@poe-platform/safe-fs 0.1.0

package/dist/safe-fs/config.d.ts

@@ -0,0 +1,15 @@
+import type { FileSystem, FileSystemFactory } from "./contracts/filesystem.js";
+export type FileSystemConfig = {
+    readonly type: string;
+    readonly options?: Readonly<Record<string, unknown>>;
+};
+export type FileSystemAdapterDescriptor = {
+    readonly validateOptions: (options: Readonly<Record<string, unknown>>) => void;
+    readonly create: FileSystemFactory;
+};
+export type FileSystemAdapterRegistry = ReadonlyMap<string, FileSystemAdapterDescriptor>;
+export declare function readConfigRecord(value: unknown, label: string, keys?: readonly string[]): Readonly<Record<string, unknown>>;
+export declare function validateFileSystemConfig(value: unknown): FileSystemConfig;
+export declare function createFileSystem(config: FileSystemConfig, options: {
+    registry: FileSystemAdapterRegistry;
+}): Promise<FileSystem>;

package/dist/safe-fs/config.js

@@ -0,0 +1,46 @@
+export function readConfigRecord(value, label, keys) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError(`${label} must be a record.`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError(`${label} must be a plain record.`);
+    }
+    const record = Object.create(null);
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string" || (keys !== undefined && !keys.includes(key))) {
+            throw new TypeError(`Unknown ${label}: ${String(key)}`);
+        }
+        const property = Object.getOwnPropertyDescriptor(value, key);
+        if (!("value" in property))
+            throw new TypeError(`${label}.${key} must be a data property.`);
+        record[key] = property.value;
+    }
+    return Object.freeze(record);
+}
+export function validateFileSystemConfig(value) {
+    const config = readConfigRecord(value, "filesystem config", ["type", "options"]);
+    if (typeof config.type !== "string" || config.type.trim().length === 0) {
+        throw new TypeError("Filesystem adapter type must be a nonempty string.");
+    }
+    return {
+        type: config.type,
+        ...(config.options === undefined
+            ? {}
+            : { options: readConfigRecord(config.options, "filesystem options") })
+    };
+}
+export async function createFileSystem(config, options) {
+    const validated = validateFileSystemConfig(config);
+    const creation = readConfigRecord(options, "filesystem creation option", ["registry"]);
+    const registry = creation.registry;
+    if (registry === undefined || registry === null || typeof registry.get !== "function") {
+        throw new TypeError("registry must be a filesystem adapter map.");
+    }
+    const descriptor = registry.get(validated.type);
+    if (descriptor === undefined)
+        throw new TypeError(`Unknown filesystem adapter: ${validated.type}`);
+    const adapterOptions = validated.options ?? Object.freeze(Object.create(null));
+    descriptor.validateOptions(adapterOptions);
+    return await descriptor.create(adapterOptions);
+}

package/dist/safe-fs/config.node.d.ts

@@ -0,0 +1,2 @@
+import type { FileSystemAdapterRegistry } from "./config.js";
+export declare function createNodeFileSystemAdapterRegistry(extensions?: FileSystemAdapterRegistry): FileSystemAdapterRegistry;

package/dist/safe-fs/config.node.js

@@ -0,0 +1,22 @@
+import { createMemoryFileSystemAdapter } from "./config/memory.js";
+import { createRealFileSystemAdapter } from "./config/real.js";
+import { createMemoryFileSystem } from "./fs/memory/index.js";
+import { createRealFileSystem } from "./fs/real/index.js";
+export function createNodeFileSystemAdapterRegistry(extensions) {
+    if (extensions !== undefined &&
+        (extensions === null ||
+            typeof extensions.get !== "function" ||
+            typeof extensions[Symbol.iterator] !== "function")) {
+        throw new TypeError("registry must be a filesystem adapter map.");
+    }
+    const registry = new Map([
+        ["memory", createMemoryFileSystemAdapter(createMemoryFileSystem)],
+        ["real", createRealFileSystemAdapter(createRealFileSystem)]
+    ]);
+    for (const [name, descriptor] of extensions ?? []) {
+        if (registry.has(name))
+            throw new TypeError(`Filesystem adapter already registered: ${name}`);
+        registry.set(name, descriptor);
+    }
+    return registry;
+}

package/dist/safe-fs/contracts/abort.d.ts

@@ -0,0 +1,5 @@
+export interface AbortSignalScope {
+    readonly signal: AbortSignal;
+    dispose(): void;
+}
+export declare function composeAbortSignals(signals: readonly AbortSignal[]): AbortSignalScope;

package/dist/safe-fs/contracts/abort.js

@@ -0,0 +1,34 @@
+export function composeAbortSignals(signals) {
+    const controller = new AbortController();
+    const listeners = new Map();
+    const dispose = () => {
+        for (const [signal, listener] of listeners)
+            signal.removeEventListener("abort", listener);
+        listeners.clear();
+    };
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            return { signal: controller.signal, dispose };
+        }
+    }
+    try {
+        for (const signal of new Set(signals)) {
+            const listener = () => {
+                dispose();
+                controller.abort(signal.reason);
+            };
+            listeners.set(signal, listener);
+            signal.addEventListener("abort", listener, { once: true });
+            if (signal.aborted)
+                listener();
+            if (controller.signal.aborted)
+                break;
+        }
+    }
+    catch (error) {
+        dispose();
+        throw error;
+    }
+    return { signal: controller.signal, dispose };
+}

package/dist/safe-fs/contracts/cleanup.d.ts

@@ -0,0 +1 @@
+export declare function finishCleanup(cleanup: () => unknown, failed: boolean): Promise<void>;

package/dist/safe-fs/contracts/cleanup.js

@@ -0,0 +1,9 @@
+export async function finishCleanup(cleanup, failed) {
+    try {
+        await cleanup();
+    }
+    catch (error) {
+        if (!failed)
+            throw error;
+    }
+}

package/dist/safe-fs/contracts/errors.d.ts

@@ -0,0 +1,50 @@
+import type { PlatformErrno } from "#safe-fs-platform";
+export type { PlatformErrno } from "#safe-fs-platform";
+declare const descriptions: {
+    readonly EACCES: "permission denied";
+    readonly EAGAIN: "resource temporarily unavailable";
+    readonly EBADF: "bad file descriptor";
+    readonly EBUSY: "resource busy or locked";
+    readonly ECANCELED: "operation canceled";
+    readonly EEXIST: "file already exists";
+    readonly EFBIG: "file too large";
+    readonly EINTR: "interrupted system call";
+    readonly EINVAL: "invalid argument";
+    readonly EIO: "input/output error";
+    readonly EISDIR: "illegal operation on a directory";
+    readonly ELOOP: "too many symbolic links encountered";
+    readonly EMFILE: "too many open files";
+    readonly ENAMETOOLONG: "name too long";
+    readonly ENFILE: "file table overflow";
+    readonly ENOENT: "no such file or directory";
+    readonly ENOMEM: "not enough memory";
+    readonly ENOSPC: "no space left on device";
+    readonly ENOSYS: "function not implemented";
+    readonly ENOTDIR: "not a directory";
+    readonly ENOTEMPTY: "directory not empty";
+    readonly ENOTSUP: "operation not supported";
+    readonly EOPNOTSUPP: "operation not supported";
+    readonly EPERM: "operation not permitted";
+    readonly EPIPE: "broken pipe";
+    readonly EROFS: "read-only file system";
+    readonly ETIMEDOUT: "operation timed out";
+    readonly EXDEV: "cross-device link not permitted";
+};
+export type ErrnoCode = keyof typeof descriptions;
+export interface FsErrorOptions extends ErrorOptions {
+    readonly syscall?: string;
+    readonly path?: string;
+    readonly dest?: string;
+    readonly message?: string;
+}
+export declare class FsError extends Error {
+    readonly code: ErrnoCode;
+    readonly errno: PlatformErrno;
+    readonly syscall?: string;
+    readonly path?: string;
+    readonly dest?: string;
+    constructor(code: ErrnoCode, options?: FsErrorOptions);
+}
+export declare function isErrnoCode(code: unknown): code is ErrnoCode;
+export declare function isFsError(error: unknown, code?: ErrnoCode): error is FsError;
+export declare function toFsError(error: unknown, options?: FsErrorOptions): FsError;

package/dist/safe-fs/contracts/errors.js

@@ -0,0 +1,77 @@
+import { platform } from "#safe-fs-platform";
+const descriptions = {
+    EACCES: "permission denied",
+    EAGAIN: "resource temporarily unavailable",
+    EBADF: "bad file descriptor",
+    EBUSY: "resource busy or locked",
+    ECANCELED: "operation canceled",
+    EEXIST: "file already exists",
+    EFBIG: "file too large",
+    EINTR: "interrupted system call",
+    EINVAL: "invalid argument",
+    EIO: "input/output error",
+    EISDIR: "illegal operation on a directory",
+    ELOOP: "too many symbolic links encountered",
+    EMFILE: "too many open files",
+    ENAMETOOLONG: "name too long",
+    ENFILE: "file table overflow",
+    ENOENT: "no such file or directory",
+    ENOMEM: "not enough memory",
+    ENOSPC: "no space left on device",
+    ENOSYS: "function not implemented",
+    ENOTDIR: "not a directory",
+    ENOTEMPTY: "directory not empty",
+    ENOTSUP: "operation not supported",
+    EOPNOTSUPP: "operation not supported",
+    EPERM: "operation not permitted",
+    EPIPE: "broken pipe",
+    EROFS: "read-only file system",
+    ETIMEDOUT: "operation timed out",
+    EXDEV: "cross-device link not permitted",
+};
+export class FsError extends Error {
+    code;
+    errno;
+    syscall;
+    path;
+    dest;
+    constructor(code, options = {}) {
+        if (!isErrnoCode(code))
+            throw new TypeError(`Unsupported errno code: ${String(code)}`);
+        const errno = platform.errno(code);
+        const operation = options.syscall ? `, ${options.syscall}` : "";
+        const path = options.path === undefined ? "" : ` '${options.path}'`;
+        const destination = options.dest === undefined ? "" : ` -> '${options.dest}'`;
+        super(`${code}: ${options.message ?? descriptions[code]}${operation}${path}${destination}`, options);
+        this.name = "FsError";
+        this.code = code;
+        this.errno = errno;
+        if (options.syscall !== undefined)
+            this.syscall = options.syscall;
+        if (options.path !== undefined)
+            this.path = options.path;
+        if (options.dest !== undefined)
+            this.dest = options.dest;
+    }
+}
+export function isErrnoCode(code) {
+    return typeof code === "string" && Object.hasOwn(descriptions, code);
+}
+export function isFsError(error, code) {
+    return error instanceof FsError && (code === undefined || error.code === code);
+}
+export function toFsError(error, options = {}) {
+    if (error instanceof FsError && Object.keys(options).length === 0)
+        return error;
+    const source = typeof error === "object" && error !== null
+        ? error
+        : {};
+    const details = {
+        ...(typeof source.syscall === "string" ? { syscall: source.syscall } : {}),
+        ...(typeof source.path === "string" ? { path: source.path } : {}),
+        ...(typeof source.dest === "string" ? { dest: source.dest } : {}),
+        cause: error,
+        ...options,
+    };
+    return new FsError(isErrnoCode(source.code) ? source.code : "EIO", details);
+}

package/dist/safe-fs/contracts/filesystem.d.ts

@@ -0,0 +1,96 @@
+import type { ByteSource } from "./io.js";
+export type FileType = "file" | "directory" | "symlink";
+export type EntryComparison = "same" | "distinct" | "unknown";
+export interface FileStat {
+    readonly type: FileType;
+    readonly size: number;
+    readonly allocatedBytes?: number;
+    readonly mode: number;
+    readonly mtimeMs: number;
+    readonly atimeMs: number;
+    readonly ctimeMs: number;
+    readonly birthtimeMs?: number;
+    readonly identityScope?: object | symbol;
+    readonly ino?: number;
+    readonly dev?: number;
+    readonly nlink?: number;
+    readonly uid?: number;
+    readonly gid?: number;
+}
+export interface DirectoryEntry {
+    readonly name: string;
+    readonly type: FileType;
+}
+export interface FileSystemCapabilities {
+    readonly readOnly?: boolean;
+    readonly symlinks?: boolean;
+    readonly hardlinks?: boolean;
+    readonly permissions?: boolean;
+    readonly timestamps?: boolean;
+    readonly atomicRename?: boolean;
+    readonly snapshotRmdir?: boolean;
+    readonly streamingRead?: boolean;
+    readonly streamingWrite?: boolean;
+    readonly [capability: string]: boolean | undefined;
+}
+export interface FsOptions {
+    readonly signal?: AbortSignal;
+}
+export interface ReadFileOptions extends FsOptions {
+    readonly maxBytes?: number;
+}
+export interface WriteFileOptions extends FsOptions {
+    readonly flag?: "w" | "wx" | "a" | "ax";
+    readonly mode?: number;
+}
+export interface AppendFileOptions extends FsOptions {
+    readonly mode?: number;
+}
+export interface MkdirOptions extends FsOptions {
+    readonly recursive?: boolean;
+    readonly mode?: number;
+}
+export interface RemoveOptions extends FsOptions {
+    readonly recursive?: boolean;
+    readonly force?: boolean;
+}
+export interface CopyFileOptions extends FsOptions {
+    readonly exclusive?: boolean;
+}
+export interface ReadStreamOptions extends FsOptions {
+    readonly start?: number;
+    readonly endExclusive?: number;
+    readonly chunkSize?: number;
+}
+export interface FileSystem {
+    readonly capabilities: FileSystemCapabilities;
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+    appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
+    stat(path: string, options?: FsOptions): Promise<FileStat>;
+    lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    compareEntry?(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
+    readdir(path: string, options?: FsOptions): Promise<DirectoryEntry[]>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rm(path: string, options?: RemoveOptions): Promise<void>;
+    rmdir?(path: string, options?: FsOptions): Promise<void>;
+    rename(source: string, destination: string, options?: FsOptions): Promise<void>;
+    copyFile(source: string, destination: string, options?: CopyFileOptions): Promise<void>;
+    realpath(path: string, options?: FsOptions): Promise<string>;
+    access(path: string, mode?: number, options?: FsOptions): Promise<void>;
+    readlink?(path: string, options?: FsOptions): Promise<string>;
+    symlink?(target: string, path: string, options?: FsOptions): Promise<void>;
+    link?(existingPath: string, newPath: string, options?: FsOptions): Promise<void>;
+    chmod?(path: string, mode: number, options?: FsOptions): Promise<void>;
+    utimes?(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
+    truncate?(path: string, length?: number, options?: FsOptions): Promise<void>;
+    readStream?(path: string, options?: ReadStreamOptions): ByteSource;
+    writeStream?(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+}
+export type FileSystemFactory = (options: Readonly<Record<string, unknown>>) => FileSystem | Promise<FileSystem>;
+export declare const ACCESS_MODES: Readonly<{
+    F_OK: 0;
+    R_OK: 4;
+    W_OK: 2;
+    X_OK: 1;
+}>;

package/dist/safe-fs/contracts/filesystem.js

@@ -0,0 +1 @@
+export const ACCESS_MODES = Object.freeze({ F_OK: 0, R_OK: 4, W_OK: 2, X_OK: 1 });

package/dist/safe-fs/contracts/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./errors.js";
+export * from "./filesystem.js";
+export * from "./io.js";
+export * from "./path.js";

package/dist/safe-fs/contracts/index.js

@@ -0,0 +1,4 @@
+export * from "./errors.js";
+export * from "./filesystem.js";
+export * from "./io.js";
+export * from "./path.js";

package/dist/safe-fs/contracts/io.d.ts

@@ -0,0 +1,8 @@
+export type ByteSource = AsyncIterable<Uint8Array>;
+export interface CollectOptions {
+    readonly maxBytes: number;
+    readonly signal?: AbortSignal;
+}
+export declare function toByteSource(input: string | Uint8Array): ByteSource;
+export declare function collectBytes(source: ByteSource, options: CollectOptions): Promise<Uint8Array>;
+export declare function readBytes(source: ByteSource, signal?: AbortSignal): AsyncGenerator<Uint8Array>;

package/dist/safe-fs/contracts/io.js

@@ -0,0 +1,92 @@
+import { FsError } from "./errors.js";
+import { finishCleanup } from "./cleanup.js";
+export function toByteSource(input) {
+    if (typeof input !== "string" && !(input instanceof Uint8Array)) {
+        throw new TypeError("Byte source input must be a string or Uint8Array");
+    }
+    const bytes = typeof input === "string" ? new TextEncoder().encode(input) : new Uint8Array(input);
+    return (async function* () {
+        if (bytes.byteLength > 0)
+            yield bytes;
+    })();
+}
+export async function collectBytes(source, options) {
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0) {
+        throw new RangeError("maxBytes must be a nonnegative safe integer");
+    }
+    const chunks = [];
+    let size = 0;
+    options.signal?.throwIfAborted();
+    for await (const chunk of readBytes(source, options.signal)) {
+        if (chunk.byteLength > options.maxBytes - size) {
+            throw new FsError("EFBIG", { syscall: "collectBytes", message: "output exceeds maxBytes" });
+        }
+        if (chunk.byteLength > 0)
+            chunks.push(new Uint8Array(chunk));
+        size += chunk.byteLength;
+    }
+    options.signal?.throwIfAborted();
+    const result = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+}
+async function abortable(operation, signal) {
+    signal?.throwIfAborted();
+    if (!signal)
+        return operation();
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            signal.removeEventListener("abort", onAbort);
+            reject(signal.reason);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            Promise.resolve(operation()).then((result) => {
+                signal.removeEventListener("abort", onAbort);
+                resolve(result);
+            }, (error) => {
+                signal.removeEventListener("abort", onAbort);
+                reject(error);
+            });
+        }
+        catch (error) {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        }
+    });
+}
+export async function* readBytes(source, signal) {
+    signal?.throwIfAborted();
+    const iterator = source[Symbol.asyncIterator]();
+    let finished = false;
+    let failed = false;
+    try {
+        while (true) {
+            const result = await abortable(() => iterator.next(), signal);
+            if (result.done) {
+                finished = true;
+                return;
+            }
+            if (!(result.value instanceof Uint8Array))
+                throw new TypeError("Byte sources must yield Uint8Array chunks");
+            yield result.value;
+        }
+    }
+    catch (error) {
+        failed = true;
+        throw error;
+    }
+    finally {
+        if (!finished && iterator.return) {
+            const cleanup = Promise.resolve().then(() => iterator.return());
+            if (signal?.aborted)
+                void cleanup.catch(() => { });
+            else
+                await finishCleanup(() => abortable(() => cleanup, signal), failed);
+        }
+    }
+}

package/dist/safe-fs/contracts/path.d.ts

@@ -0,0 +1,8 @@
+import { posix } from "node:path";
+export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./virtual-path.js";
+export declare const posixPath: typeof posix;
+export declare const basename: typeof posix.basename;
+export declare const dirname: typeof posix.dirname;
+export declare const extname: typeof posix.extname;
+export declare const joinPath: typeof posix.join;
+export declare const isAbsolutePath: typeof posix.isAbsolute;

package/dist/safe-fs/contracts/path.js

@@ -0,0 +1,8 @@
+import { posix } from "node:path";
+export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./virtual-path.js";
+export const posixPath = posix;
+export const basename = posix.basename;
+export const dirname = posix.dirname;
+export const extname = posix.extname;
+export const joinPath = posix.join;
+export const isAbsolutePath = posix.isAbsolute;

package/dist/safe-fs/contracts/portable-path.d.ts

@@ -0,0 +1,13 @@
+import { dirname as virtualDirname } from "./virtual-path.js";
+export declare function basename(path: string, suffix?: string): string;
+export declare const dirname: typeof virtualDirname;
+export declare function extname(path: string): string;
+export declare function isAbsolutePath(path: string): boolean;
+export declare function joinPath(...paths: string[]): string;
+export declare const posixPath: Readonly<{
+    basename: typeof basename;
+    dirname: typeof virtualDirname;
+    extname: typeof extname;
+    join: typeof joinPath;
+    isAbsolute: typeof isAbsolutePath;
+}>;

package/dist/safe-fs/contracts/portable-path.js

@@ -0,0 +1,57 @@
+import { dirname as virtualDirname } from "./virtual-path.js";
+function assertString(value) {
+    if (typeof value !== "string")
+        throw new TypeError("path must be a string");
+}
+export function basename(path, suffix = "") {
+    assertString(path);
+    assertString(suffix);
+    if (suffix && path === suffix)
+        return "";
+    let end = path.length;
+    while (end > 0 && path[end - 1] === "/")
+        end--;
+    if (end === 0 && suffix && suffix.length <= path.length)
+        return path;
+    const start = path.lastIndexOf("/", end - 1) + 1;
+    const base = path.slice(start, end);
+    if (suffix.length > base.length && suffix.length <= path.length && suffix.endsWith(base))
+        return path.slice(start);
+    return suffix && suffix.length < base.length && base.endsWith(suffix)
+        ? base.slice(0, -suffix.length)
+        : base;
+}
+export const dirname = virtualDirname;
+export function extname(path) {
+    const base = basename(path);
+    const position = base.lastIndexOf(".");
+    return position <= 0 || base === ".." ? "" : base.slice(position);
+}
+export function isAbsolutePath(path) {
+    assertString(path);
+    return path.startsWith("/");
+}
+export function joinPath(...paths) {
+    for (const path of paths)
+        assertString(path);
+    const joined = paths.filter(Boolean).join("/");
+    if (!joined)
+        return ".";
+    const absolute = joined.startsWith("/");
+    const components = [];
+    for (const component of joined.split("/")) {
+        if (!component || component === ".")
+            continue;
+        if (component === "..") {
+            if (components.length && components.at(-1) !== "..")
+                components.pop();
+            else if (!absolute)
+                components.push(component);
+        }
+        else
+            components.push(component);
+    }
+    const result = `${absolute ? "/" : ""}${components.join("/")}` || ".";
+    return joined.endsWith("/") && result !== "/" ? `${result}/` : result;
+}
+export const posixPath = Object.freeze({ basename, dirname, extname, join: joinPath, isAbsolute: isAbsolutePath });

package/dist/safe-fs/contracts/virtual-path.d.ts

@@ -0,0 +1,7 @@
+export declare function validatePath(path: string): void;
+export declare function resolvePath(cwd: string, ...paths: string[]): string;
+export declare function normalizePath(path: string, cwd?: string): string;
+export declare function dirname(path: string): string;
+export declare function relativePath(from: string, to: string): string;
+export declare function isPathWithin(root: string, path: string): boolean;
+export declare function assertPathWithin(root: string, path: string): string;

package/dist/safe-fs/contracts/virtual-path.js

@@ -0,0 +1,66 @@
+import { FsError } from "./errors.js";
+export function validatePath(path) {
+    if (typeof path !== "string" || path.includes("\0")) {
+        throw new FsError("EINVAL", { syscall: "resolve", message: "paths must be strings without NUL bytes" });
+    }
+}
+export function resolvePath(cwd, ...paths) {
+    validatePath(cwd);
+    if (!cwd.startsWith("/"))
+        throw new FsError("EINVAL", { syscall: "resolve", path: cwd, message: "cwd must be absolute" });
+    for (const path of paths)
+        validatePath(path);
+    const components = [];
+    for (const path of [cwd, ...paths]) {
+        if (path.startsWith("/"))
+            components.length = 0;
+        for (const component of path.split("/")) {
+            if (component === "" || component === ".")
+                continue;
+            if (component === "..")
+                components.pop();
+            else
+                components.push(component);
+        }
+    }
+    return `/${components.join("/")}`;
+}
+export function normalizePath(path, cwd = "/") {
+    return resolvePath(cwd, path);
+}
+export function dirname(path) {
+    if (typeof path !== "string")
+        throw new TypeError("path must be a string");
+    let end = path.length;
+    while (end > 0 && path[end - 1] === "/")
+        end--;
+    if (end === 0)
+        return path.startsWith("/") ? "/" : ".";
+    const boundary = path.lastIndexOf("/", end - 1);
+    if (boundary < 0)
+        return ".";
+    if (boundary === 0)
+        return "/";
+    if (boundary === 1 && path.startsWith("/"))
+        return "//";
+    return path.slice(0, boundary);
+}
+export function relativePath(from, to) {
+    const source = normalizePath(from).split("/").filter(Boolean);
+    const target = normalizePath(to).split("/").filter(Boolean);
+    let common = 0;
+    while (common < source.length && common < target.length && source[common] === target[common])
+        common++;
+    return [...Array(source.length - common).fill(".."), ...target.slice(common)].join("/");
+}
+export function isPathWithin(root, path) {
+    const normalizedRoot = normalizePath(root);
+    const normalizedPath = normalizePath(path);
+    return normalizedRoot === "/" || normalizedPath === normalizedRoot || normalizedPath.startsWith(`${normalizedRoot}/`);
+}
+export function assertPathWithin(root, path) {
+    const normalizedPath = normalizePath(path);
+    if (!isPathWithin(root, normalizedPath))
+        throw new FsError("EACCES", { syscall: "resolve", path, message: "path escapes the allowed root" });
+    return normalizedPath;
+}