@btoon/js 0.1.0 → 0.1.2

package/README.md

@@ -17,7 +17,7 @@ compression envelope and an optional HMAC-signed envelope.
   the input justifies, strict UTF-8, duplicate-key rejection, capped decompression, and
   signatures verified before anything is parsed.
 
-Version 0.1.0, implementing spec 0.1. In Node.js it is also the fastest BTOON package: on
+Implements spec 0.1. In Node.js it is also the fastest BTOON package: on
 10,000 records it encodes in 1.1 ms and decodes in 1.6 ms, against 7.8 ms and 7.1 ms for
 the native [`btoon`](https://github.com/BTOON-project/btoon-nodejs) addon, with
 byte-identical output.
@@ -94,13 +94,20 @@ API; they differ only in which synchronous codecs are built in.
 | `decode` of Brotli / Zstandard | `node:zlib` (Zstandard from Node.js 22.15) | `options.codecs` |
 | `encode` with `compress` | zlib, Brotli, Zstandard via `node:zlib` | `options.codecs`, otherwise `unsupported_compression` (use `encodeAsync`) |
 | HMAC in `encode`/`decode` | `node:crypto` | built-in pure-JS SHA-256 |
-| `encodeAsync` / `decodeAsync` compression | `CompressionStream` / `DecompressionStream` where the runtime supports the format, else the synchronous codecs | the same |
+| `encodeAsync` compression | `CompressionStream` where the runtime supports the format, else `node:zlib` | `CompressionStream` where the runtime supports the format |
+| `decodeAsync` decompression | `node:zlib` on its thread pool | the pure-JS inflate for zlib; Brotli through `DecompressionStream` where it proves strict (see below) |
 | `encodeAsync` / `decodeAsync` HMAC | WebCrypto (`crypto.subtle`), else `node:crypto` | WebCrypto, else pure JS (for example on `http://` pages) |
 | LZ4, Snappy | `options.codecs` | `options.codecs` |
 
-`DecompressionStream('deflate')` is the RFC 1950 zlib format the spec requires. Other
-formats depend on the runtime: at the time of writing, Brotli streams exist in Node.js 22+
-and Bun, and Zstandard streams in Bun.
+`decodeAsync` accepts and rejects exactly what `decode` does, because it uses the same
+decompressors: `node:zlib`'s asynchronous functions in the Node entry, and the pure-JS
+inflate in the portable entry. Only where the portable entry has no decompressor of its
+own (Brotli) does it use a `DecompressionStream`, and only after checking once that the
+runtime rejects bytes after the end of a stream: Node.js 18 to 23 accept them after a zlib
+stream (some later 22.x releases excepted), and Node.js 22 and 24 after a Brotli stream. Zstandard never goes through a
+`DecompressionStream`, which can't limit the window size (SPEC §6). Which formats
+`CompressionStream` supports depends on the runtime: at the time of writing, Brotli streams
+exist in Node.js 22+ and Bun, and Zstandard streams in Bun.
 
 Why a pure-JS inflate and SHA-256 in the portable entry: zlib decoding is mandatory in
 the spec and signatures are a security feature, so synchronous `decode` handles both in
@@ -183,7 +190,7 @@ Notes:
 ## API
 
 ```ts
-const VERSION: '0.1.0';
+const VERSION: '0.1.2';
 const SPEC_VERSION: '0.1';
 
 function encode(value: unknown, options?: EncodeOptions): Uint8Array;
@@ -265,7 +272,8 @@ Exceptions thrown by your own `toJSON()` methods or getters propagate unchanged.
 ## Security
 
 Decoding is designed for hostile input (SPEC §7, §9): every read is bounds-checked; arrays,
-maps and tables are checked against the remaining input before anything is allocated; the
+maps and tables are checked against the remaining input before anything is allocated, and
+grow as their elements are decoded instead of reserving what their headers announce; the
 nesting limit applies to input and output; strings are validated with a fatal
 `TextDecoder`; compressed payloads are checked against `maxDecompressedSize` before
 decompressing and stopped at their declared size while decompressing; Zstandard frames

package/dist/cjs/constants.d.ts

@@ -1,5 +1,5 @@
 /** Version of this library. */
-export declare const VERSION: "0.1.0";
+export declare const VERSION: "0.1.2";
 /** Version of the BTOON specification this library implements. */
 export declare const SPEC_VERSION: "0.1";
 export declare const EXT_TIMESTAMP = -1;

package/dist/cjs/constants.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_DATE_MS = exports.TIMESTAMP_BRAND = exports.EXT_BRAND = exports.ALGORITHM_NAMES = exports.ALGORITHM_IDS = exports.SIGNED_HEADER_SIZE = exports.COMPRESSION_HEADER_SIZE = exports.MIN_COMPRESSION_SIZE = exports.DEFAULT_MAX_DECOMPRESSED_SIZE = exports.DEFAULT_MAX_DEPTH = exports.NANOS_PER_SECOND = exports.MAX_OFFSET_MINUTES = exports.TABULAR_VERSION = exports.EXT_TABULAR = exports.EXT_F64_VECTOR = exports.EXT_F32_VECTOR = exports.EXT_BIGINT = exports.EXT_DATETIME = exports.EXT_DATE = exports.EXT_TIMESTAMP = exports.SPEC_VERSION = exports.VERSION = void 0;
 /** Version of this library. */
-exports.VERSION = '0.1.0';
+exports.VERSION = '0.1.2';
 /** Version of the BTOON specification this library implements. */
 exports.SPEC_VERSION = '0.1';
 // Extension type ids (SPEC §5).

package/dist/cjs/core.d.ts

@@ -1,8 +1,13 @@
 import { type CompressionAlgorithm, type DecodeOptions, type EncodeOptions } from './options.js';
-/** Synchronous building blocks of one environment. */
+/** Building blocks of one environment: its synchronous codecs and HMAC, and non-blocking decompressors. */
 export interface Platform {
     /** Decompressors; `size` is the declared uncompressed size (already checked against the limit). */
     readonly decompress: Readonly<Partial<Record<CompressionAlgorithm, (data: Uint8Array, size: number) => Uint8Array>>>;
+    /**
+     * Non-blocking forms of `decompress` that reach the same verdict (node:zlib on the thread
+     * pool). decodeAsync prefers them.
+     */
+    readonly decompressAsync?: Readonly<Partial<Record<CompressionAlgorithm, (data: Uint8Array, size: number) => Promise<Uint8Array>>>>;
     readonly compress: Readonly<Partial<Record<CompressionAlgorithm, (data: Uint8Array) => Uint8Array>>>;
     hmac(key: Uint8Array, parts: readonly Uint8Array[]): Uint8Array;
     equal(a: Uint8Array, b: Uint8Array): boolean;

package/dist/cjs/core.js

@@ -204,7 +204,7 @@ function decodeWith(data, options, platform) {
         if (out === undefined) {
             const builtin = platform.decompress[alg];
             if (builtin === undefined)
-                throw unavailable(alg, 'decompression', (0, web_js_1.webFormat)(alg, 'DecompressionStream') !== undefined);
+                throw unavailable(alg, 'decompression', (0, web_js_1.mayDecompressAsync)(alg));
             out = builtin(payload, size);
         }
         bytes = checkSize(out, size, alg);
@@ -259,17 +259,30 @@ async function decodeAsyncWith(data, options, platform) {
     if (env !== null) {
         const { alg, payload, size } = env;
         let out = await callCodecAsync(cfg.codecs, alg, 'decompress', [payload, size]);
-        if (out === undefined) {
-            const format = (0, web_js_1.webFormat)(alg, 'DecompressionStream');
-            const builtin = platform.decompress[alg];
-            if (format !== undefined)
-                out = await (0, web_js_1.webDecompress)(alg, format, payload, size);
-            else if (builtin !== undefined)
-                out = builtin(payload, size);
-            else
-                throw unavailable(alg, 'decompression', false);
-        }
+        if (out === undefined)
+            out = await decompressAsync(platform, alg, payload, size);
         bytes = checkSize(out, size, alg);
     }
     return (0, decode_js_1.decodeDocument)(bytes, cfg);
 }
+/**
+ * decodeAsync's decompressor. It reaches the same verdict as decode's: first the same
+ * decompressor, in its non-blocking form where there is one (node:zlib), then the synchronous
+ * one (the pure-JS inflate). A DecompressionStream is the last resort, only for a format that
+ * the runtime has shown it handles strictly, and never for zstd.
+ */
+async function decompressAsync(platform, alg, payload, size) {
+    const nonBlocking = platform.decompressAsync?.[alg];
+    if (nonBlocking !== undefined)
+        return nonBlocking(payload, size);
+    const builtin = platform.decompress[alg];
+    if (builtin !== undefined)
+        return builtin(payload, size);
+    const format = await (0, web_js_1.trustedDecompressionFormat)(alg);
+    if (format !== undefined)
+        return (0, web_js_1.webDecompress)(alg, format, payload, size);
+    if ((0, web_js_1.mayDecompressAsync)(alg)) {
+        throw (0, errors_js_1.fail)('unsupported_compression', `${alg} decompression is not available in this environment: its DecompressionStream accepts bytes after the end of a stream; pass options.codecs.${alg}`);
+    }
+    throw unavailable(alg, 'decompression', false);
+}

package/dist/cjs/decode.js

@@ -6,7 +6,8 @@ exports.validateBtoonExt = validateBtoonExt;
 // Hardened BTOON decoder (SPEC §7). Invariants:
 //  * every read is bounds-checked against `end` (no reads past the input);
 //  * containers are depth-limited (max_depth) — no unbounded recursion;
-//  * nothing is allocated beyond what the remaining input could encode.
+//  * nothing is allocated beyond what the remaining input could encode, and what containers
+//    allocate before their elements are decoded is bounded for the whole document.
 const constants_js_1 = require("./constants.js");
 const errors_js_1 = require("./errors.js");
 const utf8_js_1 = require("./utf8.js");
@@ -22,6 +23,15 @@ const fromCharCode = String.fromCharCode;
 const KEY_CACHE_SIZE = 4096;
 const KEY_CACHE_MAX_LEN = 16;
 const keyCache = new Array(KEY_CACHE_SIZE).fill(undefined);
+// Limits on what containers allocate before their elements are decoded. A header may announce
+// as many elements as there are bytes left, but nested containers announce the same bytes
+// again at every level, so trusting the counts let a 1 MiB document of 64 nested tabulars
+// build 4 GB of rows and exhaust the heap (review 2026-11-13, X1). An array, or the row list
+// of a table, reserves at most MAX_RESERVE slots, and those open at any time at most
+// RESERVE_BUDGET together; beyond that they grow as elements are decoded. Each tabular row is
+// created once its first cell has been decoded.
+const MAX_RESERVE = 1024;
+const RESERVE_BUDGET = 64 * MAX_RESERVE;
 const HEX = [];
 for (let i = 0; i < 256; i++)
     HEX.push((i < 16 ? '0' : '') + i.toString(16));
@@ -50,6 +60,8 @@ function plainBytes(b) {
 class Decoder {
     constructor(bytes, strict, maxDepth, tsObjects, bigAlways) {
         this.pos = 0;
+        /** Slots reserved by the arrays and row lists being decoded (see reserve). */
+        this.reserved = 0;
         this.bytes = plainBytes(bytes);
         this.view = new DataView(this.bytes.buffer, this.bytes.byteOffset, this.bytes.byteLength);
         this.end = this.bytes.length;
@@ -214,15 +226,26 @@ class Decoder {
         this.pos += len;
         return b;
     }
+    /**
+     * How many of the `n` elements that an array, or a table's row list, announces it may
+     * allocate up front. They are charged to the document's budget until it is complete.
+     */
+    reserve(n) {
+        const r = Math.min(n, MAX_RESERVE, RESERVE_BUDGET - this.reserved);
+        this.reserved += r;
+        return r;
+    }
     array(n, depth) {
         if (depth >= this.maxDepth)
             throw this.err('max_depth', 'maximum nesting depth exceeded');
         // Every element takes at least one byte.
         if (n > this.end - this.pos)
             throw this.err('truncated', 'array length exceeds the remaining input');
-        const a = new Array(n);
+        const r = this.reserve(n);
+        const a = new Array(r); // grows as elements beyond the reservation arrive
         for (let i = 0; i < n; i++)
             a[i] = this.value(depth + 1);
+        this.reserved -= r;
         return a;
     }
     key() {
@@ -452,7 +475,7 @@ class Decoder {
         // Each column needs at least 9 bytes: name length, type code, column length.
         if (cols > (end - p) / 9)
             throw bad('tabular column count exceeds the payload');
-        const names = new Array(cols);
+        const names = [];
         for (let c = 0; c < cols; c++) {
             if (end - p < 4)
                 throw bad('tabular payload truncated');
@@ -463,7 +486,7 @@ class Decoder {
             const name = (0, utf8_js_1.decodeUtf8)(this.bytes, p, n, this.strict);
             if (name === undefined)
                 throw this.err('invalid_utf8', 'column name is not valid UTF-8', p);
-            names[c] = name;
+            names.push(name);
             p += n;
         }
         if (new Set(names).size !== cols)
@@ -474,9 +497,10 @@ class Decoder {
         // Every cell is at least one byte.
         if (rowCount * cols > end - p)
             throw bad('tabular row count exceeds the payload');
-        const rows = new Array(rowCount);
-        for (let r = 0; r < rowCount; r++)
-            rows[r] = {};
+        // Each row is created once its first cell has been decoded, so the rows are backed by
+        // input actually consumed, however many the header announces.
+        const reserved = this.reserve(rowCount);
+        const rows = new Array(reserved);
         const savedEnd = this.end;
         for (let c = 0; c < cols; c++) {
             if (end - p < 4)
@@ -490,7 +514,15 @@ class Decoder {
             this.pos = p;
             this.end = colEnd;
             try {
-                if (name === '__proto__') {
+                if (c === 0) {
+                    for (let r = 0; r < rowCount; r++) {
+                        const v = this.value(depth + 2);
+                        const row = {};
+                        setProperty(row, name, v);
+                        rows[r] = row;
+                    }
+                }
+                else if (name === '__proto__') {
                     for (let r = 0; r < rowCount; r++)
                         setProperty(rows[r], name, this.value(depth + 2));
                 }
@@ -510,6 +542,7 @@ class Decoder {
             p = colEnd;
         }
         this.end = savedEnd;
+        this.reserved -= reserved;
         if (p !== end)
             throw bad('trailing bytes in tabular payload');
         this.pos = end;

package/dist/cjs/index.d.ts

@@ -60,9 +60,12 @@ export declare function decode(data: BinaryInput, options?: DecodeOptions): unkn
  */
 export declare function encodeAsync(value: unknown, options?: EncodeOptions): Promise<Uint8Array<ArrayBuffer>>;
 /**
- * Like {@link decode}, but decompresses with `DecompressionStream` (when the runtime
- * supports the algorithm) and verifies signatures with `crypto.subtle.verify`, falling back
- * to the synchronous implementations. The input is copied first, so the caller may reuse
- * its buffer immediately. Rejects with a {@link BtoonError}.
+ * Like {@link decode}, but asynchronous. In the Node.js entry, decompression runs on the
+ * `node:zlib` thread pool. In the portable entry, zlib uses the same pure-JS inflate as
+ * `decode`, and Brotli can also be decompressed with a `DecompressionStream` where the runtime
+ * has shown that it rejects bytes after the end of a stream (never Zstandard, whose window
+ * size it can't bound). Signatures are verified with `crypto.subtle.verify` where available.
+ * `decodeAsync` never accepts a document that `decode` rejects. The input is copied first, so
+ * the caller may reuse its buffer immediately. Rejects with a {@link BtoonError}.
  */
 export declare function decodeAsync(data: BinaryInput, options?: DecodeOptions): Promise<unknown>;

package/dist/cjs/index.js

@@ -76,10 +76,13 @@ function encodeAsync(value, options) {
     return (0, core_js_1.encodeAsyncWith)(value, options, platform_portable_js_1.portablePlatform);
 }
 /**
- * Like {@link decode}, but decompresses with `DecompressionStream` (when the runtime
- * supports the algorithm) and verifies signatures with `crypto.subtle.verify`, falling back
- * to the synchronous implementations. The input is copied first, so the caller may reuse
- * its buffer immediately. Rejects with a {@link BtoonError}.
+ * Like {@link decode}, but asynchronous. In the Node.js entry, decompression runs on the
+ * `node:zlib` thread pool. In the portable entry, zlib uses the same pure-JS inflate as
+ * `decode`, and Brotli can also be decompressed with a `DecompressionStream` where the runtime
+ * has shown that it rejects bytes after the end of a stream (never Zstandard, whose window
+ * size it can't bound). Signatures are verified with `crypto.subtle.verify` where available.
+ * `decodeAsync` never accepts a document that `decode` rejects. The input is copied first, so
+ * the caller may reuse its buffer immediately. Rejects with a {@link BtoonError}.
  */
 function decodeAsync(data, options) {
     return (0, core_js_1.decodeAsyncWith)(data, options, platform_portable_js_1.portablePlatform);

package/dist/cjs/node.d.ts

@@ -56,9 +56,12 @@ export declare function decode(data: BinaryInput, options?: DecodeOptions): unkn
  */
 export declare function encodeAsync(value: unknown, options?: EncodeOptions): Promise<Uint8Array<ArrayBuffer>>;
 /**
- * Like {@link decode}, but decompresses with `DecompressionStream` (when the runtime
- * supports the algorithm) and verifies signatures with `crypto.subtle.verify`, falling back
- * to the synchronous implementations. The input is copied first, so the caller may reuse
- * its buffer immediately. Rejects with a {@link BtoonError}.
+ * Like {@link decode}, but asynchronous. In the Node.js entry, decompression runs on the
+ * `node:zlib` thread pool. In the portable entry, zlib uses the same pure-JS inflate as
+ * `decode`, and Brotli can also be decompressed with a `DecompressionStream` where the runtime
+ * has shown that it rejects bytes after the end of a stream (never Zstandard, whose window
+ * size it can't bound). Signatures are verified with `crypto.subtle.verify` where available.
+ * `decodeAsync` never accepts a document that `decode` rejects. The input is copied first, so
+ * the caller may reuse its buffer immediately. Rejects with a {@link BtoonError}.
  */
 export declare function decodeAsync(data: BinaryInput, options?: DecodeOptions): Promise<unknown>;

package/dist/cjs/node.js

@@ -72,10 +72,13 @@ function encodeAsync(value, options) {
     return (0, core_js_1.encodeAsyncWith)(value, options, platform_node_js_1.nodePlatform);
 }
 /**
- * Like {@link decode}, but decompresses with `DecompressionStream` (when the runtime
- * supports the algorithm) and verifies signatures with `crypto.subtle.verify`, falling back
- * to the synchronous implementations. The input is copied first, so the caller may reuse
- * its buffer immediately. Rejects with a {@link BtoonError}.
+ * Like {@link decode}, but asynchronous. In the Node.js entry, decompression runs on the
+ * `node:zlib` thread pool. In the portable entry, zlib uses the same pure-JS inflate as
+ * `decode`, and Brotli can also be decompressed with a `DecompressionStream` where the runtime
+ * has shown that it rejects bytes after the end of a stream (never Zstandard, whose window
+ * size it can't bound). Signatures are verified with `crypto.subtle.verify` where available.
+ * `decodeAsync` never accepts a document that `decode` rejects. The input is copied first, so
+ * the caller may reuse its buffer immediately. Rejects with a {@link BtoonError}.
  */
 function decodeAsync(data, options) {
     return (0, core_js_1.decodeAsyncWith)(data, options, platform_node_js_1.nodePlatform);

package/dist/cjs/platform-node.js

@@ -45,80 +45,115 @@ function nodeFn(name) {
 function plain(b) {
     return new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
 }
-/**
- * Wraps a node:zlib `*Sync` decompressor: output is capped at the declared size
- * (`maxOutputLength`), and input left over after the end of the stream is rejected.
- */
+/** node:zlib options: output capped at the declared size, and `info` to learn how much input was consumed. */
+function options(size, extra) {
+    return { ...extra?.(size), info: true, maxOutputLength: Math.max(1, size) };
+}
+function failure(alg, e) {
+    if (e.code === 'ERR_BUFFER_TOO_LARGE') {
+        return (0, errors_js_1.fail)('invalid_envelope', `${alg} payload decompresses to more than the declared size`, e);
+    }
+    return (0, errors_js_1.fail)('invalid_envelope', `${alg} payload is corrupt: ${e.message}`, e);
+}
+/** The output of a node:zlib decompressor, once it is clear that the stream used the whole payload. */
+function output(alg, data, size, r) {
+    let out;
+    let consumed;
+    if (r instanceof Uint8Array) {
+        out = r;
+    }
+    else {
+        const info = r;
+        out = info.buffer;
+        consumed = info.engine?.bytesWritten;
+    }
+    if (typeof consumed !== 'number') {
+        // A runtime that doesn't report the input it consumed can't show that no bytes follow the
+        // stream (SPEC §6). zlib has an exact pure-JS decoder; the other algorithms don't.
+        if (alg === 'zlib')
+            return (0, inflate_js_1.inflateZlib)(data, size);
+        throw (0, errors_js_1.fail)('unsupported_compression', `${alg} decompression in this runtime cannot detect trailing bytes; pass options.codecs.${alg}`);
+    }
+    if (consumed !== data.length)
+        throw (0, errors_js_1.fail)('invalid_envelope', `${alg} payload has trailing bytes`);
+    return plain(out);
+}
+/** Wraps a node:zlib `*Sync` decompressor, for decode. */
 function decompressor(alg, fn, extra) {
     if (fn === undefined)
         return undefined;
     return (data, size) => {
         let r;
         try {
-            r = fn(data, { ...extra?.(size), info: true, maxOutputLength: Math.max(1, size) });
+            r = fn(data, options(size, extra));
         }
         catch (e) {
-            if (e.code === 'ERR_BUFFER_TOO_LARGE') {
-                throw (0, errors_js_1.fail)('invalid_envelope', `${alg} payload decompresses to more than the declared size`, e);
-            }
-            throw (0, errors_js_1.fail)('invalid_envelope', `${alg} payload is corrupt: ${e.message}`, e);
-        }
-        let out;
-        let consumed;
-        if (r instanceof Uint8Array) {
-            out = r;
-        }
-        else {
-            const info = r;
-            out = info.buffer;
-            consumed = info.engine?.bytesWritten;
-        }
-        if (typeof consumed === 'number') {
-            if (consumed !== data.length)
-                throw (0, errors_js_1.fail)('invalid_envelope', `${alg} payload has trailing bytes`);
+            throw failure(alg, e);
         }
-        else if (alg === 'zlib') {
-            // A runtime that doesn't report consumed input: the stream must end in its Adler-32.
-            const n = data.length;
-            const trailer = n >= 4 ? ((data[n - 4] << 24) | (data[n - 3] << 16) | (data[n - 2] << 8) | data[n - 1]) >>> 0 : -1;
-            if (trailer !== (0, inflate_js_1.adler32)(out))
-                throw (0, errors_js_1.fail)('invalid_envelope', 'zlib payload has trailing bytes');
-        }
-        return plain(out);
+        return output(alg, data, size, r);
     };
 }
-function compressor(fn, options) {
+/**
+ * Wraps the callback form of the same node:zlib decompressor, for decodeAsync: it runs on the
+ * thread pool, with the same limits and checks, so both give the same verdict.
+ */
+function asyncDecompressor(alg, fn, extra) {
+    if (fn === undefined)
+        return undefined;
+    return (data, size) => new Promise((resolve, reject) => {
+        fn(data, options(size, extra), (e, r) => {
+            if (e) {
+                reject(failure(alg, e));
+                return;
+            }
+            try {
+                resolve(output(alg, data, size, r));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    });
+}
+function compressor(fn, opts) {
     if (fn === undefined)
         return undefined;
-    return (data) => plain(fn(data, options));
+    return (data) => plain(fn(data, opts));
 }
 const decompress = {};
+const decompressAsync = {};
 const compress = {};
 decompress.zlib = decompressor('zlib', nodeFn('inflateSync'));
+decompressAsync.zlib = asyncDecompressor('zlib', nodeFn('inflate'));
 compress.zlib = compressor(nodeFn('deflateSync'), { level: 6 });
 const brotliQuality = zlib.constants?.BROTLI_PARAM_QUALITY;
 if (brotliQuality !== undefined) {
     decompress.brotli = decompressor('brotli', nodeFn('brotliDecompressSync'));
+    decompressAsync.brotli = asyncDecompressor('brotli', nodeFn('brotliDecompress'));
     compress.brotli = compressor(nodeFn('brotliCompressSync'), { params: { [brotliQuality]: 6 } });
 }
-// node:zlib has Zstandard from Node.js 22.15 / 23.8. SPEC §6: bound the decoder's memory
-// by rejecting frames whose window exceeds max(8 MiB, min(uncompressed_size, 128 MiB)).
+// node:zlib has Zstandard from Node.js 22.15 / 23.8. SPEC §6: bound the decoder's memory by
+// rejecting frames whose window exceeds max(8 MiB, min(uncompressed_size, 128 MiB)). Without
+// the windowLogMax parameter there is no bound, so zstd decompression is not offered at all.
 const zstdWindowLogMax = zlib.constants?.ZSTD_d_windowLogMax;
-decompress.zstd = decompressor('zstd', nodeFn('zstdDecompressSync'), (size) => zstdWindowLogMax === undefined
-    ? {}
-    : { params: { [zstdWindowLogMax]: Math.ceil(Math.log2(Math.max(8 << 20, Math.min(size, 128 << 20)))) } });
-compress.zstd = compressor(nodeFn('zstdCompressSync'), {});
-for (const alg of Object.keys(decompress)) {
-    if (decompress[alg] === undefined)
-        delete decompress[alg];
+if (zstdWindowLogMax !== undefined) {
+    const zstdWindow = (size) => ({
+        params: { [zstdWindowLogMax]: Math.ceil(Math.log2(Math.max(8 << 20, Math.min(size, 128 << 20)))) },
+    });
+    decompress.zstd = decompressor('zstd', nodeFn('zstdDecompressSync'), zstdWindow);
+    decompressAsync.zstd = asyncDecompressor('zstd', nodeFn('zstdDecompress'), zstdWindow);
 }
-for (const alg of Object.keys(compress)) {
-    if (compress[alg] === undefined)
-        delete compress[alg];
+compress.zstd = compressor(nodeFn('zstdCompressSync'), {});
+for (const table of [decompress, decompressAsync, compress]) {
+    for (const alg of Object.keys(table)) {
+        if (table[alg] === undefined)
+            delete table[alg];
+    }
 }
 /** Node.js (and Bun): node:zlib for zlib, Brotli and Zstandard; node:crypto for HMAC. */
 exports.nodePlatform = {
     decompress,
+    decompressAsync,
     compress,
     hmac(key, parts) {
         const h = (0, node_crypto_1.createHmac)('sha256', key);

package/dist/cjs/web.d.ts

@@ -1,12 +1,19 @@
 import type { CompressionAlgorithm } from './options.js';
 /** The Compression Streams format name for `alg`, if this runtime supports it. */
 export declare function webFormat(alg: CompressionAlgorithm, kind: 'CompressionStream' | 'DecompressionStream'): string | undefined;
+/**
+ * The DecompressionStream format that decodeAsync may use for `alg` when no other
+ * decompressor is available, or undefined: never for zstd, and only once the runtime has
+ * shown that it rejects trailing bytes.
+ */
+export declare function trustedDecompressionFormat(alg: CompressionAlgorithm): Promise<string | undefined>;
+/** Whether decodeAsync might decompress `alg` with a DecompressionStream here (for error messages). */
+export declare function mayDecompressAsync(alg: CompressionAlgorithm): boolean;
 export declare function webCompress(format: string, data: Uint8Array): Promise<Uint8Array>;
 /**
- * Decompresses with a DecompressionStream, stopping as soon as the output exceeds
- * `limit` (the declared size). For zlib it also checks that the payload ends with the
- * Adler-32 of the output: older runtimes silently ignore bytes after the end of the
- * stream, which a strict decoder must reject.
+ * Decompresses with a DecompressionStream, stopping as soon as the output exceeds `limit`
+ * (the declared size). Only for a format that trustedDecompressionFormat() returned, which
+ * rejects bytes after the end of the stream.
  */
 export declare function webDecompress(alg: CompressionAlgorithm, format: string, data: Uint8Array, limit: number): Promise<Uint8Array>;
 type Subtle = {