@procedures/archive 0.0.0-stage → 0.3.0

package/dist/tar.js

@@ -0,0 +1,193 @@
+/**
+ * Tar and tar.gz archives with `tar` (node-tar), the tar library of npm.
+ *
+ * - The list reads the headers with a `Parser`. It stops at the limit of entries or of bytes, so a
+ *   compressed archive with a very large content stops early.
+ * - The extract runs after the check of `planExtract()`. It keeps the protections of node-tar:
+ *   no absolute path, no `..`, and no write through a symbolic link. Its filter lets only the
+ *   checked entries through, and `strict` makes each warning an error.
+ */
+import { createReadStream } from "node:fs";
+import { createGunzip, gzipSync } from "node:zlib";
+import { open, writeFile } from "node:fs/promises";
+import { create, extract, Parser } from "tar";
+import { ArchiveError } from "./errors.js";
+/** The kind of a tar entry type. */
+function kindOf(type) {
+    switch (type) {
+        case "File":
+        case "OldFile":
+        case "ContiguousFile":
+            return "file";
+        case "Directory":
+            return "directory";
+        case "SymbolicLink":
+            return "symlink";
+        case "Link":
+            return "hardlink";
+        default:
+            return "other";
+    }
+}
+/** An error of node-tar as an `ArchiveError`. */
+function archiveErrorOf(error) {
+    if (error instanceof ArchiveError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return new ArchiveError("BAD_ARCHIVE", `The tar archive is damaged: ${message}`);
+}
+/** The most zero bytes of an empty tar: an empty tar of GNU tar has 10240. */
+const MAX_EMPTY_TAR_BYTES = 1024 * 1024;
+/**
+ * True when the content of a tar or tar.gz archive is only zero bytes: an archive without
+ * entries. node-tar calls such an archive "unrecognized". The check reads at most 1 MiB.
+ */
+async function isEmptyTar(path) {
+    const head = Buffer.alloc(2);
+    const handle = await open(path, "r");
+    try {
+        await handle.read(head, 0, 2, 0);
+    }
+    finally {
+        await handle.close();
+    }
+    const input = createReadStream(path);
+    const stream = head[0] === 0x1f && head[1] === 0x8b ? input.pipe(createGunzip()) : input;
+    let bytes = 0;
+    try {
+        for await (const chunk of stream) {
+            bytes += chunk.length;
+            if (bytes > MAX_EMPTY_TAR_BYTES || chunk.some((byte) => byte !== 0))
+                return false;
+        }
+        return bytes > 0;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        input.destroy();
+    }
+}
+/**
+ * This function reads the headers of a tar or tar.gz archive. It throws `TOO_LARGE` at more than
+ * `maxEntries` entries or more than `maxBytes` bytes of files.
+ */
+export async function readTarEntries(path, limits) {
+    try {
+        return await parseTarEntries(path, limits);
+    }
+    catch (error) {
+        if (error instanceof ArchiveError && error.code === "BAD_ARCHIVE" && error.message.includes("TAR_BAD_ARCHIVE") && (await isEmptyTar(path)))
+            return [];
+        throw error;
+    }
+}
+async function parseTarEntries(path, limits) {
+    const entries = [];
+    let bytes = 0;
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const input = createReadStream(path);
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (error === undefined) {
+                resolve();
+                return;
+            }
+            input.destroy();
+            reject(archiveErrorOf(error));
+        };
+        const parser = new Parser({
+            strict: true,
+            onReadEntry: (entry) => {
+                entry.resume();
+                if (settled)
+                    return;
+                const kind = kindOf(entry.type);
+                if (kind === "file")
+                    bytes += entry.size;
+                if (entries.length >= limits.maxEntries) {
+                    finish(new ArchiveError("TOO_LARGE", `The archive has more entries than the limit of ${limits.maxEntries}`));
+                    return;
+                }
+                if (bytes > limits.maxBytes) {
+                    finish(new ArchiveError("TOO_LARGE", `The files of the archive have more than ${limits.maxBytes} bytes`, entry.path));
+                    return;
+                }
+                entries.push({
+                    name: entry.path,
+                    kind,
+                    size: entry.size,
+                    mode: entry.mode,
+                    mtime: entry.mtime,
+                    linkTarget: entry.linkpath === undefined || entry.linkpath === "" ? undefined : entry.linkpath,
+                });
+            },
+        });
+        parser.on("warn", (code, message) => finish(new ArchiveError("BAD_ARCHIVE", `The tar archive is damaged: ${code} ${message instanceof Error ? message.message : message}`)));
+        parser.on("error", (error) => finish(error));
+        parser.on("end", () => finish());
+        input.on("error", (error) => finish(error));
+        input.on("data", (chunk) => {
+            if (settled)
+                return;
+            if (!parser.write(chunk)) {
+                input.pause();
+                parser.once("drain", () => input.resume());
+            }
+        });
+        input.on("end", () => {
+            if (!settled)
+                parser.end();
+        });
+    });
+    return entries;
+}
+/**
+ * This function extracts a tar or tar.gz archive into `target`, after the check. Only the names
+ * of `allowed` pass the filter. A name that the check did not see is an error at the end.
+ */
+export async function extractTar(path, target, allowed) {
+    const refused = [];
+    try {
+        await extract({
+            file: path,
+            cwd: target,
+            strict: true,
+            preservePaths: false,
+            preserveOwner: false,
+            // Remove an old file before the new one: the write never goes through a link or into a hard link
+            unlink: true,
+            filter: (name) => {
+                if (allowed.has(name))
+                    return true;
+                refused.push(name);
+                return false;
+            },
+        });
+    }
+    catch (error) {
+        throw archiveErrorOf(error);
+    }
+    const unexpected = refused.filter((name) => name.split(/[/\\]+/).some((part) => part !== "" && part !== "."));
+    if (unexpected.length > 0) {
+        throw new ArchiveError("BAD_ARCHIVE", `The archive changed during the extract: ${unexpected[0]} was not in the check`, unexpected[0]);
+    }
+}
+/**
+ * This function writes a tar or tar.gz archive of the `names` (relative to `cwd`) to `file`. The
+ * names are the full list: the walk of `archive.create` gives each file and folder.
+ */
+export async function createTar(file, cwd, names, gzip) {
+    if (names.length === 0) {
+        // An empty tar: two blocks of zeros
+        const empty = Buffer.alloc(1024);
+        await writeFile(file, gzip ? gzipSync(empty) : empty, { flag: "wx" });
+        return;
+    }
+    await create({ file, cwd, gzip, portable: true, follow: false, noDirRecurse: true }, [...names]);
+}
+//# sourceMappingURL=tar.js.map

package/dist/tar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tar.js","sourceRoot":"","sources":["../src/tar.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here. The zod schemas are in
+ * `module.ts`: an exported schema needs a written type (isolatedDeclarations).
+ */
+/** The formats of an archive. `tar` is a tar file without compression. */
+export type ArchiveFormat = "tar.gz" | "tar" | "zip";
+/** The kind of an entry of an archive. `other` is a device, a FIFO or another special file. */
+export type ArchiveEntryKind = "file" | "directory" | "symlink" | "hardlink" | "other";
+export interface ArchiveCreateInput {
+    /** The archive to make. */
+    output: string;
+    /** A folder: the archive gets its content, with paths relative to the folder. */
+    source?: string | undefined;
+    /** Files and folders, relative to `cwd`. A folder goes in with its content. */
+    files?: string[] | undefined;
+    /** The base folder of `files`. The default is the working folder of the process. */
+    cwd?: string | undefined;
+    /** The format. The default comes from the name of `output`: `.tar.gz`, `.tgz`, `.tar` or `.zip`. */
+    format?: ArchiveFormat | undefined;
+    /** True: replace an existing archive. The default is false: an existing archive is an error. */
+    overwrite?: boolean | undefined;
+}
+export interface ArchiveCreateOutput {
+    /** The absolute path of the archive. */
+    path: string;
+    format: ArchiveFormat;
+    /** The number of entries: files, folders and links. */
+    entries: number;
+    /** The size of the archive, in bytes. */
+    bytes: number;
+}
+export interface ArchiveExtractInput {
+    /** The archive. */
+    archive: string;
+    /** The folder that gets the content. The procedure makes it when it does not exist. */
+    target: string;
+    /** The format. The default comes from the first bytes of the archive. */
+    format?: ArchiveFormat | undefined;
+    /** True: replace an existing file. The default is false: an existing file is an error, and nothing changes. */
+    overwrite?: boolean | undefined;
+}
+export interface ArchiveExtractOutput {
+    /** The absolute path of the target folder. */
+    target: string;
+    format: ArchiveFormat;
+    files: number;
+    directories: number;
+    /** The symbolic links and the hard links. */
+    links: number;
+    /** The bytes of the files. */
+    bytes: number;
+}
+export interface ArchiveListInput {
+    /** The archive. */
+    archive: string;
+    /** The format. The default comes from the first bytes of the archive. */
+    format?: ArchiveFormat | undefined;
+}
+/** One entry of an archive. */
+export interface ArchiveEntry {
+    /** The path in the archive, as the archive has it. */
+    path: string;
+    kind: ArchiveEntryKind;
+    /** The size of the content, in bytes. */
+    size: number;
+    /** The mode bits (`0o644`), when the archive has them. */
+    mode?: number | undefined;
+    /** The time of the last change, as an ISO text, when the archive has it. */
+    mtime?: string | undefined;
+    /** The target of a link. */
+    linkTarget?: string | undefined;
+}
+export interface ArchiveListOutput {
+    format: ArchiveFormat;
+    entries: ArchiveEntry[];
+    /** The sum of the sizes of the entries, in bytes. */
+    bytes: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AAErD,+FAA+F;AAC/F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;AAMvF,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7B,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,oGAAoG;IACpG,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACnC,gGAAgG;IAChG,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,MAAM,WAAW,mBAAmB;IAClC,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACnC,+GAA+G;IAC/G,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CACpC;AAED,+BAA+B;AAC/B,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here. The zod schemas are in
+ * `module.ts`: an exported schema needs a written type (isolatedDeclarations).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/walk.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The walk of `archive.create`: each file, folder and symbolic link under the inputs, in a fixed
+ * order. The walk does not follow a link: the archive gets the link itself.
+ */
+/** One path for the archive. */
+export interface WalkEntry {
+    /** The name in the archive: relative, with `/`. */
+    readonly name: string;
+    /** The absolute path on the disk. */
+    readonly path: string;
+    readonly kind: "file" | "directory" | "symlink";
+    readonly size: number;
+    readonly mode: number;
+    readonly mtime: Date;
+    readonly linkTarget?: string | undefined;
+}
+/** The limits and the paths to leave out (the new archive and its temporary file). */
+export interface WalkOptions {
+    readonly maxEntries: number;
+    readonly maxBytes: number;
+    readonly exclude: ReadonlySet<string>;
+}
+/**
+ * This function gives the target of a link with `/`, as an archive keeps it. Windows gives `..\a.txt`
+ * for a link that Node made from `../a.txt`. On the other systems, a `\` is a part of a name.
+ */
+export declare function portableLinkTarget(target: string, separator?: string): string;
+/** This function walks the names (relative to `base`) and gives each entry for the archive. */
+export declare function walk(base: string, names: readonly string[], options: WalkOptions): Promise<WalkEntry[]>;
+/** The names of the content of a folder, sorted. */
+export declare function folderNames(folder: string): Promise<string[]>;
+/** The absolute path of a name under a base. */
+export declare function under(base: string, name: string): string;
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,gCAAgC;AAChC,MAAM,WAAW,SAAS;IACxB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACvC;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,MAAM,CAElF;AAED,+FAA+F;AAC/F,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAkC7G;AAED,oDAAoD;AACpD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnE;AAED,gDAAgD;AAChD,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/walk.js

@@ -0,0 +1,67 @@
+/**
+ * The walk of `archive.create`: each file, folder and symbolic link under the inputs, in a fixed
+ * order. The walk does not follow a link: the archive gets the link itself.
+ */
+import { lstat, readdir, readlink } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { ArchiveError } from "./errors.js";
+const byName = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * This function gives the target of a link with `/`, as an archive keeps it. Windows gives `..\a.txt`
+ * for a link that Node made from `../a.txt`. On the other systems, a `\` is a part of a name.
+ */
+export function portableLinkTarget(target, separator = sep) {
+    return separator === "\\" ? target.replaceAll("\\", "/") : target;
+}
+/** This function walks the names (relative to `base`) and gives each entry for the archive. */
+export async function walk(base, names, options) {
+    const entries = [];
+    const seen = new Set();
+    let bytes = 0;
+    const visit = async (name) => {
+        const path = resolve(base, ...name.split("/"));
+        if (options.exclude.has(path) || seen.has(name))
+            return;
+        seen.add(name);
+        let stats;
+        try {
+            stats = await lstat(path);
+        }
+        catch {
+            throw new ArchiveError("UNSAFE_PATH", `${path} does not exist`, name);
+        }
+        if (entries.length >= options.maxEntries)
+            throw new ArchiveError("TOO_LARGE", `The archive gets more entries than the limit of ${options.maxEntries}`, name);
+        const common = { name, path, size: 0, mode: stats.mode & 0o7777, mtime: stats.mtime };
+        if (stats.isSymbolicLink()) {
+            entries.push({ ...common, kind: "symlink", linkTarget: portableLinkTarget(await readlink(path)) });
+        }
+        else if (stats.isDirectory()) {
+            entries.push({ ...common, kind: "directory" });
+            const children = (await readdir(path)).sort(byName);
+            for (const child of children)
+                await visit(`${name}/${child}`);
+        }
+        else if (stats.isFile()) {
+            bytes += stats.size;
+            if (bytes > options.maxBytes)
+                throw new ArchiveError("TOO_LARGE", `The files have more than ${options.maxBytes} bytes`, name);
+            entries.push({ ...common, kind: "file", size: stats.size });
+        }
+        else {
+            throw new ArchiveError("UNSUPPORTED_ENTRY", `${path} is a special file (a socket, a device or a FIFO)`, name);
+        }
+    };
+    for (const name of names)
+        await visit(name);
+    return entries;
+}
+/** The names of the content of a folder, sorted. */
+export async function folderNames(folder) {
+    return (await readdir(folder)).sort(byName);
+}
+/** The absolute path of a name under a base. */
+export function under(base, name) {
+    return join(base, ...name.split("/"));
+}
+//# sourceMappingURL=walk.js.map

package/dist/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"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"}

package/dist/zip.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Zip archives on `node:zlib` (roadmap R46).
+ *
+ * The package reads and writes zip itself, for two reasons. The reader needs the external
+ * attributes of each entry, to see a symbolic link, and a limit on the bytes of each entry
+ * against a zip bomb. A zip library that decodes in memory gives neither.
+ *
+ * - The reader takes the central directory: stored and deflated entries, UTF-8 names, and the
+ *   zip64 fields. It refuses an encrypted entry, another method and an archive on more disks.
+ * - The extract streams each entry and stops when it gets more bytes than the entry declares.
+ *   It examines the size and the CRC-32 of each entry.
+ * - The writer stores each file, or deflates it when that is smaller. It writes no zip64 fields:
+ *   it refuses more than 65535 entries and an archive of 4 GiB or more.
+ */
+import { type FileHandle } from "node:fs/promises";
+/** The CRC-32 of bytes, continued from `crc` (0 for new bytes). */
+export declare function crc32(bytes: Uint8Array, crc?: number): number;
+/** One entry of the central directory. */
+export interface ZipEntry {
+    readonly name: string;
+    readonly kind: "file" | "directory" | "symlink";
+    readonly method: number;
+    readonly flags: number;
+    readonly crc: number;
+    readonly compressedSize: number;
+    readonly size: number;
+    readonly localOffset: number;
+    /** The mode bits of a Unix entry, without the type. */
+    readonly mode: number | undefined;
+    readonly mtime: Date;
+}
+/** This function reads the central directory of a zip. It throws `TOO_LARGE` for more than `maxEntries` entries. */
+export declare function readZipDirectory(path: string, maxEntries: number): Promise<ZipEntry[]>;
+/**
+ * This function writes the content of a file entry to `destination`, with the checks. The file
+ * must not exist: the caller removes an old file first, so the write never follows a link.
+ */
+export declare function extractZipFile(archive: string, entry: ZipEntry, destination: string, mode?: number): Promise<void>;
+/** This function gives the target of a symbolic link entry: its content, as text. */
+export declare function readZipLink(archive: string, entry: ZipEntry): Promise<string>;
+/** One entry for the writer. */
+export interface ZipWriteEntry {
+    /** The name in the archive. A folder ends with `/`: the writer adds it. */
+    readonly name: string;
+    readonly kind: "file" | "directory" | "symlink";
+    /** The content of a file, or the target of a link as UTF-8. A function loads it when the writer needs it. */
+    readonly data?: Uint8Array | (() => Promise<Uint8Array>) | undefined;
+    /** The mode bits, without the type. */
+    readonly mode?: number | undefined;
+    readonly mtime?: Date | undefined;
+}
+/**
+ * This function writes a zip to an open file. The names are not examined here: `archive.create`
+ * gives only the relative paths of a walk, and a test gives hostile names on purpose.
+ */
+export declare function writeZip(handle: FileHandle, entries: readonly ZipWriteEntry[]): Promise<number>;
+//# sourceMappingURL=zip.d.ts.map

package/dist/zip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip.d.ts","sourceRoot":"","sources":["../src/zip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAuCzD,mEAAmE;AACnE,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,SAAI,GAAG,MAAM,CAIxD;AAMD,0CAA0C;AAC1C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;CACtB;AAkFD,oHAAoH;AACpH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CA0E5F;AAwED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAExH;AAED,qFAAqF;AACrF,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAWnF;AAMD,gCAAgC;AAChC,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAChD,6GAA6G;IAC7G,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,SAAS,CAAC;IACrE,uCAAuC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoErG"}