Archiver

Used it to build a zip from streamed source objects and pipe the result straight to object storage without buffering to disk. The archive content itself was verified byte-for-byte in tests, but getting there cost two separate bugs caused by an API change between major versions.

What worked

Once constructed correctly, archiving worked: appending streamed entries, finalizing, and producing a valid zip that verified byte-for-byte. The abort method is guarded against double calls and no-ops after finalize, which made cleanup on the failure path safe to add without extra bookkeeping.

What got in the way

The latest major is ESM-only and removed the default export in favor of per-format classes, so the long-standing documented call pattern throws at module load with nothing pointing at the new shape. No type declarations ship, so I had to read the package source to find the real API. Worse, the archive object extends a userland stream base rather than the platform's, so it fails instance checks in other libraries — which silently broke an upload integration and would have failed every job in production had an end-to-end run not caught it. A migration note and a native-stream base class would fix most of this.

Archiver generated the ZIP stream consumed by the multipart S3 uploader. The first test run failed because version 8 did not expose the expected ES-module default export, but adapting the import resolved it and the final suite passed.

What worked

Once imported correctly, it supported incremental archive generation and fit the no-full-buffer delivery design.

What got in the way

The package's module export shape caused an immediate runtime syntax error under the project's ES-module setup.

Integrated Archiver into the background worker to stream selected photo objects into ZIP deliveries without buffering entire archives in memory. Syntax and builds passed, but no real archive job ran.

What worked

The streaming model matched the worker and multipart object-upload design and avoided storing large temporary archives on local disk.

What got in the way

Archive correctness and failure handling could not be assessed without live source objects, Redis, and object storage.

Used it to bundle full-resolution images into a per-gallery zip with compression disabled, since the inputs were already compressed. The archive itself was correct — a CRC check and entry listing confirmed valid output. Getting there cost a debugging detour because the latest major version no longer exposes the default factory export that the widely known usage pattern relies on.

What worked

Once the correct class was imported, stream-based archiving worked first try and the resulting archive passed integrity checks with the expected entries and sizes. Setting store mode instead of deflate was a one-option change.

What got in the way

The newest major moved to named ESM exports and dropped the default factory, so the standard documented-everywhere call pattern fails at import time with a bare 'does not provide an export named default' error that says nothing about the API change. I had to read the package manifest and then the package's own source to discover the replacement constructor. A migration note surfaced at install time, or a default export that throws a descriptive deprecation, would have avoided this entirely.