Refactor: use standard web streams (#1)

Author: gordonmleigh

.c8rc

@@ -0,0 +1,5 @@
+{
+  "all": true,
+  "exclude": ["*.js", "*.d.ts", "**/*.test.ts", "types/"],
+  "reporter": ["text", "lcovonly"]
+}

.github/workflows/pr.yaml

@@ -13,7 +13,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: "22.x"
+          node-version-file: ".node-version"
           cache: "npm"
           registry-url: "https://registry.npmjs.org"
 

.github/workflows/release.yaml

@@ -24,7 +24,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: "22.x"
+          node-version-file: ".node-version"
           cache: "npm"
           registry-url: "https://registry.npmjs.org"
 

.node-version

@@ -0,0 +1 @@
+24.0.1

.vscode/settings.json

@@ -6,6 +6,12 @@
   },
   "eslint.useFlatConfig": true,
   "typescript.tsdk": "node_modules/typescript/lib",
-  "cSpell.words": ["decompressors"],
-  "code-coverage-lcov.path.searchPath": "coverage/lcov.info"
+  "cSpell.words": ["decompressors", "eocdl", "eocdr"],
+  "code-coverage-lcov.path.searchPath": "coverage/lcov.info",
+  "nodejs-testing.extensions": [
+    {
+      "extensions": ["ts"],
+      "parameters": []
+    }
+  ]
 }

CHANGELOG.md

@@ -2,35 +2,31 @@
 
 ## [0.1.7](https://github.com/gordonmleigh/zip24/compare/v0.1.6...v0.1.7) (2025-03-25)
 
-
 ### Fix
 
-* DataView is now generic ([a030c33](https://github.com/gordonmleigh/zip24/commit/a030c33d5d94c274421f4b1868d35acdf09ebecb))
+- DataView is now generic ([a030c33](https://github.com/gordonmleigh/zip24/commit/a030c33d5d94c274421f4b1868d35acdf09ebecb))
 
 ## [0.1.6](https://github.com/gordonmleigh/zip24/compare/v0.1.4...v0.1.6) (2024-10-05)
 
-
 ### Chore
 
-* add helpful error in core compress ([574b59d](https://github.com/gordonmleigh/zip24/commit/574b59d77834cdf4e93f88585914a0e66090179d))
-* improve tests for writers ([b2f21d8](https://github.com/gordonmleigh/zip24/commit/b2f21d88b42e66a43c0979e1fe5ac33e9c2c7407))
-* make DoubleEndedBuffer unconstrained ([d0a0c2d](https://github.com/gordonmleigh/zip24/commit/d0a0c2d23077e5aadeb789f62b405025790488c1))
-* version bump ([4556969](https://github.com/gordonmleigh/zip24/commit/4556969b31c08617a1772ad94d028b0912a6714e))
+- add helpful error in core compress ([574b59d](https://github.com/gordonmleigh/zip24/commit/574b59d77834cdf4e93f88585914a0e66090179d))
+- improve tests for writers ([b2f21d8](https://github.com/gordonmleigh/zip24/commit/b2f21d88b42e66a43c0979e1fe5ac33e9c2c7407))
+- make DoubleEndedBuffer unconstrained ([d0a0c2d](https://github.com/gordonmleigh/zip24/commit/d0a0c2d23077e5aadeb789f62b405025790488c1))
+- version bump ([4556969](https://github.com/gordonmleigh/zip24/commit/4556969b31c08617a1772ad94d028b0912a6714e))
 
 ## [0.1.4](https://github.com/gordonmleigh/zip24/compare/v0.1.3...v0.1.4) (2024-10-04)
 
-
 ### Build
 
-* publish provenance attestations ([18c38c0](https://github.com/gordonmleigh/zip24/commit/18c38c078ed2ae5abe4a59d0352e1dd69192b1d3))
-* publish to npm automatically ([3e1949c](https://github.com/gordonmleigh/zip24/commit/3e1949cf2e1cc978c97f97ce1cfe2472ba12e217))
+- publish provenance attestations ([18c38c0](https://github.com/gordonmleigh/zip24/commit/18c38c078ed2ae5abe4a59d0352e1dd69192b1d3))
+- publish to npm automatically ([3e1949c](https://github.com/gordonmleigh/zip24/commit/3e1949cf2e1cc978c97f97ce1cfe2472ba12e217))
 
 ## [0.1.3](https://github.com/gordonmleigh/zip24/compare/v0.1.0...v0.1.3) (2024-10-04)
 
-
 ### Build
 
-* add build script ([4e9da64](https://github.com/gordonmleigh/zip24/commit/4e9da64a430f7eebd566246b41f1aaa019baa196))
-* add GitHub Actions workflow ([c5943aa](https://github.com/gordonmleigh/zip24/commit/c5943aadfc82a3b19dd270bdaccc65ba68a71613))
-* add release-it ([028f241](https://github.com/gordonmleigh/zip24/commit/028f241c0fb8abde53ed82667cc37abe236a654e))
-* upgrade linting ([03bd772](https://github.com/gordonmleigh/zip24/commit/03bd772bc6b76b58cd00be67da4849fe0892cd87))
+- add build script ([4e9da64](https://github.com/gordonmleigh/zip24/commit/4e9da64a430f7eebd566246b41f1aaa019baa196))
+- add GitHub Actions workflow ([c5943aa](https://github.com/gordonmleigh/zip24/commit/c5943aadfc82a3b19dd270bdaccc65ba68a71613))
+- add release-it ([028f241](https://github.com/gordonmleigh/zip24/commit/028f241c0fb8abde53ed82667cc37abe236a654e))
+- upgrade linting ([03bd772](https://github.com/gordonmleigh/zip24/commit/03bd772bc6b76b58cd00be67da4849fe0892cd87))

README.md

@@ -82,6 +82,10 @@ Nope! Reading a zip forwards from start to finish is something that the zip form
 
 ## Writing Zips
 
+### With `ZipWriter.open()`
+
+You can use `ZipWriter.open()` on Node.js to write directly to a file:
+
 ```ts
 import { ZipWriter } from "zip24/writer";
 
@@ -106,9 +110,28 @@ await writer.addFile(
   "this will be stored as-is",
 );
 
-await writer.finalize("Gordon is cool");
+await writer.close();
 ```
 
+### With `destination` option
+
+You can also output to any writer you'd like. On Node, [`Writable`](https://nodejs.org/api/stream.html#class-streamwritable) is also supported as a destination. Note that the destination must be an instance of `Writable`, not just "Writable-like".
+
+```ts
+import { ZipWriter } from "zip24/writer";
+
+const destination = createWritableStreamSomehow();
+const writer = new ZipWriter({ destination });
+
+// etc
+
+await writer.close();
+```
+
+### With streams
+
+`ZipWriter` is also a [TransformStream](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream), so you can pipe `ZipEntry`/`ZipEntryInfo` instances in and pipe the output to a stream of your choice.
+
 ## About this library
 
 ### Why `zip24`?

docs/records.md

@@ -97,7 +97,8 @@ This record has an optional signature value of `0x08074b50` which precedes the o
 | 32     | total entries on all disks    | 8    |
 | 40     | size of the central directory | 8    |
 | 48     | central directory offset      | 8    |
-| 56     | (end)                         |      |
+| 56     | extensible data sector        | ...  |
+| ...    | (56 + record size - 12)       |      |
 
 ## Zip64 End of Central Directory Locator (4.3.15)
 

eslint.config.js

@@ -1,24 +1,53 @@
-import config from "@propulsionworks/eslint-config";
+import propulsionworks, { config } from "@propulsionworks/eslint-config";
 
-export default [
-  config.configs["base"],
-  config.configs["ts"],
+export default config(
   {
+    ignores: ["node_modules/", "lib/", "eslint.config.js"],
+  },
+  {
+    files: ["**/*.js", "**/*.ts"],
+    extends: [propulsionworks.configs.js],
+  },
+  {
+    files: ["**/*.ts"],
+    extends: [propulsionworks.configs.ts],
     rules: {
-      //"unicorn/no-unused-properties": "warn",
-      "unicorn/number-literal-case": "off", // fights with prettier
-      "unicorn/numeric-separators-style": "off", // annoying
+      // we can turn this off due to the other rules that stop us abusing `any`
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { ignoreRestSiblings: true },
+      ],
+      "@typescript-eslint/unified-signatures": [
+        "error",
+        {
+          ignoreDifferentlyNamedParameters: true,
+          ignoreOverloadsWithDifferentJSDoc: true,
+        },
+      ],
+      "n/no-unsupported-features/node-builtins": "off",
     },
   },
   {
-    files: ["src/**/*.test.*"],
+    files: ["**/*.test.ts"],
+    extends: [propulsionworks.configs["ts-relaxed-any"]],
 
     rules: {
-      "@typescript-eslint/no-floating-promises": "off", // `describe` and `it` return promises
+      // `describe` and `it` return promises
+      "@typescript-eslint/no-floating-promises": [
+        "warn",
+        {
+          allowForKnownSafeCalls: [
+            { from: "package", name: ["describe", "it"], package: "node:test" },
+          ],
+        },
+      ],
+
       "@typescript-eslint/no-non-null-asserted-optional-chain": "off", // easier for testing
       "@typescript-eslint/no-non-null-assertion": "off", // easier for testing
-      "n/no-unsupported-features/node-builtins": "off", // so we can use node:test
+      "@typescript-eslint/no-unused-vars": "off", // easier for testing
+      "@typescript-eslint/require-await": "off", // easier for testing
       "unicorn/no-abusive-eslint-disable": "off",
     },
   },
-];
+);

src/web/buffer.test.ts exports/buffer.test.tssrc/web/buffer.test.ts renamed to exports/buffer.test.ts

@@ -1,16 +1,15 @@
 import assert from "node:assert";
-import { buffer } from "node:stream/consumers";
+import { buffer, text } from "node:stream/consumers";
 import { describe, it, mock } from "node:test";
-import { CompressionMethod } from "../core/compression-core.js";
-import { ZipPlatform, ZipVersion } from "../core/constants.js";
-import { UnixFileAttributes } from "../core/file-attributes.js";
-import { ZipEntry } from "../core/zip-entry.js";
 import {
   EmptyZip32,
   Zip32WithThreeEntries,
   generateZip,
-} from "../test-util/fixtures.js";
-import { ZipBufferReader } from "./buffer.js";
+} from "../test-util/fixtures.ts";
+import { ZipBufferReader } from "./buffer.ts";
+import { ZipEntry, ZipEntryReader } from "./entry.ts";
+import { CompressionMethod, ZipPlatform, ZipVersion } from "./raw/constants.ts";
+import { UnixFileAttributes } from "./raw/file-attributes.ts";
 
 describe("web/buffer", () => {
   describe("ZipBufferReader", () => {
@@ -44,7 +43,7 @@ describe("web/buffer", () => {
       it("iterates all the files", async () => {
         const reader = new ZipBufferReader(Zip32WithThreeEntries);
 
-        const files: ZipEntry[] = [];
+        const files: ZipEntryReader[] = [];
         for (const file of reader.filesSync()) {
           files.push(file);
         }
@@ -80,7 +79,7 @@ describe("web/buffer", () => {
         assert.strictEqual(file0.isDirectory, false);
         assert.strictEqual(file0.isFile, true);
 
-        assert.strictEqual(await file0.toText(), "this is the file 1 content");
+        assert.strictEqual(await text(file0), "this is the file 1 content");
 
         //// FILE 1
         const file1 = files[1];
@@ -111,10 +110,7 @@ describe("web/buffer", () => {
         assert.strictEqual(file1.isDirectory, false);
         assert.strictEqual(file1.isFile, true);
 
-        assert.strictEqual(
-          await file1.toText(),
-          "file 2 content goes right here",
-        );
+        assert.strictEqual(await text(file1), "file 2 content goes right here");
 
         //// FILE 2
         const file2 = files[2];
@@ -144,7 +140,7 @@ describe("web/buffer", () => {
         assert.strictEqual(file2.isDirectory, true);
         assert.strictEqual(file2.isFile, false);
 
-        assert.strictEqual(await file2.toText(), "");
+        assert.strictEqual(await text(file2), "");
       });
     });