@naturalcycles/nodejs-lib 15.109.0 → 15.111.0

package/dist/zip/index.d.ts

@@ -0,0 +1,3 @@
+export * from './zip2.js';
+export * from './zipReader.js';
+export * from './zipWriter.js';

package/dist/zip/index.js

@@ -0,0 +1,3 @@
+export * from './zip2.js';
+export * from './zipReader.js';
+export * from './zipWriter.js';

package/dist/zip/zip2.d.ts

@@ -1,5 +1,8 @@
 import type { ZlibOptions, ZstdOptions } from 'node:zlib';
 import type { Integer } from '@naturalcycles/js-lib/types';
+import type { ZipEntry } from './zipReader.js';
+import { ZipWriter } from './zipWriter.js';
+import type { ZipFileEntry, ZipPathsOptions } from './zipWriter.js';
 declare class Zip2 {
     decompressZstdOrInflateToString(buf: Buffer): Promise<string>;
     decompressZstdOrInflateToStringSync(buf: Buffer): string;
@@ -54,6 +57,40 @@ declare class Zip2 {
     zstdDecompressSync(input: Buffer, options?: ZstdOptions): Buffer<ArrayBuffer>;
     isZstdBuffer(input: Buffer): boolean;
     isGzipBuffer(input: Buffer): boolean;
+    /**
+     * Open a zip file and extract all of its entries into `destDir`, streaming each
+     * file to disk. Directories are created as needed.
+     *
+     * Path-traversal attempts (absolute paths, `..` segments, or paths escaping
+     * `destDir`) are rejected.
+     *
+     * Returns the list of extracted entries.
+     */
+    extractZipFileToDirectory(zipFilePath: string, destDir: string): Promise<ZipEntry[]>;
+    /**
+     * Create a zip archive on disk from a list of files and/or directories.
+     */
+    zipPaths(paths: string[], outputZipFilePath: string, opt?: ZipPathsOptions): Promise<void>;
+    /**
+     * Create a zip archive on disk, returning a {@link ZipWriter} that streams to it.
+     *
+     * Add entries with {@link ZipWriter.addFile}/{@link ZipWriter.addBuffer}/etc.,
+     * then call {@link ZipWriter.finalize} (or use `await using`):
+     *
+     * ```ts
+     * const zip = createZip('archive.zip')
+     * await zip.addFile('./photo.jpg')
+     * await zip.addBuffer(Buffer.from('{"a":1}'), 'data.json')
+     * await zip.finalize()
+     * ```
+     */
+    createZip(filePath: string): ZipWriter;
+    /**
+     * Build a zip archive entirely in memory and return it as a Buffer.
+     *
+     * For large archives or streamed inputs prefer {@link createZip} / {@link ZipWriter}.
+     */
+    createZipBuffer(entries: ZipFileEntry[]): Promise<Buffer>;
 }
 export declare const zip2: Zip2;
 export {};

package/dist/zip/zip2.js

@@ -1,5 +1,8 @@
+import { createWriteStream } from 'node:fs';
 import { promisify } from 'node:util';
 import zlib from 'node:zlib';
+import { openZip } from './zipReader.js';
+import { createZipBuffer, zipPaths, ZipWriter } from './zipWriter.js';
 const deflateAsync = promisify(zlib.deflate.bind(zlib));
 const inflateAsync = promisify(zlib.inflate.bind(zlib));
 const gzipAsync = promisify(zlib.gzip.bind(zlib));
@@ -124,6 +127,54 @@ class Zip2 {
     isGzipBuffer(input) {
         return input[0] === 0x1f && input[1] === 0x8b;
     }
+    /**
+     * Open a zip file and extract all of its entries into `destDir`, streaming each
+     * file to disk. Directories are created as needed.
+     *
+     * Path-traversal attempts (absolute paths, `..` segments, or paths escaping
+     * `destDir`) are rejected.
+     *
+     * Returns the list of extracted entries.
+     */
+    async extractZipFileToDirectory(zipFilePath, destDir) {
+        const zip = await openZip(zipFilePath);
+        try {
+            return await zip.extractAll(destDir);
+        }
+        finally {
+            await zip.close();
+        }
+    }
+    /**
+     * Create a zip archive on disk from a list of files and/or directories.
+     */
+    async zipPaths(paths, outputZipFilePath, opt) {
+        return await zipPaths(paths, outputZipFilePath, opt);
+    }
+    /**
+     * Create a zip archive on disk, returning a {@link ZipWriter} that streams to it.
+     *
+     * Add entries with {@link ZipWriter.addFile}/{@link ZipWriter.addBuffer}/etc.,
+     * then call {@link ZipWriter.finalize} (or use `await using`):
+     *
+     * ```ts
+     * const zip = createZip('archive.zip')
+     * await zip.addFile('./photo.jpg')
+     * await zip.addBuffer(Buffer.from('{"a":1}'), 'data.json')
+     * await zip.finalize()
+     * ```
+     */
+    createZip(filePath) {
+        return new ZipWriter(createWriteStream(filePath));
+    }
+    /**
+     * Build a zip archive entirely in memory and return it as a Buffer.
+     *
+     * For large archives or streamed inputs prefer {@link createZip} / {@link ZipWriter}.
+     */
+    async createZipBuffer(entries) {
+        return await createZipBuffer(entries);
+    }
 }
 export const zip2 = new Zip2();
 const ZSTD_MAGIC_NUMBER = 0xfd2fb528;

package/dist/zip/zipInternal.d.ts

@@ -0,0 +1,41 @@
+import type { UnixTimestamp } from '@naturalcycles/js-lib/types';
+export declare const STORED = 0;
+export declare const DEFLATE = 8;
+export declare const LOCAL_FILE_HEADER_SIG = 67324752;
+export declare const DATA_DESCRIPTOR_SIG = 134695760;
+export declare const CDFH_SIG = 33639248;
+export declare const CDFH_SIZE = 46;
+export declare const EOCDR_SIG = 101010256;
+export declare const EOCDR_SIZE = 22;
+export declare const ZIP64_EOCDL_SIG = 117853008;
+export declare const ZIP64_EOCDL_SIZE = 20;
+export declare const ZIP64_EOCDR_SIG = 101075792;
+export declare const ZIP64_EOCDR_SIZE = 56;
+/** The .zip comment and per-entry name/comment length fields are all 16-bit. */
+export declare const MAX_COMMENT_SIZE = 65535;
+/** Read a 64-bit little-endian unsigned integer, rejecting values above `Number.MAX_SAFE_INTEGER`. */
+export declare function readUInt64LE(buf: Buffer, offset: number): number;
+/** Write a 64-bit little-endian unsigned integer. */
+export declare function writeUInt64LE(buf: Buffer, value: number, offset: number): void;
+/**
+ * Decode a packed DOS date + time pair into a {@link UnixTimestamp} (seconds).
+ * The DOS fields are local-time, so they are interpreted in the local timezone.
+ * Used when no Info-ZIP extended timestamp is present.
+ */
+export declare function dosDateTimeToUnix(date: number, time: number): UnixTimestamp;
+/**
+ * Encode a {@link UnixTimestamp} (seconds) into the packed DOS date + time pair stored
+ * in local file and central directory headers. The DOS fields are local-time, so the
+ * timestamp is rendered in the local timezone. Out-of-range dates are clamped to 1980-2107.
+ */
+export declare function unixToDosDateTime(ts: UnixTimestamp): {
+    date: number;
+    time: number;
+};
+/** Normalize Windows-style separators, like yauzl in non-strict mode. */
+export declare function normalizeZipEntryName(name: string): string;
+/**
+ * Reject entry names that would escape the extraction directory: absolute paths
+ * (drive letters or a leading `/`) and any `..` path segment.
+ */
+export declare function assertSafeZipEntryName(name: string): void;

package/dist/zip/zipInternal.js

@@ -0,0 +1,88 @@
+/*
+
+Shared low-level helpers and constants for the zip reader and writer.
+
+These are the parts of the ZIP file format that both reading (`zipReader.ts`) and
+writing (`zipWriter.ts`) need in common: record signatures and fixed sizes, 64-bit
+integer read/write helpers, DOS date/time conversion (both directions) and
+entry-name normalization/validation.
+
+ */
+// oxlint-disable no-bitwise -- the ZIP format packs DOS date/time into bit fields
+// Compression methods.
+export const STORED = 0;
+export const DEFLATE = 8;
+// Record signatures (little-endian uint32) and fixed sizes (in bytes).
+export const LOCAL_FILE_HEADER_SIG = 0x04034b50;
+export const DATA_DESCRIPTOR_SIG = 0x08074b50;
+export const CDFH_SIG = 0x02014b50;
+export const CDFH_SIZE = 46;
+export const EOCDR_SIG = 0x06054b50;
+export const EOCDR_SIZE = 22;
+export const ZIP64_EOCDL_SIG = 0x07064b50;
+export const ZIP64_EOCDL_SIZE = 20;
+export const ZIP64_EOCDR_SIG = 0x06064b50;
+export const ZIP64_EOCDR_SIZE = 56;
+/** The .zip comment and per-entry name/comment length fields are all 16-bit. */
+export const MAX_COMMENT_SIZE = 0xffff;
+const MAX_SAFE_INTEGER_BIG = BigInt(Number.MAX_SAFE_INTEGER);
+/** Read a 64-bit little-endian unsigned integer, rejecting values above `Number.MAX_SAFE_INTEGER`. */
+export function readUInt64LE(buf, offset) {
+    const value = buf.readBigUInt64LE(offset);
+    if (value > MAX_SAFE_INTEGER_BIG) {
+        throw new Error('zip file too large: 64-bit values above Number.MAX_SAFE_INTEGER are not supported');
+    }
+    return Number(value);
+}
+/** Write a 64-bit little-endian unsigned integer. */
+export function writeUInt64LE(buf, value, offset) {
+    buf.writeBigUInt64LE(BigInt(value), offset);
+}
+/**
+ * Decode a packed DOS date + time pair into a {@link UnixTimestamp} (seconds).
+ * The DOS fields are local-time, so they are interpreted in the local timezone.
+ * Used when no Info-ZIP extended timestamp is present.
+ */
+export function dosDateTimeToUnix(date, time) {
+    const day = date & 0x1f; // 1-31
+    const month = ((date >> 5) & 0x0f) - 1; // 1-12 -> 0-11
+    const year = ((date >> 9) & 0x7f) + 1980; // 0-127 -> 1980-2107
+    const second = (time & 0x1f) * 2; // 0-29 -> 0-58
+    const minute = (time >> 5) & 0x3f; // 0-59
+    const hour = (time >> 11) & 0x1f; // 0-23
+    return Math.floor(new Date(year, month, day, hour, minute, second).getTime() / 1000);
+}
+const MIN_DOS_DATE = new Date(1980, 0, 1);
+const MAX_DOS_DATE = new Date(2107, 11, 31, 23, 59, 58);
+/**
+ * Encode a {@link UnixTimestamp} (seconds) into the packed DOS date + time pair stored
+ * in local file and central directory headers. The DOS fields are local-time, so the
+ * timestamp is rendered in the local timezone. Out-of-range dates are clamped to 1980-2107.
+ */
+export function unixToDosDateTime(ts) {
+    const jsDate = new Date(ts * 1000);
+    const d = jsDate < MIN_DOS_DATE ? MIN_DOS_DATE : jsDate > MAX_DOS_DATE ? MAX_DOS_DATE : jsDate;
+    const date = (d.getDate() & 0x1f) | // 1-31
+        (((d.getMonth() + 1) & 0x0f) << 5) | // 1-12
+        (((d.getFullYear() - 1980) & 0x7f) << 9); // 1980-2107
+    const time = Math.floor(d.getSeconds() / 2) | // 0-29
+        ((d.getMinutes() & 0x3f) << 5) | // 0-59
+        ((d.getHours() & 0x1f) << 11); // 0-23
+    return { date, time };
+}
+/** Normalize Windows-style separators, like yauzl in non-strict mode. */
+export function normalizeZipEntryName(name) {
+    return name.replaceAll('\\', '/');
+}
+/**
+ * Reject entry names that would escape the extraction directory: absolute paths
+ * (drive letters or a leading `/`) and any `..` path segment.
+ */
+export function assertSafeZipEntryName(name) {
+    if (/^[a-z]:/i.test(name) || name.startsWith('/')) {
+        throw new Error(`absolute path in zip entry: ${name}`);
+    }
+    if (name.split('/').includes('..')) {
+        throw new Error(`invalid relative path in zip entry: ${name}`);
+    }
+}

package/dist/zip/zipReader.d.ts

@@ -0,0 +1,142 @@
+import { Readable } from 'node:stream';
+import type { UnixTimestamp } from '@naturalcycles/js-lib/types';
+/**
+ * Open a zip archive from a file on disk.
+ *
+ * Reads and parses the central directory; the returned {@link ZipReader} exposes
+ * the list of entries and lets you read their contents.
+ *
+ * Remember to call {@link ZipReader.close} when done, or use {@link extractZip}.
+ */
+export declare function openZip(filePath: string): Promise<ZipReader>;
+/**
+ * Open a zip archive from an in-memory Buffer.
+ */
+export declare function openZipBuffer(buffer: Buffer): Promise<ZipReader>;
+/**
+ * Reads entries from an open zip archive.
+ *
+ * Create one via {@link openZip} or {@link openZipBuffer}.
+ *
+ * Implements `AsyncDisposable`, so it can be used with `await using` to close
+ * automatically on scope exit:
+ *
+ * ```ts
+ * await using zip = await openZip('archive.zip')
+ * const buf = await zip.readEntry(zip.entries[0])
+ * // zip.close() is called automatically here
+ * ```
+ */
+export declare class ZipReader implements AsyncDisposable {
+    private source;
+    /**
+     * All entries (files and directories) found in the archive,
+     * in central-directory order.
+     */
+    readonly entries: ZipEntry[];
+    /**
+     * Archive-level comment (empty string if none).
+     */
+    readonly comment: string;
+    constructor(source: ZipSource, 
+    /**
+     * All entries (files and directories) found in the archive,
+     * in central-directory order.
+     */
+    entries: ZipEntry[], 
+    /**
+     * Archive-level comment (empty string if none).
+     */
+    comment: string);
+    /**
+     * Read and fully decompress an entry into a Buffer.
+     *
+     * Validates the uncompressed size and CRC-32 checksum.
+     * For large entries prefer {@link openReadStream}.
+     */
+    readEntry(entry: ZipEntry): Promise<Buffer>;
+    /**
+     * Open a Readable stream of an entry's decompressed contents.
+     *
+     * Useful for piping large entries to disk without buffering them in memory.
+     * Unlike {@link readEntry}, this does not verify the CRC-32 checksum.
+     */
+    openReadStream(entry: ZipEntry): Promise<Readable>;
+    /**
+     * Extract all entries into `destDir`, streaming each file to disk.
+     * See {@link extractZip}.
+     */
+    extractAll(destDir: string): Promise<ZipEntry[]>;
+    /**
+     * Close the underlying file handle. No-op for buffer-backed archives.
+     * Safe to call multiple times.
+     */
+    close(): Promise<void>;
+    /**
+     * Called by `await using`; closes the archive. See {@link close}.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    private assertReadable;
+    private findFileDataStart;
+}
+/**
+ * Random-access byte source backing a {@link ZipReader}.
+ */
+interface ZipSource {
+    readonly size: number;
+    /** Read exactly `length` bytes starting at `position`; throws on EOF. */
+    read: (position: number, length: number) => Promise<Buffer>;
+    /** Stream raw bytes in the `[start, end)` range. */
+    createReadStream: (start: number, end: number) => Readable;
+    /** Release any held resources. Idempotent. */
+    close: () => Promise<void>;
+}
+/**
+ * A single entry (file or directory) inside a zip archive,
+ * as parsed from its central directory record.
+ */
+export interface ZipEntry {
+    /**
+     * Entry name, using `/` as the path separator.
+     * Directory entries end with a trailing `/`.
+     */
+    fileName: string;
+    /**
+     * Uncompressed size, in bytes.
+     */
+    uncompressedSize: number;
+    /**
+     * Compressed size, in bytes.
+     */
+    compressedSize: number;
+    /**
+     * Compression method: `0` = stored (no compression), `8` = deflate.
+     * Other methods cannot be read.
+     */
+    compressionMethod: number;
+    /**
+     * Expected CRC-32 checksum of the uncompressed data.
+     */
+    crc32: number;
+    /**
+     * Last modification time of the entry, as a Unix timestamp in seconds.
+     */
+    lastModified: UnixTimestamp;
+    /**
+     * True if the entry is a directory (its `fileName` ends with `/`).
+     */
+    isDirectory: boolean;
+    /**
+     * True if the entry is encrypted. Encrypted entries cannot be read.
+     */
+    isEncrypted: boolean;
+    /**
+     * Optional per-entry comment (empty string if none).
+     */
+    comment: string;
+    /** Bit flags from the central directory record. */
+    generalPurposeBitFlag: number;
+    /** Byte offset of the entry's local file header. */
+    relativeOffsetOfLocalHeader: number;
+}
+export {};