@gyng/remote-zip 0.2.5 → 1.0.1

package/lib/types/zip.d.ts

@@ -1,5 +1,23 @@
+export { crc32 } from "./crypto";
+/** Machine-readable discriminant for {@link RemoteZipError}. */
+export type RemoteZipErrorCode = "UNKNOWN" | "CONTENT_LENGTH_MISSING" | "INVALID_CONTENT_LENGTH" | "HTTP_ERROR" | "RANGE_NOT_SUPPORTED" | "RANGE_RESPONSE_MISMATCH" | "EOCD_NOT_FOUND" | "UNSUPPORTED_ZIP64" | "UNSUPPORTED_ENCRYPTION" | "FILE_NOT_FOUND" | "LOCAL_HEADER_PARSE_FAILED" | "CENTRAL_DIRECTORY_OUT_OF_BOUNDS" | "INVALID_ARCHIVE" | "TRUNCATED_ENTRY" | "UNSUPPORTED_COMPRESSION" | "UNSUPPORTED_MULTI_DISK" | "DECOMPRESSION_LIMIT_EXCEEDED" | "CRC_MISMATCH" | "WRONG_PASSWORD" | "DECRYPTION_FAILED";
 export declare class RemoteZipError extends Error {
-    constructor(message: any);
+    /** Machine-readable error code, for programmatic handling without matching on `message`. */
+    code: RemoteZipErrorCode;
+    constructor(message: string, code?: RemoteZipErrorCode);
+}
+/** Per-call options for {@link RemoteZip.fetch} / {@link RemoteZip.fetchStream}. */
+export interface EntryDecodeOptions {
+    /** If set, decompression aborts and throws once output would exceed this many bytes. */
+    maxUncompressedSize?: number;
+    /** Aborts this request (in addition to any instance-level signal). */
+    signal?: AbortSignal;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** If set, verify the decompressed output against the entry's CRC-32. */
+    verifyCrc?: boolean;
+    /** Password for an encrypted entry (traditional ZipCrypto or WinZip AES). */
+    password?: string;
 }
 export interface EndOfCentralDirectory {
     meta: Record<string, unknown>;
@@ -18,9 +36,9 @@ export interface EndOfCentralDirectory {
         centralDirectoryByteSize: number;
         /** Offset of start of central directory, relative to start of archive (or 0xffffffff for ZIP64) */
         centralDirectoryByteOffset: number;
-        /** Comment length (n) */
-        comment: string;
         /** Comment */
+        comment: string;
+        /** Comment length (n) */
         commentLength: number;
     };
 }
@@ -237,7 +255,15 @@ export declare class RemoteZip {
     method: string;
     /** Credentials passed to `fetch` when retrieving files. Defaults to `same-origin`. */
     credentials: "include" | "omit" | "same-origin";
-    constructor({ contentLength, url, centralDirectoryRecords, endOfCentralDirectory, method, credentials, }: {
+    /** Redirect mode passed to `fetch`. Defaults to `"follow"`. */
+    redirect?: RequestRedirect;
+    /** Signal that aborts in-flight requests. */
+    signal?: AbortSignal;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Extra RequestInit merged into every `fetch`. */
+    requestInit?: RequestInit;
+    constructor({ contentLength, url, centralDirectoryRecords, endOfCentralDirectory, method, credentials, redirect, signal, timeoutMs, requestInit, }: {
         /** Length of the remote ZIP archive in bytes */
         contentLength: number;
         /** Passed to fetch when performing a HTTP GET request for the file */
@@ -247,8 +273,10 @@ export declare class RemoteZip {
         /** Passed to fetch when performing a HTTP GET request for the file */
         method: string;
         /** Passed to fetch when performing a HTTP GET request for the file. */
-        credentials: "include" | "omit" | "same-origin";
-    });
+        credentials?: "include" | "omit" | "same-origin";
+    } & Pick<RemoteZipRequestOptions, "redirect" | "signal" | "timeoutMs" | "requestInit">);
+    /** Build a fetch RequestInit from this instance's network options. */
+    private requestInitFor;
     /**
      * Get a formatted file listing of the remote ZIP archive.
      *
@@ -269,10 +297,64 @@ export declare class RemoteZip {
      *
      * @param path Path of the file in the remote ZIP archive
      * @param additionalHeaders Additional headers, if any, to be passed to the `fetch` request
+     * @param options.maxUncompressedSize If set, inflation aborts and throws once the
+     *   decompressed output would exceed this many bytes. Set this when handling
+     *   untrusted archives to guard against decompression bombs.
+     * @param options.signal Aborts this request (in addition to any instance-level signal).
+     * @param options.timeoutMs Per-request timeout for this fetch.
+     * @param options.verifyCrc If set, verify the decompressed output against the
+     *   entry's CRC-32 and throw a {@link RemoteZipError} (`CRC_MISMATCH`) on mismatch.
      * @returns Inflated (uncompressed) bytes of the requested file
-     * @throws [RemoteZipError](RemoteZipError) if it fails to parse or fetch
+     * @throws {@link RemoteZipError} if it fails to parse, fetch, or exceeds limits
+     */
+    fetch(path: string, additionalHeaders?: Headers, options?: EntryDecodeOptions): Promise<Uint8Array>;
+    /**
+     * Decrypt (if needed), decompress, and CRC-verify one entry's bytes. Shared by
+     * {@link fetch} and the encrypted path of {@link fetchStream}.
+     */
+    private decodeEntry;
+    /**
+     * Like {@link fetch}, but returns a `ReadableStream` of the uncompressed bytes
+     * so large entries can be processed incrementally without buffering the whole
+     * file. `maxUncompressedSize` is enforced mid-stream (the stream errors with a
+     * {@link RemoteZipError} once exceeded).
+     *
+     * ```ts
+     * const stream = await remoteZip.fetchStream("big.bin");
+     * for await (const chunk of stream) {
+     *   // process each chunk
+     * }
+     * ```
      */
-    fetch(path: string, additionalHeaders?: Headers): Promise<ArrayBuffer>;
+    fetchStream(path: string, additionalHeaders?: Headers, options?: EntryDecodeOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Find an entry, reject encrypted ones, and issue the Range request that covers
+     * its local file header + compressed data. Shared by {@link fetch} and
+     * {@link fetchStream}.
+     */
+    private fetchEntryResponse;
+    private fetchRange;
+}
+/**
+ * Network options shared by every request a {@link RemoteZip} / {@link RemoteZipPointer}
+ * makes. All are optional with sensible defaults.
+ */
+export interface RemoteZipRequestOptions {
+    /** HTTP method for the Range GET requests. The metadata probe is always a HEAD. Defaults to `"GET"`. */
+    method?: string;
+    /** Passed to `fetch`. Defaults to `"same-origin"`. */
+    credentials?: "include" | "omit" | "same-origin";
+    /**
+     * Passed to `fetch`. Defaults to `"follow"`. Use `"manual"` or `"error"` to avoid
+     * leaking `Authorization`/cookies cross-origin when a server responds with a redirect.
+     */
+    redirect?: RequestRedirect;
+    /** Aborts in-flight requests when this signal fires. */
+    signal?: AbortSignal;
+    /** Per-request timeout in milliseconds; combined with `signal` via `AbortSignal.any`. */
+    timeoutMs?: number;
+    /** Escape hatch merged into every `fetch` RequestInit (lowest precedence — the options above win). */
+    requestInit?: RequestInit;
 }
 /**
  * An uninitialised pointer to a remote ZIP file.
@@ -283,7 +365,7 @@ export declare class RemoteZip {
  * const url = new URL("http://www.example.com/test.zip");
  * const remoteZip = await new RemoteZipPointer({ url }).populate();
  * const fileListing = remoteZip.files(); // RemoteZipFile[]
- * const uncompressedBytes = await remoteZip.fetch("test.txt"); // ArrayBuffer
+ * const uncompressedBytes = await remoteZip.fetch("test.txt"); // Uint8Array
  * ```
  */
 export declare class RemoteZipPointer {
@@ -297,7 +379,15 @@ export declare class RemoteZipPointer {
     method: string;
     /** Credentials passed to `fetch` when retrieving files. Defaults to `same-origin`. */
     credentials: "include" | "omit" | "same-origin";
-    constructor({ url, headUrl, additionalHeaders, method, credentials, }: {
+    /** Redirect mode passed to `fetch`. Defaults to `"follow"`. */
+    redirect?: RequestRedirect;
+    /** Signal that aborts in-flight requests. */
+    signal?: AbortSignal;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Extra RequestInit merged into every `fetch`. */
+    requestInit?: RequestInit;
+    constructor({ url, headUrl, additionalHeaders, method, credentials, redirect, signal, timeoutMs, requestInit, }: {
         /** URL for GET requests */
         url: URL;
         /** Passed to fetch when performing a HTTP GET request for the file */
@@ -308,15 +398,18 @@ export declare class RemoteZipPointer {
         credentials?: "include" | "omit" | "same-origin";
         /** URL for HEAD request. Defaults to `url`. This can, for example, differ from `url` if you are using a signed URL for S3. */
         headUrl?: URL;
-    });
+    } & Pick<RemoteZipRequestOptions, "redirect" | "signal" | "timeoutMs" | "requestInit">);
+    /** Build a fetch RequestInit from this pointer's network options. */
+    private requestInitFor;
     /**
      * Gets metadata about the ZIP file and constructs an initialised `RemoteZip`.
      *
-     * @returns An initialised [RemoteZip](RemoteZip)
-     * @throws [RemoteZipError](RemoteZipError) if it fails to parse or fetch
+     * @returns An initialised {@link RemoteZip}
+     * @throws {@link RemoteZipError} if it fails to parse or fetch
      */
     populate(): Promise<RemoteZip>;
     private fetchEndOfCentralDirectory;
+    private fetchZip64EOCD;
     private fetchCentralDirectoryRecords;
 }
 /**
@@ -328,3 +421,39 @@ export declare class RemoteZipPointer {
  * @see https://github.com/Stuk/jszip/blob/112fcdb9953c6b9a2744afee451d73029f7cd2f8/lib/reader/DataReader.js#L105
  */
 export declare const parseZipDatetime: (zipDate: number, zipTime: number) => string;
+/**
+ * Detects whether an EOCD record points at ZIP64 structures this library does
+ * not parse yet. Any ZIP64 sentinel value (`0xffff` for 16-bit fields,
+ * `0xffffffff` for 32-bit fields) means the real value lives in a ZIP64 EOCD.
+ */
+export declare const isZip64: (eocd: EndOfCentralDirectory) => boolean;
+/** Effective central-directory location from a ZIP64 End Of Central Directory record. */
+export interface Zip64EndOfCentralDirectory {
+    diskNumber: number;
+    cdDisk: number;
+    centralDirectoryDiskRecordCount: number;
+    centralDirectoryRecordCount: number;
+    centralDirectoryByteSize: number;
+    centralDirectoryByteOffset: number;
+}
+/** Locate the ZIP64 EOCD locator in a tail buffer and return the ZIP64 EOCD offset. */
+export declare const parseZip64EOCDLocator: (buffer: ArrayBuffer) => {
+    diskWithZip64EOCD: number;
+    zip64EOCDOffset: number;
+    totalDisks: number;
+} | null;
+/** Parse a ZIP64 End Of Central Directory record (the real CD offset/size/count). */
+export declare const parseZip64EOCD: (buffer: ArrayBuffer) => Zip64EndOfCentralDirectory | null;
+/**
+ * Decode a ZIP filename/comment. ZIP entries use CP437 unless general-purpose
+ * bit 11 marks the field as UTF-8; ASCII is identical in both.
+ */
+export declare const decodeZipString: (bytes: ArrayBuffer, utf8: boolean) => string;
+export declare const parseAllCDs: (buffer: ArrayBuffer) => CentralDirectoryRecord[];
+export declare const parseOneCD: (buffer: ArrayBuffer) => CentralDirectoryRecord | null;
+export declare const parseOneEOCD: (buffer: ArrayBuffer) => EndOfCentralDirectory | null;
+export declare const parseOneLocalFile: (buffer: ArrayBuffer, 
+/** Sometimes, the local header does not have the compressed size and a data descriptor is used after the compressed data.
+ * If provided, will be used if the local header indicates a data descriptor block.
+ * It is used to find the correct offset for the data descriptor. */
+compressedSizeOverride?: number) => LocalFileHeader | null;

package/package.json

@@ -1,57 +1,83 @@
 {
   "name": "@gyng/remote-zip",
-  "version": "0.2.5",
-  "main": "lib/cjs/index.js",
-  "module": "lib/esm/index.js",
-  "types": "lib/types/index.d.ts",
-  "author": "AIcadium, Ng Guoyou <gyng@users.noreply.github.com>",
-  "license": "MIT",
+  "version": "1.0.1",
+  "description": "Fetch file listings and individual files from a remote ZIP archive over HTTP Range requests, without downloading the whole archive.",
+  "keywords": [
+    "browser",
+    "central-directory",
+    "fetch",
+    "http",
+    "range",
+    "remote",
+    "stream",
+    "zip"
+  ],
+  "homepage": "https://github.com/gyng/remote-zip#readme",
+  "bugs": {
+    "url": "https://github.com/gyng/remote-zip/issues"
+  },
+  "license": "(MIT OR Apache-2.0)",
+  "author": "Ng Guoyou <gyng@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gyng/remote-zip.git"
+  },
   "files": [
-    "LICENSE",
+    "LICENSE-MIT",
+    "LICENSE-APACHE",
+    "README.md",
     "package.json",
     "lib/**"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/gyng/remote-zip.git"
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "lib/cjs/index.js",
+  "module": "lib/esm/index.mjs",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/types/index.d.mts",
+        "default": "./lib/esm/index.mjs"
+      },
+      "require": {
+        "types": "./lib/types/index.d.ts",
+        "default": "./lib/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "rm -rf lib/* && yarn ts-types && node ./esbuild.mjs",
-    "d:server": "http-server fixtures",
-    "d": "WATCH=1 yarn build",
-    "doc:gen": "yarn typedoc src/index.ts --excludePrivate --cleanOutputDir --logLevel Verbose --out ./docs/api",
-    "lint:eslint:fix": "yarn lint:eslint --fix",
-    "lint:eslint": "eslint . --ext .js --ext .jsx --ext .ts --ext .tsx",
-    "lint:fix": "yarn lint:prettier:fix && yarn lint:eslint:fix",
-    "lint:prettier:fix": "prettier --write .",
-    "lint:prettier": "prettier --check .",
-    "lint": "yarn lint:prettier && yarn lint:eslint",
-    "t:watch": "yarn test --watch",
-    "t": "yarn test",
-    "test:coverage": "yarn test --coverage",
-    "test": "jest",
-    "ts-types": " tsc --emitDeclarationOnly --outDir lib/types"
+    "build": "rm -rf lib/* && npm run ts-types && node ./esbuild.mjs",
+    "d": "WATCH=1 npm run build",
+    "doc:gen": "npm --prefix tools/typedoc run generate",
+    "doc:site": "npm run build && npm run doc:gen && node ./scripts/build-site.mjs",
+    "lint:fix": "oxfmt . && oxlint --type-aware --import-plugin --vitest-plugin --fix .",
+    "lint": "oxfmt --check . && oxlint --type-aware --import-plugin --vitest-plugin .",
+    "t:watch": "vitest",
+    "t": "npm test",
+    "test:coverage": "vitest run --coverage",
+    "test:package": "npm run build && node ./scripts/test-package.mjs",
+    "test": "vitest run",
+    "ts-types": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "pako": "^3.0.1"
   },
   "devDependencies": {
-    "@types/http-server": "^0.12.1",
-    "@types/jest": "^29.5.2",
-    "@types/node": "^20.3.1",
-    "@types/pako": "^2.0.0",
-    "@typescript-eslint/eslint-plugin": "^5.60.0",
-    "@typescript-eslint/parser": "^5.60.0",
-    "esbuild": "^0.18.7",
-    "esbuild-jest": "^0.5.0",
-    "eslint": "^8.43.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-plugin-jest": "^27.2.2",
-    "http-server": "^14.1.1",
-    "jest": "^29.5.0",
-    "prettier": "^2.8.8",
-    "typedoc": "^0.24.8",
-    "typescript": "^5.1.3"
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "esbuild": "^0.28.1",
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.73.0",
+    "oxlint-tsgolint": "^0.24.0",
+    "typescript": "~7.0.2",
+    "vitest": "^4.1.10"
   },
-  "dependencies": {
-    "cross-fetch": "^3.1.6",
-    "pako": "^2.1.0"
-  }
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "npm@11.11.0"
 }

package/lib/types/zip.test.d.ts

@@ -1 +0,0 @@
-export {};