@procedures/archive 0.0.0-stage → 0.3.0

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The errors of the archive procedures.
+ */
+/** The reason of an `ArchiveError`. */
+export type ArchiveErrorCode = 
+/** The format is not known, or it is not the format of the file. */
+"BAD_FORMAT"
+/** The archive is damaged, or it uses a feature that the package does not read. */
+ | "BAD_ARCHIVE"
+/** A path exists already: the archive of `create`, or a file of `extract` without `overwrite`. */
+ | "EXISTS"
+/** A path of the input or an entry of the archive is not safe: `..`, an absolute path, or a way through a link. */
+ | "UNSAFE_PATH"
+/** A link of the archive goes out of the target folder, or a hard link names no file of the archive. */
+ | "UNSAFE_LINK"
+/** The archive has an entry that the package does not extract: a device, a FIFO or another special file. */
+ | "UNSUPPORTED_ENTRY"
+/** The archive has more entries or more bytes than the limits of the module. */
+ | "TOO_LARGE";
+/** An error of an archive procedure. `entry` names the entry of the archive, when one is the cause. */
+export declare class ArchiveError extends Error {
+    readonly name = "ArchiveError";
+    readonly code: ArchiveErrorCode;
+    readonly entry: string | undefined;
+    constructor(code: ArchiveErrorCode, message: string, entry?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,uCAAuC;AACvC,MAAM,MAAM,gBAAgB;AAC1B,oEAAoE;AAClE,YAAY;AACd,mFAAmF;GACjF,aAAa;AACf,kGAAkG;GAChG,QAAQ;AACV,mHAAmH;GACjH,aAAa;AACf,wGAAwG;GACtG,aAAa;AACf,4GAA4G;GAC1G,mBAAmB;AACrB,gFAAgF;GAC9E,WAAW,CAAC;AAEhB,uGAAuG;AACvG,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAkB,IAAI,kBAAkB;IACxC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnC,YAAY,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAIlE;CACF"}

package/dist/errors.js

@@ -0,0 +1,15 @@
+/**
+ * The errors of the archive procedures.
+ */
+/** An error of an archive procedure. `entry` names the entry of the archive, when one is the cause. */
+export class ArchiveError extends Error {
+    name = "ArchiveError";
+    code;
+    entry;
+    constructor(code, message, entry) {
+        super(message);
+        this.code = code;
+        this.entry = entry;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmBH,uGAAuG;AACvG,MAAM,OAAO,YAAa,SAAQ,KAAK;IACnB,IAAI,GAAG,cAAc,CAAC;IAC/B,IAAI,CAAmB;IACvB,KAAK,CAAqB;IAEnC,YAAY,IAAsB,EAAE,OAAe,EAAE,KAAc;QACjE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/dist/format.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The format of an archive: from the name of a new archive, or from the first bytes of a file.
+ * And the limits of the module.
+ */
+import type { ArchiveFormat } from "./types.js";
+/** The limits of the procedures of a module. */
+export interface ArchiveSettings {
+    /** The most bytes of the files of one archive: `extract` and `create` refuse more. */
+    readonly maxBytes: number;
+    /** The most entries of one archive. */
+    readonly maxEntries: number;
+}
+/** The default most bytes: 1 GiB. */
+export declare const DEFAULT_MAX_BYTES: number;
+/** The default most entries. */
+export declare const DEFAULT_MAX_ENTRIES = 100000;
+/** The settings of the default module. */
+export declare const DEFAULT_ARCHIVE_SETTINGS: ArchiveSettings;
+/** The format of a new archive from its name, or the format of the input. */
+export declare function formatOfName(path: string, given: ArchiveFormat | undefined): ArchiveFormat;
+/** The format that the first bytes of a file show, or undefined. */
+export declare function sniffFormat(path: string): Promise<ArchiveFormat | undefined>;
+/** The format of an existing archive: its first bytes, which must agree with the format of the input. */
+export declare function formatOfFile(path: string, given: ArchiveFormat | undefined): Promise<ArchiveFormat>;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,qCAAqC;AACrC,eAAO,MAAM,iBAAiB,EAAE,MAA2B,CAAC;AAC5D,gCAAgC;AAChC,eAAO,MAAM,mBAAmB,SAAU,CAAC;AAE3C,0CAA0C;AAC1C,eAAO,MAAM,wBAAwB,EAAE,eAAiG,CAAC;AAEzI,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,aAAa,CAO1F;AAED,oEAAoE;AACpE,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAclF;AAED,yGAAyG;AACzG,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAUzG"}

package/dist/format.js

@@ -0,0 +1,60 @@
+/**
+ * The format of an archive: from the name of a new archive, or from the first bytes of a file.
+ * And the limits of the module.
+ */
+import { open } from "node:fs/promises";
+import { ArchiveError } from "./errors.js";
+/** The default most bytes: 1 GiB. */
+export const DEFAULT_MAX_BYTES = 1024 * 1024 * 1024;
+/** The default most entries. */
+export const DEFAULT_MAX_ENTRIES = 100_000;
+/** The settings of the default module. */
+export const DEFAULT_ARCHIVE_SETTINGS = Object.freeze({ maxBytes: DEFAULT_MAX_BYTES, maxEntries: DEFAULT_MAX_ENTRIES });
+/** The format of a new archive from its name, or the format of the input. */
+export function formatOfName(path, given) {
+    if (given !== undefined)
+        return given;
+    const name = path.toLowerCase();
+    if (name.endsWith(".tar.gz") || name.endsWith(".tgz"))
+        return "tar.gz";
+    if (name.endsWith(".tar"))
+        return "tar";
+    if (name.endsWith(".zip"))
+        return "zip";
+    throw new ArchiveError("BAD_FORMAT", `The name ${path} does not tell the format: give format, or end the name with .tar.gz, .tgz, .tar or .zip`);
+}
+/** The format that the first bytes of a file show, or undefined. */
+export async function sniffFormat(path) {
+    const handle = await open(path, "r");
+    try {
+        const head = Buffer.alloc(512);
+        const { bytesRead } = await handle.read(head, 0, 512, 0);
+        if (bytesRead >= 2 && head[0] === 0x1f && head[1] === 0x8b)
+            return "tar.gz";
+        if (bytesRead >= 4 && head[0] === 0x50 && head[1] === 0x4b && ((head[2] === 3 && head[3] === 4) || (head[2] === 5 && head[3] === 6)))
+            return "zip";
+        if (bytesRead >= 262 && head.toString("latin1", 257, 262) === "ustar")
+            return "tar";
+        // An empty tar: zero blocks without a header
+        if (bytesRead === 512 && head.every((byte) => byte === 0))
+            return "tar";
+        return undefined;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** The format of an existing archive: its first bytes, which must agree with the format of the input. */
+export async function formatOfFile(path, given) {
+    const found = await sniffFormat(path);
+    if (found === undefined) {
+        if (given === "tar")
+            return "tar";
+        throw new ArchiveError("BAD_FORMAT", `${path} is not a tar.gz, tar or zip archive`);
+    }
+    if (given !== undefined && given !== found) {
+        throw new ArchiveError("BAD_FORMAT", `${path} is a ${found} archive, not a ${given} archive`);
+    }
+    return found;
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./module.js";
+export * from "./types.js";
+export { archiveCreate, archiveExtract, archiveList } from "./procedures/archive/index.js";
+export { ArchiveError, type ArchiveErrorCode } from "./errors.js";
+export { DEFAULT_ARCHIVE_SETTINGS, DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES, formatOfFile, formatOfName, sniffFormat, type ArchiveSettings } from "./format.js";
+export { entryParts, isAbsoluteName, planExtract, type PlanOptions, type PlannedEntry, type RawEntry } from "./paths.js";
+export { crc32, readZipDirectory, writeZip, type ZipEntry, type ZipWriteEntry } from "./zip.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAE3F,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9J,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AACzH,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// The root registers nothing: import "<package>/register", or give the module to createRegistry()
+export * from "./module.js";
+export * from "./types.js";
+export { archiveCreate, archiveExtract, archiveList } from "./procedures/archive/index.js";
+// The checks and the formats (roadmap R46)
+export { ArchiveError } from "./errors.js";
+export { DEFAULT_ARCHIVE_SETTINGS, DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES, formatOfFile, formatOfName, sniffFormat } from "./format.js";
+export { entryParts, isAbsoluteName, planExtract } from "./paths.js";
+export { crc32, readZipDirectory, writeZip } from "./zip.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC3F,2CAA2C;AAC3C,OAAO,EAAE,YAAY,EAAyB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC;AAC9J,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAsD,MAAM,YAAY,CAAC;AACzH,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAqC,MAAM,UAAU,CAAC"}

package/dist/module.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The procedures of @procedures/archive as data. Importing this file registers nothing.
+ *
+ * Scaffold a procedure with: mark procedure new <name> --path packages/archive
+ *
+ * `archiveModule` has the default limits: 1 GiB of files and 100000 entries in one archive.
+ * `createArchiveModule()` gives the same procedures with other limits (roadmap R46).
+ */
+import { type ProcedureModule, type ProcedureRegistry } from "@procedures/client";
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data, with the default
+ * limits. Importing this file registers nothing.
+ */
+export declare const archiveModule: ProcedureModule;
+export default archiveModule;
+/** The options of `createArchiveModule()`. */
+export interface ArchiveModuleOptions {
+    /** The most bytes of the files of one archive. The default is 1 GiB. */
+    readonly maxBytes?: number | undefined;
+    /** The most entries of one archive. The default is 100000. */
+    readonly maxEntries?: number | undefined;
+}
+/**
+ * This function gives the module of this package with other limits. Without options, it gives
+ * `archiveModule`. A host gives it to `createRegistry()` before its bundles, so it replaces the
+ * `archiveModule` that a bundle requires (the first module of a name counts).
+ */
+export declare function createArchiveModule(options?: ArchiveModuleOptions): ProcedureModule;
+/**
+ * This function registers the procedures of @procedures/archive in a registry. The default is the
+ * global registry. The options are the options of `createArchiveModule()`.
+ */
+export declare function registerArchiveProcedures(registry?: ProcedureRegistry, options?: ArchiveModuleOptions): void;
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAQL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAoI5B;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eAAkG,CAAC;eAEhH,aAAa;AAE5B,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,eAAe,CAUvF;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,GAAE,iBAAsC,EAAE,OAAO,GAAE,oBAAyB,GAAG,IAAI,CAEpI"}

package/dist/module.js

@@ -0,0 +1,148 @@
+/**
+ * The procedures of @procedures/archive as data. Importing this file registers nothing.
+ *
+ * Scaffold a procedure with: mark procedure new <name> --path packages/archive
+ *
+ * `archiveModule` has the default limits: 1 GiB of files and 100000 entries in one archive.
+ * `createArchiveModule()` gives the same procedures with other limits (roadmap R46).
+ */
+import { z } from "zod";
+import { defineModule, registerModules, PROCEDURE_REGISTRY, createProcedure, zodAdapter, } from "@procedures/client";
+import { archiveCreate } from "./procedures/archive/create.js";
+import { archiveExtract } from "./procedures/archive/extract.js";
+import { archiveList } from "./procedures/archive/list.js";
+import { DEFAULT_ARCHIVE_SETTINGS } from "./format.js";
+// =============================================================================
+// Schemas
+// =============================================================================
+const path = (description) => z.string().min(1).max(4096).describe(description);
+const format = z.enum(["tar.gz", "tar", "zip"]);
+const ArchiveCreateInputSchema = z.object({
+    output: path("The archive to make"),
+    source: path("A folder: the archive gets its content").optional(),
+    files: z.array(z.string().min(1).max(4096)).min(1).max(10_000).optional().describe("Files and folders, relative to cwd. A folder goes in with its content"),
+    cwd: path("The base folder of files (default: the working folder)").optional(),
+    format: format.optional().describe("The format (default: from the name of output: .tar.gz, .tgz, .tar or .zip)"),
+    overwrite: z.boolean().optional().describe("True: replace an existing archive (default false)"),
+});
+const ArchiveCreateOutputSchema = z.object({
+    path: z.string().describe("The absolute path of the archive"),
+    format,
+    entries: z.number().int().describe("The number of entries: files, folders and links"),
+    bytes: z.number().int().describe("The size of the archive, in bytes"),
+});
+const ArchiveExtractInputSchema = z.object({
+    archive: path("The archive"),
+    target: path("The folder that gets the content. The procedure makes it"),
+    format: format.optional().describe("The format (default: from the first bytes of the archive)"),
+    overwrite: z.boolean().optional().describe("True: replace an existing file (default false: an existing file is an error, and nothing changes)"),
+});
+const ArchiveExtractOutputSchema = z.object({
+    target: z.string().describe("The absolute path of the target folder"),
+    format,
+    files: z.number().int(),
+    directories: z.number().int(),
+    links: z.number().int().describe("The symbolic links and the hard links"),
+    bytes: z.number().int().describe("The bytes of the files"),
+});
+const ArchiveListInputSchema = z.object({
+    archive: path("The archive"),
+    format: format.optional().describe("The format (default: from the first bytes of the archive)"),
+});
+const ArchiveListOutputSchema = z.object({
+    format,
+    entries: z.array(z.object({
+        path: z.string().describe("The path in the archive"),
+        kind: z.enum(["file", "directory", "symlink", "hardlink", "other"]),
+        size: z.number().int(),
+        mode: z.number().int().optional(),
+        mtime: z.string().optional().describe("The time of the last change, as an ISO text"),
+        linkTarget: z.string().optional().describe("The target of a link"),
+    })),
+    bytes: z.number().int().describe("The sum of the sizes of the files"),
+});
+// =============================================================================
+// Procedures
+// =============================================================================
+/** The effects of `create` and `extract`: they read and write files, and `overwrite` replaces a file. */
+const READS_WRITES_FS = Object.freeze({ reads: Object.freeze(["fs"]), writes: Object.freeze(["fs"]) });
+/** The effects of `list`: it reads a file and changes nothing. */
+const READS_FS = Object.freeze({ reads: Object.freeze(["fs"]), writes: Object.freeze([]) });
+/** The three procedures, with handlers that use the limits. */
+function archiveProcedures(settings) {
+    const archiveCreateProcedure = createProcedure()
+        .path(["archive", "create"])
+        .input(zodAdapter(ArchiveCreateInputSchema))
+        .output(zodAdapter(ArchiveCreateOutputSchema))
+        .meta({
+        description: "Make a tar.gz or zip archive of a folder or of files",
+        tags: ["archive", "fs"],
+        args: ["output"],
+        shorts: { source: "s", format: "f" },
+        output: "json",
+        effects: READS_WRITES_FS,
+    })
+        .handler(async (input) => archiveCreate(input, settings))
+        .build();
+    const archiveExtractProcedure = createProcedure()
+        .path(["archive", "extract"])
+        .input(zodAdapter(ArchiveExtractInputSchema))
+        .output(zodAdapter(ArchiveExtractOutputSchema))
+        .meta({
+        description: "Extract a tar.gz or zip archive into a folder, with a check of each path",
+        tags: ["archive", "fs"],
+        args: ["archive", "target"],
+        shorts: { format: "f" },
+        output: "json",
+        effects: READS_WRITES_FS,
+    })
+        .handler(async (input) => archiveExtract(input, settings))
+        .build();
+    const archiveListProcedure = createProcedure()
+        .path(["archive", "list"])
+        .input(zodAdapter(ArchiveListInputSchema))
+        .output(zodAdapter(ArchiveListOutputSchema))
+        .meta({
+        description: "The entries of a tar.gz or zip archive",
+        tags: ["archive", "fs"],
+        args: ["archive"],
+        shorts: { format: "f" },
+        output: "json",
+        effects: READS_FS,
+    })
+        .handler(async (input) => archiveList(input, settings))
+        .build();
+    return [archiveCreateProcedure, archiveExtractProcedure, archiveListProcedure];
+}
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data, with the default
+ * limits. Importing this file registers nothing.
+ */
+export const archiveModule = defineModule("@procedures/archive", archiveProcedures(DEFAULT_ARCHIVE_SETTINGS));
+export default archiveModule;
+/**
+ * This function gives the module of this package with other limits. Without options, it gives
+ * `archiveModule`. A host gives it to `createRegistry()` before its bundles, so it replaces the
+ * `archiveModule` that a bundle requires (the first module of a name counts).
+ */
+export function createArchiveModule(options = {}) {
+    if (Object.values(options).every((value) => value === undefined))
+        return archiveModule;
+    const settings = {
+        maxBytes: options.maxBytes ?? DEFAULT_ARCHIVE_SETTINGS.maxBytes,
+        maxEntries: options.maxEntries ?? DEFAULT_ARCHIVE_SETTINGS.maxEntries,
+    };
+    for (const [name, value] of Object.entries(settings)) {
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new TypeError(`createArchiveModule: ${name} must be a whole number of 0 or more`);
+    }
+    return defineModule("@procedures/archive", archiveProcedures(settings));
+}
+/**
+ * This function registers the procedures of @procedures/archive in a registry. The default is the
+ * global registry. The options are the options of `createArchiveModule()`.
+ */
+export function registerArchiveProcedures(registry = PROCEDURE_REGISTRY, options = {}) {
+    registerModules(registry, [createArchiveModule(options)]);
+}
+//# sourceMappingURL=module.js.map

package/dist/module.js.map

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

package/dist/paths.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The check of the entries of an archive before an extract ("zip slip", roadmap R46).
+ *
+ * `planExtract()` examines all the entries before the extract writes a file. A hostile archive
+ * thus changes nothing. The rules:
+ *
+ * 1. A path must be relative and must not have `..`. A drive letter, a UNC path, a NUL character
+ *    and (on Windows) a colon are refused too. A backslash counts as a separator.
+ * 2. An entry must not go through a symbolic link of the archive: a link `a` and a file `a/b`.
+ * 3. A symbolic link must stay in the target. Its target is relative, and the resolution through
+ *    the other links of the archive stays in the target folder. The check knows all the links of
+ *    the archive first, so the order of the entries does not matter.
+ * 4. A path of a link appears only one time in the archive.
+ * 5. A hard link names a file that came before it in the archive.
+ * 6. A folder of the target that the extract goes through must not be a symbolic link.
+ * 7. Without `overwrite`, an existing file at the path of an entry is an error.
+ *
+ * Rules 2 and 3 compare the paths two times: with the case, and without the case. A file system
+ * that ignores the case (Windows, macOS) then gets the same protection as one that does not.
+ */
+import type { ArchiveEntryKind } from "./types.js";
+/** One entry of an archive, before the check. */
+export interface RawEntry {
+    /** The name in the archive. */
+    readonly name: string;
+    readonly kind: ArchiveEntryKind;
+    readonly size: number;
+    /** The target of a symbolic link, or the archive path of the file of a hard link. */
+    readonly linkTarget?: string | undefined;
+    /** The place of the entry in the archive. */
+    readonly index?: number | undefined;
+}
+/** One entry after the check. */
+export interface PlannedEntry extends RawEntry {
+    /** The parts of the path: no empty part, no `.` and no `..`. */
+    readonly parts: readonly string[];
+    /** The parts joined with `/`. */
+    readonly path: string;
+}
+/** The options of `planExtract()`. */
+export interface PlanOptions {
+    readonly overwrite: boolean;
+    readonly maxBytes: number;
+    readonly maxEntries: number;
+}
+/** True for a path that starts at a root: `/x`, `\x`, `C:x`, `C:\x` or `\\server\share`. */
+export declare function isAbsoluteName(name: string): boolean;
+/**
+ * This function gives the parts of the path of an entry. It throws `UNSAFE_PATH` for an absolute
+ * path, a `..`, a NUL character, and on Windows a colon (an alternate data stream).
+ */
+export declare function entryParts(name: string, code?: "UNSAFE_PATH" | "UNSAFE_LINK"): string[];
+/**
+ * This function examines the entries of an archive for an extract into `target` (a real path),
+ * and gives them with their parts. It throws the first problem. It writes nothing.
+ */
+export declare function planExtract(entries: readonly RawEntry[], target: string, options: PlanOptions): PlannedEntry[];
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,iDAAiD;AACjD,MAAM,WAAW,QAAQ;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,iCAAiC;AACjC,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAOD,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,aAAa,GAAG,aAA6B,GAAG,MAAM,EAAE,CAStG;AA2DD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,YAAY,EAAE,CA0F9G"}