initial commit

.vscode/settings.json

···
+{
+	"editor.defaultFormatter": "denoland.vscode-deno",
+	"deno.enable": true
+}

.zed/settings.json

···
+{
+	"lsp": {
+		"deno": {
+			"settings": {
+				"deno": {
+					"enable": true
+				}
+			}
+		}
+	},
+	"languages": {
+		"JavaScript": {
+			"language_servers": [
+				"deno",
+				"!typescript-language-server",
+				"!vtsls",
+				"!eslint"
+			],
+			"formatter": "language_server"
+		},
+		"TypeScript": {
+			"language_servers": [
+				"deno",
+				"!typescript-language-server",
+				"!vtsls",
+				"!eslint"
+			],
+			"formatter": "language_server"
+		},
+		"TSX": {
+			"language_servers": [
+				"deno",
+				"!typescript-language-server",
+				"!vtsls",
+				"!eslint"
+			],
+			"formatter": "language_server"
+		}
+	}
+}

LICENSE

···
+BSD Zero Clause License
+
+Copyright (c) 2025 Mary
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

README.md

···
+# zip
+
+[JSR](https://jsr.io/@mary/zip) | [source code](https://tangled.sh/@mary.my.id/pkg-zip)
+
+streaming zip archiver/extractor
+
+```ts
+{
+	const iterable = ReadableStream.from(
+		zip([
+			{ name: 'README.md', data: `Hello, **world**!` },
+		]),
+	);
+}
+```

deno.json

···
+{
+	"name": "@mary/zip",
+	"version": "0.1.0",
+	"license": "0BSD",
+	"exports": {
+		".": "./lib/mod.ts",
+		"./deno": "./lib/reader/deno.ts",
+		"./node": "./lib/reader/node.ts"
+	},
+	"fmt": {
+		"useTabs": true,
+		"indentWidth": 2,
+		"lineWidth": 110,
+		"semiColons": true,
+		"singleQuote": true
+	},
+	"publish": {
+		"include": ["lib/", "LICENSE", "README.md", "deno.json"]
+	},
+	"imports": {
+		"@mary/date-fns": "jsr:@mary/date-fns@^0.1.3",
+		"@mary/ds-circular-buffer": "jsr:@mary/ds-circular-buffer@^0.1.0",
+		"@mary/ds-queue": "jsr:@mary/ds-queue@^0.1.3",
+		"@mary/mutex": "jsr:@mary/mutex@^0.1.0"
+	}
+}

deno.lock

···
+{
+  "version": "5",
+  "specifiers": {
+    "jsr:@mary/date-fns@~0.1.3": "0.1.3",
+    "jsr:@mary/ds-circular-buffer@0.1": "0.1.0",
+    "jsr:@mary/ds-queue@~0.1.3": "0.1.3",
+    "jsr:@mary/mutex@0.1": "0.1.0",
+    "npm:@types/node@*": "24.1.0"
+  },
+  "jsr": {
+    "@mary/date-fns@0.1.3": {
+      "integrity": "16dea8b5e45de5de6a442555e171544d4e565b8abc325a0ef86f5f6d04ba0c38"
+    },
+    "@mary/ds-circular-buffer@0.1.0": {
+      "integrity": "51c463436ffd625979bcd1fc63860c2d6a48f289e2d414b72a3ad95689ce4481"
+    },
+    "@mary/ds-queue@0.1.3": {
+      "integrity": "a743caa397b924cb08b0bbdffc526eb1ea2d3fc9e675da6edc137c437fc93c76"
+    },
+    "@mary/mutex@0.1.0": {
+      "integrity": "491d33bfd019f5467fd33cf75fcad293800c9954d76332865747201cbeecb0fc"
+    }
+  },
+  "npm": {
+    "@types/node@24.1.0": {
+      "integrity": "sha512-ut5FthK5moxFKH2T1CUOC6ctR67rQRvvHdFLCD2Ql6KXmMuCrjsSsRI9UsLCm9M18BMwClv4pn327UvB7eeO1w==",
+      "dependencies": [
+        "undici-types"
+      ]
+    },
+    "undici-types@7.8.0": {
+      "integrity": "sha512-9UJ2xGDvQ43tYyVMpuHlsgApydB8ZKfVYTsLDhXkFL/6gfkp+U8xTGdh8pMJv1SpZna0zxG1DwsKZsreLbXBxw=="
+    }
+  },
+  "workspace": {
+    "dependencies": [
+      "jsr:@mary/date-fns@~0.1.3",
+      "jsr:@mary/ds-circular-buffer@0.1",
+      "jsr:@mary/ds-queue@~0.1.3",
+      "jsr:@mary/mutex@0.1"
+    ]
+  }
+}

lib/mod.ts

···
+export * from './zip.ts';
+export * from './unzip.ts';
+
+export type * from './reader/types.ts';
+export * from './reader/common.ts';

lib/reader/common.ts

···
+import type { Reader } from './types.ts';
+
+/**
+ * creates a reader from a Uint8Array
+ * @param data the data to read from
+ * @returns a reader for the data
+ */
+export function fromUint8Array(data: Uint8Array): Reader {
+	const totalLength = data.length;
+
+	return {
+		length: totalLength,
+		// deno-lint-ignore require-await
+		async read(offset: number, length?: number): Promise<ReadableStream<Uint8Array>> {
+			const endOffset = length !== undefined ? offset + length : totalLength;
+
+			const slice = data.subarray(offset, endOffset);
+			const sliceLength = slice.length;
+
+			let position = 0;
+
+			return new ReadableStream<Uint8Array>({
+				pull(controller) {
+					if (position >= sliceLength) {
+						controller.close();
+						return;
+					}
+
+					const size = Math.min(controller.desiredSize!, sliceLength - position);
+					const chunk = slice.subarray(position, position + size);
+
+					controller.enqueue(chunk);
+					position += size;
+
+					if (position >= sliceLength) {
+						controller.close();
+						return;
+					}
+				},
+			}, new ByteLengthQueuingStrategy({ highWaterMark: 64 * 1024 }));
+		},
+	};
+}
+
+export interface FetchReaderOptions {
+	input: string | URL | Request;
+	fetch?: typeof fetch;
+}
+
+/**
+ * creates a reader from a fetch URL or Request
+ * @param input URL string or Request object to fetch from
+ * @returns a reader for the remote resource
+ */
+export async function fromFetch(opts: FetchReaderOptions): Promise<Reader> {
+	const thisFetch = opts.fetch ?? fetch;
+
+	const totalLength = await (async () => {
+		// make a HEAD request to get content length upfront
+		const response = await thisFetch(opts.input, { method: 'HEAD' });
+		if (!response.ok) {
+			throw new Error(`failed to fetch resource: http ${response.status}`);
+		}
+
+		const raw = response.headers.get('content-length');
+		if (raw === null) {
+			throw new Error(`content-length header not available`);
+		}
+
+		const value = parseInt(raw, 10);
+		if (isNaN(value)) {
+			throw new Error(`invalid content-length header`);
+		}
+
+		return value;
+	})();
+
+	return {
+		length: totalLength,
+		async read(offset: number, length?: number): Promise<ReadableStream<Uint8Array>> {
+			const endOffset = length !== undefined ? offset + length - 1 : totalLength - 1;
+
+			const req = opts.input;
+			const headers = new Headers(req instanceof Request ? req.headers : undefined);
+			headers.set('range', `bytes=${offset}-${endOffset}`);
+
+			const response = await thisFetch(req, { headers });
+
+			if (!response.ok) {
+				throw new Error(`failed to fetch range ${offset}-${endOffset}: http ${response.status}`);
+			}
+
+			if (response.status !== 206) {
+				throw new Error(`server does not support range requests`);
+			}
+
+			if (response.body === null) {
+				throw new Error(`response body is null`);
+			}
+
+			return response.body;
+		},
+	};
+}

lib/reader/deno.ts

···
+import Mutex from '@mary/mutex';
+
+import type { Reader } from './types.ts';
+
+/**
+ * creates a reader from a Deno.FsFile
+ * @param file the file to read from
+ * @returns a reader for the file
+ */
+export async function fromFsFile(file: Deno.FsFile): Promise<Reader & Disposable> {
+	const mutex = new Mutex();
+	const totalLength = (await file.stat()).size;
+
+	return {
+		length: totalLength,
+		// deno-lint-ignore require-await
+		async read(offset: number, length?: number): Promise<ReadableStream<Uint8Array>> {
+			let remaining = length !== undefined ? length : totalLength - offset;
+
+			return new ReadableStream<Uint8Array>({
+				type: 'bytes',
+				async pull(controller) {
+					using _lock = await mutex.acquire();
+
+					await file.seek(offset, Deno.SeekMode.Start);
+
+					const size = Math.min(controller.desiredSize!, remaining);
+
+					const buffer = new Uint8Array(size);
+					const read = await file.read(buffer);
+
+					if (read === null) {
+						// end of file
+						controller.close();
+						return;
+					}
+
+					if (read < size) {
+						// partial read, slice the buffer
+						controller.enqueue(buffer.subarray(0, read));
+					} else {
+						controller.enqueue(buffer);
+					}
+
+					remaining -= read;
+					offset += read;
+
+					if (remaining <= 0) {
+						controller.close();
+						return;
+					}
+				},
+			}, { highWaterMark: 64 * 1024 });
+		},
+		[Symbol.dispose]() {
+			file.close();
+		},
+	};
+}

lib/reader/node.ts

···
+import type { FileHandle } from 'node:fs/promises';
+
+import type { Reader } from './types.ts';
+
+/**
+ * creates a reader from a Node.js' FileHandle
+ * @param handle the file handle to read from
+ * @returns a reader for the file
+ */
+export const fromFileHandle = async (handle: FileHandle): Promise<Reader> => {
+	const totalLength = (await handle.stat()).size;
+
+	return {
+		length: totalLength,
+		// deno-lint-ignore require-await
+		async read(offset: number, length?: number): Promise<ReadableStream<Uint8Array>> {
+			let remaining = length !== undefined ? length : totalLength - offset;
+
+			return new ReadableStream<Uint8Array>({
+				type: 'bytes',
+				async pull(controller) {
+					const size = Math.min(controller.desiredSize!, remaining);
+
+					const buffer = new Uint8Array(size);
+					const { bytesRead } = await handle.read(buffer, 0, size, offset);
+
+					if (bytesRead === 0) {
+						// end of file
+						controller.close();
+						return;
+					}
+
+					if (bytesRead < size) {
+						// partial read, slice the buffer
+						controller.enqueue(buffer.subarray(0, bytesRead));
+					} else {
+						controller.enqueue(buffer);
+					}
+
+					remaining -= bytesRead;
+					offset += bytesRead;
+
+					if (remaining <= 0) {
+						controller.close();
+						return;
+					}
+				},
+			}, { highWaterMark: 64 * 1024 });
+		},
+	};
+};

lib/reader/types.ts

···
+/**
+ * interface for reading data from a zip source
+ */
+export interface Reader {
+	/** total length of the data source */
+	length: number;
+	/** reads data from the specified offset and length */
+	read(offset: number, length?: number): Promise<ReadableStream<Uint8Array>>;
+}

lib/unzip.ts

···
+import CircularBuffer from '@mary/ds-circular-buffer';
+
+import { decodeUtf8From, read } from './utils/buffer.ts';
+import { cache } from './utils/decorator.ts';
+import { StreamReader } from './utils/stream-reader.ts';
+
+import type { Reader } from './reader/types.ts';
+
+const EOCD_FIXED_SIZE = 22;
+const CRECORD_FIXED_SIZE = 46;
+const LHEADER_FIXED_SIZE = 30;
+
+function readUint16LE(view: DataView, offset: number): number {
+	return view.getUint16(offset, true);
+}
+
+function readUint32LE(view: DataView, offset: number): number {
+	return view.getUint32(offset, true);
+}
+
+/**
+ * represents a single entry in a zip archive during extraction
+ */
+export class UnzippedEntry {
+	readonly #reader: Reader;
+
+	readonly #recordFixed: Uint8Array;
+	readonly #recordVariable: Uint8Array;
+
+	readonly #headerOffset: number;
+
+	/** @ignore */
+	constructor(reader: Reader, recordFixed: Uint8Array, recordVariable: Uint8Array, headerOffset: number) {
+		this.#reader = reader;
+
+		this.#recordFixed = recordFixed;
+		this.#recordVariable = recordVariable;
+
+		this.#headerOffset = headerOffset;
+	}
+
+	get #centralFixedView(): DataView {
+		const buffer = this.#recordFixed;
+		return new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+	}
+
+	/**
+	 * the filename of the entry
+	 * @returns the filename as string
+	 */
+	@cache
+	get filename(): string {
+		const fnameLength = readUint16LE(this.#centralFixedView, 28);
+		const fname = this.#recordVariable.subarray(0, fnameLength);
+
+		return decodeUtf8From(fname);
+	}
+
+	/**
+	 * the uncompressed size of the entry
+	 * @returns size in bytes
+	 */
+	@cache
+	get size(): number {
+		return readUint32LE(this.#centralFixedView, 24);
+	}
+
+	/**
+	 * the compressed size of the entry
+	 * @returns size in bytes
+	 */
+	@cache
+	get compressedSize(): number {
+		return readUint32LE(this.#centralFixedView, 20);
+	}
+
+	/**
+	 * the compression method used for the entry
+	 * @returns compression method code
+	 */
+	@cache
+	get compressionMethod(): number {
+		return readUint16LE(this.#centralFixedView, 10);
+	}
+
+	/**
+	 * the last modification time of the entry
+	 * @returns timestamp in milliseconds
+	 */
+	@cache
+	get mtime(): number {
+		const view = this.#centralFixedView;
+		const dosTime = readUint16LE(view, 12);
+		const dosDate = readUint16LE(view, 14);
+
+		const seconds = (dosTime & 0x1f) * 2;
+		const minutes = (dosTime >>> 5) & 0x3f;
+		const hours = (dosTime >>> 11) & 0x1f;
+
+		const day = dosDate & 0x1f;
+		const month = ((dosDate >>> 5) & 0x0f) - 1;
+		const year = ((dosDate >>> 9) & 0x7f) + 1980;
+
+		return Date.UTC(year, month, day, hours, minutes, seconds);
+	}
+
+	/**
+	 * the file mode/permissions of the entry
+	 * @returns mode as number, or 0 if not set
+	 */
+	@cache
+	get mode(): number {
+		const attrs = readUint32LE(this.#centralFixedView, 38);
+		const mode = (attrs >>> 16) & 0xffff;
+
+		return mode;
+	}
+
+	/**
+	 * a readable stream of the entry's decompressed content
+	 * @returns stream of the entry data
+	 */
+	@cache
+	get body(): ReadableStream<Uint8Array> {
+		let r: ReadableStreamDefaultReader<Uint8Array>;
+
+		return new ReadableStream({
+			start: async (controller) => {
+				try {
+					// read local file header to get actual data offset
+					let offset: number;
+					{
+						const headerOffset = this.#headerOffset;
+
+						const stream = await this.#reader.read(headerOffset, LHEADER_FIXED_SIZE);
+						const bytes = await read(stream, LHEADER_FIXED_SIZE);
+
+						const header = new DataView(bytes.buffer, bytes.byteOffset, LHEADER_FIXED_SIZE);
+
+						const filenameLength = readUint16LE(header, 26);
+						const extraFieldLength = readUint16LE(header, 28);
+
+						offset = headerOffset + LHEADER_FIXED_SIZE + filenameLength + extraFieldLength;
+					}
+
+					// read data
+					let stream = await this.#reader.read(offset, this.compressedSize);
+					if (this.compressionMethod === 8) {
+						// deflate compression
+						stream = stream.pipeThrough(new DecompressionStream('deflate-raw'));
+					}
+
+					r = stream.getReader();
+				} catch (error) {
+					controller.error(error);
+
+					await r?.cancel();
+				}
+			},
+			async pull(controller) {
+				const { done, value } = await r.read();
+
+				if (done) {
+					controller.close();
+				} else {
+					controller.enqueue(value);
+				}
+			},
+			async cancel() {
+				await r?.cancel();
+			},
+		});
+	}
+
+	/**
+	 * reads the entry content as bytes
+	 * @returns the content as Uint8Array
+	 */
+	async bytes(): Promise<Uint8Array> {
+		return await read(this.body, this.size);
+	}
+
+	/**
+	 * reads the entry content as an ArrayBuffer
+	 * @returns an ArrayBuffer
+	 */
+	async arrayBuffer(): Promise<ArrayBuffer> {
+		const bytes = await this.bytes() as Uint8Array<ArrayBuffer>;
+
+		// if bytes covers the entire buffer, return it directly
+		if (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
+			return bytes.buffer;
+		}
+
+		// otherwise we need to slice to get the right portion
+		return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+	}
+
+	/**
+	 * reads the entry content as a Blob
+	 * @returns a Blob
+	 */
+	async blob(): Promise<Blob> {
+		const bytes = await this.bytes();
+		return new Blob([bytes]);
+	}
+
+	/**
+	 * reads the entry content as text
+	 * @returns the content as string
+	 */
+	async text(): Promise<string> {
+		const bytes = await this.bytes();
+		return decodeUtf8From(bytes);
+	}
+
+	/**
+	 * reads the entry content as JSON
+	 * @returns the parsed JSON
+	 */
+	async json(): Promise<unknown> {
+		const text = await this.text();
+		return JSON.parse(text);
+	}
+}
+
+/**
+ * extracts entries from a zip archive
+ * @param reader data source to read the zip file from
+ * @returns async generator yielding zip entries
+ */
+export async function* unzip(reader: Reader): AsyncGenerator<UnzippedEntry> {
+	const eocd = await readEocd(reader);
+
+	for await (const record of readCentralRecords(reader, eocd)) {
+		yield new UnzippedEntry(reader, record.fixedBytes, record.variableBytes, record.headerOffset);
+	}
+}
+
+interface EndOfCentralDirectory {
+	recordCount: number;
+	dirSize: number;
+	dirOffset: number;
+}
+
+interface CentralRecord {
+	fixedBytes: Uint8Array;
+	variableBytes: Uint8Array;
+	headerOffset: number;
+}
+
+async function readEocd(reader: Reader): Promise<EndOfCentralDirectory> {
+	const maxSearchLength = Math.min(reader.length, 65557); // 22 + max comment length
+	const start = reader.length - maxSearchLength;
+
+	// use a 22-byte circular buffer sliding window
+	const window = new CircularBuffer(EOCD_FIXED_SIZE);
+	const stream = await reader.read(start, maxSearchLength);
+
+	let pos = start;
+	let eocd: EndOfCentralDirectory | undefined;
+
+	for await (const chunk of stream) {
+		for (let idx = 0, len = chunk.length; idx < len; idx++) {
+			const byte = chunk[idx];
+
+			window.push(byte);
+			pos++;
+
+			// only check for signature once window is full
+			if (!window.filled) {
+				continue;
+			}
+
+			//  0 - end of central directory signature
+			//  4 - this disk's number
+			//  6 - disk number containing start of central directory
+			//  8 - amount of records in this disk's central directory
+			// 10 - total amount of central directory records
+			// 12 - total size of this disk's central directory records
+			// 16 - offset to start of this disk's central directory records
+			// 20 - comment length
+
+			// check for EOCD signature (0x06054b50)
+			// signature is [0x50, 0x4b, 0x05, 0x06] in little endian
+			if (window.at(0) === 0x50 && window.at(1) === 0x4b && window.at(2) === 0x05 && window.at(3) === 0x06) {
+				const offset = pos - EOCD_FIXED_SIZE; // window start position
+
+				const buffer = window.dump();
+				const view = new DataView(buffer.buffer, buffer.byteOffset);
+
+				const diskNumber = readUint16LE(view, 4);
+				const commentLength = readUint16LE(view, 20);
+
+				if (diskNumber !== 0) {
+					throw new Error(`multi-disk zip files not supported`);
+				}
+
+				// the EOCD should end exactly at the file end
+				if (offset + EOCD_FIXED_SIZE + commentLength === reader.length) {
+					// validate central directory bounds
+					const centralDirSize = readUint32LE(view, 12);
+					const centralDirOffset = readUint32LE(view, 16);
+
+					if (centralDirOffset + centralDirSize <= offset) {
+						eocd = {
+							recordCount: readUint16LE(view, 10),
+							dirSize: centralDirSize,
+							dirOffset: centralDirOffset,
+						};
+					}
+				}
+			}
+		}
+	}
+
+	if (eocd === undefined) {
+		throw new Error(`zip file might be invalid or corrupted`);
+	}
+
+	return eocd;
+}
+
+async function* readCentralRecords(
+	reader: Reader,
+	{ dirOffset, dirSize, recordCount }: EndOfCentralDirectory,
+): AsyncGenerator<CentralRecord> {
+	const stream = await reader.read(dirOffset, dirSize);
+	await using r = new StreamReader(stream);
+
+	for (let idx = 0, len = recordCount; idx < len; idx++) {
+		// check if we have room for at least the fixed header
+		if (r.consumed + CRECORD_FIXED_SIZE > dirSize) {
+			throw new Error(`central record extends beyond directory bounds`);
+		}
+
+		// ensure we have 46 bytes for the header
+		await r.require(CRECORD_FIXED_SIZE);
+
+		const fixedBytes = r.take(CRECORD_FIXED_SIZE);
+		const fixed = new DataView(fixedBytes.buffer, fixedBytes.byteOffset);
+
+		//  0 - central directory record signature
+		//  4 - version used to create this archive
+		//  6 - minimum required version for extraction
+		//  8 - general purpose bitflag
+		// 10 - compression method
+		// 12 - file last modification time
+		// 14 - file last modification date
+		// 16 - CRC32 of uncompressed data
+		// 20 - compressed size
+		// 24 - uncompressed size
+		// 28 - file name length
+		// 30 - extra fields length
+		// 32 - file comment length
+		// 34 - disk number containing start of file
+		// 36 - internal file attributes
+		// 38 - external file attributes
+		// 42 - offset to start of entry
+
+		const signature = readUint32LE(fixed, 0);
+		if (signature !== 0x02014b50) {
+			throw new Error(`invalid central directory file header signature`);
+		}
+
+		const filenameLength = readUint16LE(fixed, 28);
+		const extraFieldLength = readUint16LE(fixed, 30);
+		const commentLength = readUint16LE(fixed, 32);
+		const headerOffset = readUint32LE(fixed, 42);
+
+		const variableLength = filenameLength + extraFieldLength + commentLength;
+
+		// validate variable field lengths are reasonable
+		if (variableLength < 0 || r.consumed + variableLength > dirSize) {
+			throw new Error(`central record variable fields extend beyond directory bounds`);
+		}
+
+		let variableBytes: Uint8Array;
+
+		if (variableLength > 0) {
+			await r.require(variableLength);
+
+			variableBytes = r.take(variableLength);
+		} else {
+			variableBytes = new Uint8Array(0);
+		}
+
+		yield {
+			fixedBytes: fixedBytes,
+			variableBytes: variableBytes,
+			headerOffset: headerOffset,
+		};
+	}
+}

lib/utils/buffer.ts

···
+const fromCharCode = String.fromCharCode;
+
+export const textEncoder = new TextEncoder();
+export const textDecoder = new TextDecoder();
+
+export function concat(arrays: Uint8Array[], size?: number): Uint8Array {
+	let written = 0;
+
+	// deno-lint-ignore prefer-const
+	let len = arrays.length;
+	let idx: number;
+
+	if (size === undefined) {
+		for (idx = size = 0; idx < len; idx++) {
+			const chunk = arrays[idx];
+			size += chunk.length;
+		}
+	}
+
+	const buffer = new Uint8Array(size);
+
+	for (idx = 0; idx < len; idx++) {
+		const chunk = arrays[idx];
+
+		buffer.set(chunk, written);
+		written += chunk.length;
+	}
+
+	return buffer;
+}
+
+export async function read(stream: ReadableStream<Uint8Array>, size: number): Promise<Uint8Array> {
+	const buffer = new Uint8Array(size);
+
+	let read = 0;
+
+	for await (const chunk of stream) {
+		const length = chunk.length;
+		const remaining = Math.min(length, size - read);
+
+		if (remaining === length) {
+			buffer.set(chunk, read);
+		} else {
+			buffer.set(chunk.subarray(0, remaining), read);
+		}
+
+		read += remaining;
+
+		if (read >= size) {
+			break;
+		}
+	}
+
+	if (read < size) {
+		throw new Error(`unexpected end of stream: expected ${size} bytes, got ${read}`);
+	}
+
+	return buffer;
+}
+
+export const decodeUtf8From = (from: Uint8Array, offset?: number, length?: number): string => {
+	let buffer: Uint8Array;
+
+	if (offset === undefined) {
+		buffer = from;
+	} else if (length === undefined) {
+		buffer = from.subarray(offset);
+	} else {
+		buffer = from.subarray(offset, offset + length);
+	}
+
+	const end = buffer.length;
+	if (end > 24) {
+		return textDecoder.decode(buffer);
+	}
+
+	{
+		let str = '';
+		let idx = 0;
+
+		for (; idx + 3 < end; idx += 4) {
+			const a = buffer[idx];
+			const b = buffer[idx + 1];
+			const c = buffer[idx + 2];
+			const d = buffer[idx + 3];
+
+			if ((a | b | c | d) & 0x80) {
+				return str + textDecoder.decode(buffer.subarray(idx));
+			}
+
+			str += fromCharCode(a, b, c, d);
+		}
+
+		for (; idx < end; idx++) {
+			const x = buffer[idx];
+
+			if (x & 0x80) {
+				return str + textDecoder.decode(buffer.subarray(idx));
+			}
+
+			str += fromCharCode(x);
+		}
+
+		return str;
+	}
+};

lib/utils/decorator.ts

···
+/**
+ * caches the result of a getter on first access
+ */
+export function cache<T, K>(originalMethod: (this: T) => K, context: ClassGetterDecoratorContext) {
+	return function (this: T): K {
+		const value = originalMethod.call(this);
+
+		Object.defineProperty(this, context.name, { value, writable: false, enumerable: false });
+		return value;
+	};
+}

lib/utils/stream-reader.ts

···
+import Queue from '@mary/ds-queue';
+
+import { concat } from './buffer.ts';
+
+export class StreamReader implements AsyncDisposable {
+	#reader: ReadableStreamDefaultReader<Uint8Array>;
+
+	#chunks = new Queue<Uint8Array>();
+	#buffered = 0;
+	#consumed = 0;
+
+	constructor(stream: ReadableStream<Uint8Array>) {
+		this.#reader = stream.getReader();
+	}
+
+	get buffered(): number {
+		return this.#buffered;
+	}
+
+	get consumed(): number {
+		return this.#consumed;
+	}
+
+	async require(size: number): Promise<void> {
+		const reader = this.#reader;
+		const chunks = this.#chunks;
+
+		while (this.#buffered < size) {
+			const { done, value } = await reader.read();
+
+			if (done) {
+				throw new Error(`unexpected end of stream: needed ${size} bytes, have ${this.#buffered}`);
+			}
+
+			chunks.enqueue(value);
+
+			this.#buffered += value.length;
+		}
+	}
+
+	take(size: number): Uint8Array {
+		if (size === 0) {
+			return new Uint8Array(0);
+		}
+
+		if (this.#buffered < size) {
+			throw new Error(`needed ${size} bytes, have ${this.#buffered}`);
+		}
+
+		const chunks = this.#chunks;
+		const needed: Uint8Array[] = [];
+
+		let taken = 0;
+
+		while (taken < size) {
+			const chunk = chunks.dequeue()!;
+			const chunkLength = chunk.length;
+
+			const took = Math.min(chunkLength, size - taken);
+
+			if (took < chunkLength) {
+				// Split chunk
+				needed.push(chunk.subarray(0, took));
+
+				chunks.enqueueFront(chunk.subarray(took));
+
+				taken += took;
+				break;
+			} else {
+				needed.push(chunk);
+
+				taken += chunkLength;
+			}
+		}
+
+		this.#buffered -= size;
+		this.#consumed += size;
+
+		if (needed.length === 1) {
+			return needed[0];
+		} else {
+			return concat(needed, size);
+		}
+	}
+
+	async [Symbol.asyncDispose](): Promise<void> {
+		await this.#reader.cancel();
+	}
+}

lib/zip.ts

···
+import { getDayOfMonth, getHours, getMinutes, getMonth, getSeconds, getYear } from '@mary/date-fns';
+import { textEncoder } from './utils/buffer.ts';
+
+/**
+ * file attributes for zip entries
+ */
+export interface ZipFileAttributes {
+	/** file permissions mode */
+	mode?: number;
+	/** user id of the file owner */
+	uid?: number;
+	/** group id of the file owner */
+	gid?: number;
+	/** modification time as unix timestamp */
+	mtime?: number;
+	/** owner username */
+	owner?: string;
+	/** group name */
+	group?: string;
+}
+
+/**
+ * represents a single entry in a zip archive
+ */
+export interface ZipEntry {
+	/** path and name of the file in the zip archive */
+	filename: string;
+	/** file content as string, bytes, or stream */
+	data: string | Uint8Array | ReadableStream<Uint8Array>;
+	/** file attributes like permissions and timestamps */
+	attrs?: ZipFileAttributes;
+	/** whether to compress the file data */
+	compress?: false | 'deflate';
+}
+
+const DEFAULT_ATTRS: ZipFileAttributes = {};
+
+// deno-lint-ignore no-control-regex
+const INVALID_FILENAME_CHARS = /[<>:"|?*\x00-\x1f]/;
+const INVALID_FILENAME_TRAVERSAL = /(?:^|[/\\])\.\.(?:[/\\]|$)/;
+// deno-lint-ignore no-control-regex
+const NON_ASCII_CHARS = /[^\x00-\x7f]/;
+
+function writeUtf8String(view: DataView, offset: number, length: number, str: string) {
+	const u8 = new Uint8Array(view.buffer, view.byteOffset + offset, length);
+	textEncoder.encodeInto(str, u8);
+}
+
+function writeUint32LE(view: DataView, offset: number, value: number) {
+	view.setUint32(offset, value, true);
+}
+function writeUint16LE(view: DataView, offset: number, value: number) {
+	view.setUint16(offset, value, true);
+}
+
+const CRC32_TABLE = /*#__PURE__*/ (() => {
+	const t = new Int32Array(256);
+
+	for (let i = 0; i < 256; ++i) {
+		let c = i, k = 9;
+		while (--k) c = (c & 1 ? 0xedb88320 : 0) ^ (c >>> 1);
+		t[i] = c;
+	}
+
+	return t;
+})();
+
+function crc32(chunk: Uint8Array, crc: number = 0xffffffff): number {
+	for (let idx = 0, len = chunk.length; idx < len; idx++) {
+		crc = CRC32_TABLE[(crc ^ chunk[idx]) & 0xff] ^ (crc >>> 8);
+	}
+
+	return crc ^ -1;
+}
+
+function unixToDosTime(unixTimestamp: number): { time: number; date: number } {
+	const date = new Date(unixTimestamp * 1000);
+
+	const dosTime = ((getSeconds(date) >> 1) & 0x1f) | ((getMinutes(date) & 0x3f) << 5) |
+		((getHours(date) & 0x1f) << 11);
+
+	const dosDate = (getDayOfMonth(date) & 0x1f) |
+		(((getMonth(date) + 1) & 0x0f) << 5) |
+		(((getYear(date) - 1980) & 0x7f) << 9);
+
+	return { time: dosTime, date: dosDate };
+}
+
+function validateFilename(filename: string): void {
+	if (filename.length === 0) {
+		throw new Error(`invalid filename: cannot be empty`);
+	}
+
+	if (filename.length > 65535) {
+		throw new Error(`invalid filename: too long (max 65535 bytes)`);
+	}
+
+	if (INVALID_FILENAME_TRAVERSAL.test(filename)) {
+		throw new Error(`invalid filename: contains path traversal`);
+	}
+
+	if (filename.startsWith('/')) {
+		throw new Error(`invalid filename: is an absolute path`);
+	}
+
+	if (INVALID_FILENAME_CHARS.test(filename)) {
+		throw new Error('invalid filename: contains invalid characters');
+	}
+}
+
+function isNonAscii(filename: string): boolean {
+	// check if filename contains non-ASCII characters
+	return NON_ASCII_CHARS.test(filename);
+}
+
+/**
+ * creates a zip archive from entries and yields chunks as Uint8Array
+ * @param entries iterable of zip entries to include in the archive
+ * @returns async generator that yields zip file chunks
+ */
+export async function* zip(
+	entries: Iterable<ZipEntry> | AsyncIterable<ZipEntry>,
+): AsyncGenerator<Uint8Array> {
+	const listing: Uint8Array[] = [];
+	let offset: number = 0;
+
+	for await (const { filename, data, compress = 'deflate', attrs = DEFAULT_ATTRS } of entries) {
+		validateFilename(filename);
+
+		const startOffset = offset;
+
+		const fname = textEncoder.encode(filename);
+		const fnameLen = fname.length;
+
+		const mtimeSeconds = attrs?.mtime ?? Math.floor(Date.now() / 1000);
+		const { time: dosTime, date: dosDate } = unixToDosTime(mtimeSeconds);
+
+		let method: number = 0;
+		let crc: number = 0xffffffff;
+		let flags = 0x0008;
+
+		let uncompressedSize: number = 0;
+		let compressedSize: number = 0;
+
+		if (compress === 'deflate') {
+			method = 8;
+		}
+
+		if (isNonAscii(filename)) {
+			flags |= 0x0800;
+		}
+
+		// local header
+		{
+			const header = new ArrayBuffer(30 + fnameLen);
+			const view = new DataView(header);
+
+			writeUint32LE(view, 0, 0x04034b50); // local file header signature
+			writeUint16LE(view, 4, 20); // version needed to extract (2.0)
+			writeUint16LE(view, 6, flags); // general purpose bit flag
+			writeUint16LE(view, 8, method); // compression method (0=stored, 8=deflate)
+			writeUint16LE(view, 10, dosTime); // last mod file time (DOS format)
+			writeUint16LE(view, 12, dosDate); // last mod file date (DOS format)
+			writeUint32LE(view, 14, 0); // crc-32 (set to 0, actual value in data descriptor)
+			writeUint32LE(view, 18, 0); // compressed size (set to 0, actual value in data descriptor)
+			writeUint32LE(view, 22, 0); // uncompressed size (set to 0, actual value in data descriptor)
+			writeUint16LE(view, 26, fnameLen); // file name length
+			writeUint16LE(view, 28, 0); // extra field length
+
+			writeUtf8String(view, 30, fnameLen, filename);
+
+			offset += 30 + fnameLen;
+
+			yield new Uint8Array(header);
+		}
+
+		// data
+		if (compress === 'deflate') {
+			let stream: ReadableStream<Uint8Array>;
+			if (data instanceof ReadableStream) {
+				stream = data.pipeThrough(
+					new TransformStream({
+						transform(chunk, controller) {
+							uncompressedSize += chunk.length;
+							crc = crc32(chunk, crc);
+
+							controller.enqueue(chunk);
+						},
+					}),
+				);
+			} else {
+				const chunk = typeof data === 'string' ? textEncoder.encode(data) : data;
+
+				uncompressedSize = chunk.length;
+				crc = crc32(chunk, crc);
+
+				stream = new ReadableStream({
+					start(controller) {
+						controller.enqueue(chunk);
+						controller.close();
+					},
+				});
+			}
+
+			yield* stream.pipeThrough(new CompressionStream('deflate-raw')).pipeThrough(
+				new TransformStream({
+					transform(chunk, controller) {
+						controller.enqueue(chunk);
+
+						compressedSize += chunk.length;
+					},
+				}),
+			);
+		} else {
+			if (data instanceof ReadableStream) {
+				yield* data.pipeThrough(
+					new TransformStream({
+						transform(chunk, controller) {
+							uncompressedSize += chunk.length;
+							crc = crc32(chunk, crc);
+
+							controller.enqueue(chunk);
+						},
+					}),
+				);
+
+				compressedSize = uncompressedSize;
+			} else {
+				const chunk = typeof data === 'string' ? textEncoder.encode(data) : data;
+
+				uncompressedSize = chunk.length;
+				compressedSize = uncompressedSize;
+				crc = crc32(chunk, crc);
+
+				yield chunk;
+			}
+		}
+
+		offset += compressedSize;
+
+		// data descriptor
+		{
+			const descriptor = new ArrayBuffer(16);
+			const view = new DataView(descriptor);
+
+			//  0 - data descriptor signature
+			//  4 - CRC32 of uncompressed data
+			//  8 - compressed size
+			// 12 - uncompressed size
+			writeUint32LE(view, 0, 0x08074b50);
+			writeUint32LE(view, 4, crc);
+			writeUint32LE(view, 8, compressedSize);
+			writeUint32LE(view, 12, uncompressedSize);
+
+			offset += 16;
+
+			yield new Uint8Array(descriptor);
+		}
+
+		// central directory record
+		{
+			const record = new ArrayBuffer(46 + fnameLen);
+			const view = new DataView(record);
+
+			const mode = attrs?.mode ?? 0o100644;
+			const externalAttrs = (mode & 0xffff) << 16;
+
+			//  0 - central directory record signature
+			//  4 - version used to create this archive
+			//  6 - minimum required version for extraction
+			//  8 - general purpose bitflag
+			// 10 - compression method
+			// 12 - file last modification time
+			// 14 - file last modification date
+			// 16 - CRC32 of uncompressed data
+			// 20 - compressed size
+			// 24 - uncompressed size
+			// 28 - file name length
+			// 30 - extra fields length
+			// 32 - file comment length
+			// 34 - disk number containing start of file
+			// 36 - internal file attributes
+			// 38 - external file attributes
+			// 42 - offset to start of entry
+			writeUint32LE(view, 0, 0x02014b50);
+			writeUint16LE(view, 4, (3 << 8) | 20);
+			writeUint16LE(view, 6, 20);
+			writeUint16LE(view, 8, flags);
+			writeUint16LE(view, 10, method);
+			writeUint16LE(view, 12, dosTime);
+			writeUint16LE(view, 14, dosDate);
+			writeUint32LE(view, 16, crc);
+			writeUint32LE(view, 20, compressedSize);
+			writeUint32LE(view, 24, uncompressedSize);
+			writeUint16LE(view, 28, fnameLen);
+			writeUint16LE(view, 30, 0);
+			writeUint16LE(view, 32, 0);
+			writeUint16LE(view, 34, 0);
+			writeUint16LE(view, 36, 0);
+			writeUint32LE(view, 38, externalAttrs);
+			writeUint32LE(view, 42, startOffset);
+
+			writeUtf8String(view, 46, fnameLen, filename);
+
+			listing.push(new Uint8Array(record));
+		}
+	}
+
+	// central directory
+	{
+		const startCentralOffset = offset;
+		const recordCount = listing.length;
+
+		let centralSize = 0;
+
+		for (let idx = 0; idx < recordCount; idx++) {
+			const record = listing[idx];
+			const recordLen = record.length;
+
+			offset += recordLen;
+			centralSize += recordLen;
+
+			yield record;
+		}
+
+		{
+			const directory = new ArrayBuffer(22);
+			const view = new DataView(directory);
+
+			//  0 - end of central directory signature
+			//  4 - this disk's number
+			//  6 - disk number containing start of central directory
+			//  8 - amount of records in this disk's central directory
+			// 10 - total amount of central directory records
+			// 12 - total size of this disk's central directory records
+			// 16 - offset of this disk's central directory records
+			// 20 - comment length
+			writeUint32LE(view, 0, 0x06054b50);
+			writeUint16LE(view, 4, 0);
+			writeUint16LE(view, 6, 0);
+			writeUint16LE(view, 8, recordCount);
+			writeUint16LE(view, 10, recordCount);
+			writeUint32LE(view, 12, centralSize);
+			writeUint32LE(view, 16, startCentralOffset);
+			writeUint16LE(view, 20, 0);
+
+			yield new Uint8Array(directory);
+		}
+	}
+}