@gyng/remote-zip 0.2.5

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2021 AIcadium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# remote-zip
+
+[API documentation](https://gyng.github.io/remote-zip)
+
+Fetch file listings and individual files from a remote ZIP file.
+
+## Features
+
+Without downloading the entire ZIP:
+
+- Fetch individual files in a remote ZIP
+- Fetch file listings
+
+The gist of what the library does is:
+
+1. Get the content size of the ZIP file using a HTTP HEAD request.
+2. Get the last 100 bytes using HTTP Range queries (hoping it's enough) to read the end-of-central-directory (EOCD) section.
+3. Using the EOCD, read the central directory (CD) section with a Range request. This section contains a complete file listing and file byte offsets in the ZIP.
+4. To get individual files, use another Range request with an offset to get the local file header + compressed data.
+
+## Limitations
+
+- No ZIP64 support
+- No encrypted ZIP support
+- No stream support via `ReadableStream` due to testing/dev difficulties
+- Long comments in a ZIP file might cause `populate()` to fail
+
+## Install
+
+```bash
+yarn add @gyng/remote-zip
+```
+
+```bash
+npm install --save @gyng/remote-zip
+```
+
+## Usage
+
+See the [generated API documentation](https://gyng.github.io/remote-zip/).
+
+If using in the browser, the server will need to whitelist CORS for `GET`, `HEAD`, and the `Range` header.
+
+### Basic
+
+```ts
+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
+```
+
+### With more features
+
+```ts
+const method = "POST";
+const additonalHeaders = new Headers();
+additonalHeaders.append("X-Example", "foobar");
+const url = new URL("http://www.example.com/test.zip");
+const remoteZip = await new RemoteZipPointer({
+  url,
+  additionalHeaders,
+  method,
+  credentials: "include",
+}).populate();
+const uncompressedBytes = await remoteZip.fetch("test.txt", additionalHeaders);
+```
+
+## Dev
+
+<details>
+<summary>Dev instructions</summary>
+See `scripts` in `package.json` for more scripts.
+
+- `yarn d` watch and build
+- `yarn t:watch` watch and test
+- `yarn lint`
+- `yarn build`
+
+Run tests and checks with Docker
+
+```
+docker-compose -f docker-compose.test.yml up --build
+```
+
+### Publish
+
+#### Setup
+
+1. Get an automation token from npm under settings
+
+   ```
+   https://www.npmjs.com/settings/aicadium/tokens/
+   ```
+
+2. Add the token to your repository secrets.
+
+   ```
+   https://github.com/$YOUR_USERNAME/$YOUR_REPO_NAME/settings/secrets/actions/new
+   ```
+
+   - Name: `NPM_TOKEN`
+   - Value: The automation token you got from the previous step
+
+#### Run
+
+1. Create a new release.
+
+   ```
+   https://github.com/$YOUR_USERNAME/$YOUR_REPO_NAME/releases
+   ```
+
+   The workflow at `./github/workflows/publish.yml` should run and publish your packages to both NPM and GitHub Packages.
+
+   Don't forget to bump your version number in `package.json` before this.
+   </details>

package/lib/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./zip";

package/lib/types/zip.d.ts

@@ -0,0 +1,330 @@
+export declare class RemoteZipError extends Error {
+    constructor(message: any);
+}
+export interface EndOfCentralDirectory {
+    meta: Record<string, unknown>;
+    data: {
+        /** End of central directory signature = 0x06054b50 */
+        signature: ArrayBuffer;
+        /** Number of this disk (or 0xffff for ZIP64) */
+        diskNumber: number;
+        /** Disk where central directory starts (or 0xffff for ZIP64) */
+        cdDisk: number;
+        /** Number of central directory records on this disk (or 0xffff for ZIP64) */
+        centralDirectoryDiskNumber: number;
+        /** Number of central directory records on this disk (or 0xffff for ZIP64) */
+        centralDirectoryRecordCount: number;
+        /** Size of central directory (bytes) (or 0xffffffff for ZIP64) */
+        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 */
+        commentLength: number;
+    };
+}
+export interface CentralDirectoryRecord {
+    meta: {
+        /** Length of the entire record */
+        length: number;
+    };
+    data: {
+        /** Central directory file header signature = 0x02014b50 */
+        signature: ArrayBuffer;
+        /** Version of the program this ZIP was made by.
+         *
+         * Upper byte:
+         * - 0 - MS-DOS and OS/2 (FAT / VFAT / FAT32 file systems)
+         * - 1 - Amiga
+         * - 2 - OpenVMS
+         * - 3 - UNIX
+         * - 4 - VM/CMS
+         * - 5 - Atari ST
+         * - 6 - OS/2 H.P.F.S.
+         * - 7 - Macintosh
+         * - 8 - Z-System
+         * - 9 - CP/M
+         * - 10 - Windows NTFS
+         * - 11 - MVS (OS/390 - Z/OS)
+         * - 12 - VSE
+         * - 13 - Acorn Risc
+         * - 14 - VFAT
+         * - 15 - alternate MVS
+         * - 16 - BeOS
+         * - 17 - Tandem
+         * - 18 - OS/400
+         * - 19 - OS/X (Darwin)
+         * - 20 - 255: Unused
+         */
+        versionMadeBy: number;
+        /** Version needed to extract (minimum) */
+        versionToExtract: number;
+        /** General purpose bit flag
+         *
+         * - Bit 00: encrypted file
+         * - Bit 01: compression option
+         * - Bit 02: compression option
+         * - Bit 03: data descriptor
+         * - Bit 04: enhanced deflation
+         * - Bit 05: compressed patched data
+         * - Bit 06: strong encryption
+         * - Bit 07-10: unused
+         * - Bit 11: language encoding
+         * - Bit 12: reserved
+         * - Bit 13: mask header values
+         * - Bit 14-15: reserved
+         */
+        generalPurposeBitFlag: number;
+        /** Compression method; e.g. none = 0, DEFLATE = 8 (or "\0x08\0x00")
+         *
+         * - 00: no compression
+         * - 01: shrunk
+         * - 02: reduced with compression factor 1
+         * - 03: reduced with compression factor 2
+         * - 04: reduced with compression factor 3
+         * - 05: reduced with compression factor 4
+         * - 06: imploded
+         * - 07: reserved
+         * - 08: deflated
+         * - 09: enhanced deflated
+         * - 10: PKWare DCL imploded
+         * - 11: reserved
+         * - 12: compressed using BZIP2
+         * - 13: reserved
+         * - 14: LZMA
+         * - 15-17: reserved
+         * - 18: compressed using IBM TERSE
+         * - 19: IBM LZ77 z
+         * - 98: PPMd version I, Rev 1
+         */
+        compressionMethod: number;
+        /** File last modification time (DOS) */
+        lastModifiedTime: number;
+        /** File last modification date (DOS) */
+        lastModifiedDate: number;
+        /** CRC-32 of uncompressed data
+         * Value computed over file data by CRC-32 algorithm with
+         * 'magic number' 0xdebb20e3 (little endian)
+         */
+        crc32: number;
+        /** Compressed size (or 0xffffffff for ZIP64) */
+        compressedSize: number;
+        /** Uncompressed size (or 0xffffffff for ZIP64) */
+        uncompressedSize: number;
+        /** File name length (n) */
+        filenameLength: number;
+        /** Extra field length (m) */
+        extraFieldLength: number;
+        /** File comment length (k) */
+        fileCommentLength: number;
+        /** Disk number where file starts */
+        startingDiskNumber: number;
+        /** Internal file attributes
+         *
+         * Bit 0: apparent ASCII/text file
+         * Bit 1: reserved
+         * Bit 2: control field records precede logical records
+         * Bits 3-16: unused
+         */
+        internalFileAttributes: number;
+        /** External file attributes (host-system dependent) */
+        externalFileAttributes: number;
+        /** Relative offset of local file header.
+         * This is the number of bytes between the start of the first
+         * disk on which the file occurs, and the start of the local file
+         * header. This allows software reading the central directory to
+         * locate the position of the file inside the ZIP file. */
+        localFileHeaderRelativeOffset: number;
+        /** File name */
+        filename: string;
+        /** Extra field
+         *
+         * Used to store additional information. The field consistes of a sequence of
+         * header and data pairs, where the header has a 2 byte identifier and a 2 byte data size field.
+         */
+        extraField: ArrayBuffer;
+        /** File comment */
+        fileComment: string;
+    };
+}
+export interface LocalFileHeader {
+    meta: {
+        compressedData: ArrayBuffer;
+        /** If the bit at offset 3 (0x08) of the general-purpose flags field is set,
+         * then the CRC-32 and file sizes are not known when the header is written.
+         * The fields in the local header are filled with zero, and the CRC-32 and size are
+         * appended in a 12-byte structure (optionally preceded by a 4-byte signature) immediately
+         * after the compressed data */
+        dataDescriptor?: {
+            /** Optional data descriptor signature = 0x08074b50 */
+            optionalSignature?: ArrayBuffer;
+            /** CRC-32 of uncompressed data */
+            crc32: number;
+            /** Compressed size */
+            compressedSize: number;
+            /** Uncompressed size */
+            uncompressedSize: number;
+        };
+    };
+    data: {
+        /** Local file header signature = 0x04034b50 (PK♥♦ or "PK\3\4") */
+        signature: ArrayBuffer;
+        /** Version needed to extract (minimum) */
+        versionToExtract: number;
+        /** General purpose bit flag  */
+        generalPurposeBitFlag: number;
+        /** Compression method; e.g. none = 0, DEFLATE = 8 (or "\0x08\0x00") */
+        compressionMethod: number;
+        /** File last modification time (DOS format) */
+        lastModifiedTime: number;
+        /** File last modification date (DOS format) */
+        lastModifiedDate: number;
+        /** CRC-32 of uncompressed data
+         * Value computed over file data by CRC-32 algorithm with
+         * 'magic number' 0xdebb20e3 (little endian)
+         */
+        crc32: number;
+        /** Compressed size (or 0xffffffff for ZIP64) */
+        compressedSize: number;
+        /** Uncompressed size (or 0xffffffff for ZIP64) */
+        uncompressedSize: number;
+        /** File name length (n) */
+        filenameLength: number;
+        /** Extra field length (m) */
+        extraFieldLength: number;
+        /** File name */
+        filename: string;
+        /** Extra field */
+        extraField: ArrayBuffer;
+    };
+}
+/**
+ * A friendly representation of a file inside a ZIP archive
+ */
+export interface RemoteZipFile {
+    /** Full path of the file inside the archive */
+    filename: string;
+    /** Size in bytes */
+    size: number;
+    /** ISO timestamp without timezone (ZIP/DOS does not preserve timezones) */
+    modified: string;
+    /** File attributes of host system */
+    attributes: number;
+}
+/**
+ * An initialised object representating a remote ZIP archive.
+ *
+ * Best constructed from a `RemoteZipPointer`.
+ *
+ * ```ts
+ * import { RemoteZipPointer } from "remote-zip";
+ *
+ * const url = new URL("http://www.example.com/test.zip");
+ * const remoteZip = await new RemoteZipPointer({ url }).populate();
+ * ```
+ */
+export declare class RemoteZip {
+    /** Size of the remote ZIP archive in bytes */
+    contentLength: number;
+    /** URL of the remote ZIP archive */
+    url: URL;
+    /** Records representing the files in the remote ZIP archive */
+    centralDirectoryRecords: CentralDirectoryRecord[];
+    /** Metadata of the remote ZIP archive */
+    endOfCentralDirectory: EndOfCentralDirectory | null;
+    /** HTTP method used to fetch files from the remote ZIP archive */
+    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, }: {
+        /** Length of the remote ZIP archive in bytes */
+        contentLength: number;
+        /** Passed to fetch when performing a HTTP GET request for the file */
+        url: URL;
+        centralDirectoryRecords: CentralDirectoryRecord[];
+        endOfCentralDirectory: EndOfCentralDirectory | null;
+        /** 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";
+    });
+    /**
+     * Get a formatted file listing of the remote ZIP archive.
+     *
+     * @returns List of files in the remote ZIP archive.
+     *
+     * ```ts
+     * import { RemoteZipPointer } from "remote-zip";
+     *
+     * const url = new URL("http://www.example.com/test.zip");
+     * const remoteZip = await new RemoteZipPointer({ url }).populate();
+     * const files = remoteZip.files();
+     * // files = [{ attributes: 1107099648, filename: "text.txt", modified: "2021-06-17T12:28:02", size: 14 }]
+     * ```
+     */
+    files(): RemoteZipFile[];
+    /**
+     * Gets a single uncompressed file in the remote ZIP archive.
+     *
+     * @param path Path of the file in the remote ZIP archive
+     * @param additionalHeaders Additional headers, if any, to be passed to the `fetch` request
+     * @returns Inflated (uncompressed) bytes of the requested file
+     * @throws [RemoteZipError](RemoteZipError) if it fails to parse or fetch
+     */
+    fetch(path: string, additionalHeaders?: Headers): Promise<ArrayBuffer>;
+}
+/**
+ * An uninitialised pointer to a remote ZIP file.
+ *
+ * No network requests are sent until `populate()` is called.
+ *
+ * ```ts
+ * 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
+ * ```
+ */
+export declare class RemoteZipPointer {
+    /** URL of the remote ZIP archive */
+    url: URL;
+    /** URL used when performing the HTTP HEAD request to fetch ZIP metadata */
+    headUrl: URL;
+    /** Additional headers, if any, passed to `fetch` when calling `url` or `headUrl` */
+    additionalHeaders?: Headers;
+    /** HTTP method used to fetch ZIP metadata (the initial HEAD request is always sent) */
+    method: string;
+    /** Credentials passed to `fetch` when retrieving files. Defaults to `same-origin`. */
+    credentials: "include" | "omit" | "same-origin";
+    constructor({ url, headUrl, additionalHeaders, method, credentials, }: {
+        /** URL for GET requests */
+        url: URL;
+        /** Passed to fetch when performing a HTTP GET request for the file */
+        additionalHeaders?: Headers;
+        /** 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";
+        /** 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;
+    });
+    /**
+     * 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
+     */
+    populate(): Promise<RemoteZip>;
+    private fetchEndOfCentralDirectory;
+    private fetchCentralDirectoryRecords;
+}
+/**
+ * Parses DOS datetime into an ISO string without timezone.
+ *
+ * @param zipDate DOS date format
+ * @param zipTime DOS time format
+ * @returns An ISO datetime without timezone. Defaults to `"1980-01-01T00:00:00"` if the datetime is invalid
+ * @see https://github.com/Stuk/jszip/blob/112fcdb9953c6b9a2744afee451d73029f7cd2f8/lib/reader/DataReader.js#L105
+ */
+export declare const parseZipDatetime: (zipDate: number, zipTime: number) => string;

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

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "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",
+  "files": [
+    "LICENSE",
+    "package.json",
+    "lib/**"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/gyng/remote-zip.git"
+  },
+  "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"
+  },
+  "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"
+  },
+  "dependencies": {
+    "cross-fetch": "^3.1.6",
+    "pako": "^2.1.0"
+  }
+}