@poe-platform/safe-js 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.node.d.ts

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

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/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/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/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/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/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/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/core.d.ts

@@ -0,0 +1,12 @@
+export * from "./contracts/errors.js";
+export * from "./contracts/filesystem.js";
+export * from "./contracts/io.js";
+export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./contracts/virtual-path.js";
+export { basename, dirname, extname, isAbsolutePath, joinPath, posixPath } from "./contracts/portable-path.js";
+export * from "./fs/memory/index.js";
+export * from "./fs/readonly/index.js";
+export * from "./fs/mount/index.js";
+export * from "./fs/overlay/index.js";
+export * from "./fs/webdav/index.js";
+export * from "./bridge/index.js";
+export { compareEntries } from "./fs/mount/comparison.js";

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

@@ -0,0 +1,58 @@
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileStat, FileSystem, FsOptions, MkdirOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { ByteSource } from "../../contracts/io.js";
+export declare class MemoryFileSystem implements FileSystem {
+    readonly capabilities: Readonly<{
+        readOnly: false;
+        symlinks: true;
+        hardlinks: true;
+        permissions: true;
+        timestamps: true;
+        atomicRename: true;
+        streamingRead: true;
+        streamingWrite: true;
+    }>;
+    private readonly identityScope;
+    private nextInode;
+    private readonly root;
+    constructor();
+    compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
+    private metadata;
+    private directory;
+    private fail;
+    private validatePath;
+    private permission;
+    private mode;
+    private integer;
+    private changed;
+    private resolve;
+    private file;
+    private entry;
+    private terminalDot;
+    private snapshot;
+    private bytes;
+    private allocate;
+    private openWrite;
+    private append;
+    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>;
+    readdir(path: string, options?: FsOptions): Promise<DirectoryEntry[]>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rmdir(path: string, options?: FsOptions): Promise<void>;
+    rm(path: string, options?: RemoveOptions): 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 declare function createMemoryFileSystem(): MemoryFileSystem;

package/dist/safe-fs/fs/mount/comparison.d.ts

@@ -0,0 +1,19 @@
+import type { EntryComparison, FileStat, FileSystem, FsOptions } from "../../contracts/filesystem.js";
+export interface EntryLocation {
+    readonly filesystem: FileSystem;
+    readonly path: string;
+    readonly readOnly?: boolean;
+    readonly stat?: FileStat;
+}
+export interface EntryView extends EntryLocation {
+    readonly stat: FileStat;
+    readonly readOnly: boolean;
+}
+export type EntryViewResolver = (path: string, options: FsOptions) => Promise<EntryLocation>;
+export type EntryAuthority = (own: EntryView, peer: EntryView, options: FsOptions) => Promise<EntryComparison>;
+export declare function assertCallbackAuthorityAllowed(): void;
+export declare function registerEntryView(filesystem: FileSystem, resolver: EntryViewResolver): void;
+export declare function registerEntryAuthority(filesystem: FileSystem, authority: EntryAuthority): void;
+export declare function resolveEntryView(filesystem: FileSystem, path: string, options?: FsOptions): Promise<EntryView>;
+export declare function compareResolvedEntries(own: EntryView, peer: EntryView, options?: FsOptions): Promise<EntryComparison>;
+export declare function compareEntries(filesystem: FileSystem, path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;

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

@@ -0,0 +1,44 @@
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { ByteSource } from "../../contracts/io.js";
+export interface MountFileSystemOptions {
+    readonly root: FileSystem;
+    readonly mounts?: Readonly<Record<string, FileSystem>>;
+}
+export declare class MountFileSystem implements FileSystem {
+    readonly capabilities: FileSystemCapabilities;
+    private readonly mounts;
+    constructor(options: MountFileSystemOptions);
+    private select;
+    private protected;
+    private error;
+    private operation;
+    private components;
+    private lookup;
+    private resolve;
+    private mutable;
+    private entryPath;
+    private optional;
+    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>;
+    readdir(path: string, options?: FsOptions): Promise<DirectoryEntry[]>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rmdir(path: string, options?: FsOptions): Promise<void>;
+    rm(path: string, options?: RemoveOptions): 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>;
+    compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").EntryComparison>;
+    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 declare function createMountFileSystem(options: MountFileSystemOptions): MountFileSystem;

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

@@ -0,0 +1,73 @@
+import type { ByteSource } from "../../contracts/io.js";
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+export interface OverlayFileSystemOptions {
+    readonly upper: FileSystem;
+    readonly lower: FileSystem;
+    readonly maxBufferBytes?: number;
+}
+export declare class OverlayFileSystem implements FileSystem {
+    #private;
+    readonly capabilities: FileSystemCapabilities;
+    private readonly maxBufferBytes;
+    private readonly whiteouts;
+    private readonly opaque;
+    private readonly garbage;
+    private readonly activeStages;
+    private readonly linkMetadata;
+    private readonly linkOrigins;
+    private queue;
+    constructor(options: OverlayFileSystemOptions);
+    private run;
+    private writable;
+    private permission;
+    private maybeStat;
+    private hidden;
+    private lowerVisible;
+    private lookup;
+    private resolve;
+    private linkTarget;
+    private movableLinkTarget;
+    private required;
+    private listing;
+    private bytes;
+    private cleanGarbage;
+    cleanup(options?: FsOptions): Promise<void>;
+    private staged;
+    private preserve;
+    private clone;
+    private rememberLink;
+    private ensureDirectory;
+    private copyUp;
+    private parent;
+    private makeDirectory;
+    private writeOptions;
+    private writeLocation;
+    private replace;
+    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<import("../../contracts/filesystem.js").EntryComparison>;
+    readdir(path: string, options?: FsOptions): Promise<DirectoryEntry[]>;
+    realpath(path: string, options?: FsOptions): Promise<string>;
+    access(path: string, requestedMode?: number, options?: FsOptions): Promise<void>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rmdir(path: string, options?: FsOptions): Promise<void>;
+    rm(path: string, options?: RemoveOptions): Promise<void>;
+    private materialize;
+    rename(source: string, destination: string, options?: FsOptions): Promise<void>;
+    copyFile(source: string, destination: string, options?: CopyFileOptions): 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>;
+    private metadata;
+    chmod(path: string, permissions: 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;
+    private bounded;
+    private streamToUpper;
+    writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+}
+export declare function createOverlayFileSystem(options: OverlayFileSystemOptions): OverlayFileSystem;

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

@@ -0,0 +1,31 @@
+import type { ByteSource } from "../../contracts/io.js";
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+export declare class ReadOnlyFileSystem implements FileSystem {
+    #private;
+    constructor(filesystem: FileSystem);
+    get capabilities(): FileSystemCapabilities;
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    stat(path: string, options?: FsOptions): Promise<FileStat>;
+    lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").EntryComparison>;
+    readdir(path: string, options?: FsOptions): Promise<DirectoryEntry[]>;
+    realpath(path: string, options?: FsOptions): Promise<string>;
+    access(path: string, mode?: number, options?: FsOptions): Promise<void>;
+    readlink(path: string, options?: FsOptions): Promise<string>;
+    readStream(path: string, options?: ReadStreamOptions): ByteSource;
+    writeFile(path: string, _data: Uint8Array, _options?: WriteFileOptions): Promise<void>;
+    appendFile(path: string, _data: Uint8Array, _options?: AppendFileOptions): Promise<void>;
+    writeStream(path: string, _source: ByteSource, _options?: WriteFileOptions): Promise<void>;
+    mkdir(path: string, _options?: MkdirOptions): Promise<void>;
+    rm(path: string, _options?: RemoveOptions): Promise<void>;
+    unlink(path: string, _options?: FsOptions): 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>;
+    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>;
+}
+export declare function createReadOnlyFileSystem(filesystem: FileSystem): ReadOnlyFileSystem;

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

@@ -0,0 +1,76 @@
+import type { AppendFileOptions, ByteSource, CopyFileOptions, DirectoryEntry, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/index.js";
+export interface RealFileSystemOptions {
+    /** An existing, absolute host directory. It is never created implicitly. */
+    readonly root: string;
+}
+/**
+ * Async byte filesystem for trusted POSIX hosts (Windows is unsupported).
+ * Both relative and absolute input paths are virtual POSIX paths rooted at `/`;
+ * components resolve in order, following symlinks before subsequent `..` and
+ * preserving trailing directory requirements. Empty paths are ENOENT. Excess
+ * input `..` clamps at the virtual root; symlink targets may never cross it.
+ * There is no process cwd dependency. The configured host root must already
+ * exist; its canonical location is pinned on first use or by the async factory.
+ *
+ * Absolute symlink targets created here are virtual paths, stored as rooted
+ * host targets without lexical normalization. Relative targets retain their
+ * text; safe dangling, non-directory, and looping targets may be created.
+ * Existing host symlinks are
+ * followed only when every traversed component remains beneath the root, with
+ * a 40-link traversal limit. Existing absolute host targets must start with the
+ * canonical root, not a different host alias of that root. lstat, removal, and
+ * rename inspect or modify a final symlink itself rather than its target. Absolute readlink results are
+ * translated back into virtual paths; external absolute targets are refused.
+ *
+ * SECURITY LIMIT: containment checks and subsequent Node path operations are
+ * not atomic. O_NOFOLLOW narrows final-file open races, but ancestor swaps,
+ * concurrent renames, mount changes, and preexisting hardlinks cannot be made
+ * safe by these APIs. This is NOT a race-proof sandbox or an isolation boundary
+ * against another process modifying the tree. Use an OS sandbox for that.
+ *
+ * Only regular files, directories, and symlinks are represented. Permissions,
+ * ownership, timestamp precision, case sensitivity, umask, and rename behavior
+ * are those of the host filesystem. Copy is not atomic; rename can fail EXDEV.
+ * Cancellation is cooperative between operations/chunks, not rollback: failed
+ * or canceled writes/copies may leave partial data. No native commands execute.
+ * Destructive rm/rename operands ending in `.` or `..` are refused with EINVAL,
+ * including native recursive-rm edge cases that could otherwise delete content.
+ * Public filesystem errors carry only virtual operands; native causes are
+ * intentionally omitted so host paths cannot escape through nested errors.
+ */
+export declare class RealFileSystem implements FileSystem {
+    readonly capabilities: FileSystemCapabilities;
+    private readonly configuredRoot;
+    private rootPromise;
+    constructor(options: RealFileSystemOptions | string);
+    private root;
+    private absoluteTarget;
+    private walk;
+    private path;
+    private operation;
+    private protectRoot;
+    private protectTerminal;
+    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>;
+    readdir(path: string, options?: FsOptions): Promise<DirectoryEntry[]>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rmdir(path: string, options?: FsOptions): Promise<void>;
+    rm(path: string, options?: RemoveOptions): 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>;
+}
+/** Construct and validate an existing root before returning the backend. */
+export declare function createRealFileSystem(options: RealFileSystemOptions | string): Promise<RealFileSystem>;

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

@@ -0,0 +1,93 @@
+import { FsError } from "../../contracts/errors.js";
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileStat, FileSystem, FsOptions, MkdirOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { ByteSource } from "../../contracts/io.js";
+import type { S3Transport } from "./transport.js";
+export interface S3FileSystemOptions {
+    readonly transport: S3Transport;
+    readonly bucket: string;
+    readonly prefix?: string;
+    readonly compareEntry?: (this: FileSystem, ...args: Parameters<NonNullable<FileSystem["compareEntry"]>>) => ReturnType<NonNullable<FileSystem["compareEntry"]>>;
+    readonly readOnly?: boolean;
+    readonly allowNonAtomicRename?: boolean;
+    readonly pageSize?: number;
+    readonly maxReadBytes?: number;
+    readonly maxStreamBytes?: number;
+    readonly maxListEntries?: number;
+}
+export declare class S3RenameError extends FsError {
+    readonly phase: "copy" | "delete";
+    readonly copiedKeys: readonly string[];
+    readonly deletedKeys: readonly string[];
+    constructor(source: string, destination: string, phase: "copy" | "delete", copied: string[], deleted: string[], cause: FsError);
+}
+export declare class S3FileSystem implements FileSystem {
+    readonly capabilities: Readonly<{
+        readOnly: boolean;
+        symlinks: false;
+        hardlinks: false;
+        permissions: false;
+        timestamps: boolean;
+        atomicRename: false;
+        snapshotRmdir: true;
+        streamingRead: boolean;
+        streamingWrite: boolean;
+    }>;
+    readonly readStream?: (path: string, options?: ReadStreamOptions) => ByteSource;
+    readonly writeStream?: (path: string, source: ByteSource, options?: WriteFileOptions) => Promise<void>;
+    private readonly transport;
+    private readonly bucket;
+    private readonly prefix;
+    private readonly allowRename;
+    private readonly pageSize;
+    private readonly maxReadBytes;
+    private readonly maxStreamBytes;
+    private readonly maxListEntries;
+    constructor(options: S3FileSystemOptions);
+    compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
+    private path;
+    private key;
+    private directoryKey;
+    private checkAbort;
+    private requestOptions;
+    private call;
+    private writable;
+    private unsupported;
+    private head;
+    private makeStat;
+    private page;
+    private validateKey;
+    private validateObject;
+    private pages;
+    private inspect;
+    private lookup;
+    private requireDirectorySuffix;
+    stat(input: string, options?: FsOptions): Promise<FileStat>;
+    lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    private body;
+    private get;
+    readFile(input: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    private etag;
+    writeFile(input: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+    private writeMetadata;
+    appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
+    mkdir(input: string, options?: MkdirOptions): Promise<void>;
+    readdir(input: string, options?: FsOptions): Promise<DirectoryEntry[]>;
+    private tree;
+    rmdir(input: string, options?: FsOptions): Promise<void>;
+    rm(input: string, options?: RemoveOptions): Promise<void>;
+    private copy;
+    copyFile(sourceInput: string, destinationInput: string, options?: CopyFileOptions): Promise<void>;
+    rename(sourceInput: string, destinationInput: string, options?: FsOptions): Promise<void>;
+    private copyWithPut;
+    realpath(input: string, options?: FsOptions): Promise<string>;
+    access(path: string, mode?: number, options?: FsOptions): Promise<void>;
+    readlink(path: string): Promise<string>;
+    symlink(_target: string, path: string): Promise<void>;
+    link(_existingPath: string, path: string): Promise<void>;
+    chmod(path: string, _mode: number): Promise<void>;
+    utimes(input: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
+    truncate(input: string, length?: number, options?: FsOptions): Promise<void>;
+    private streamRead;
+    private dispose;
+    private streamWrite;
+}

package/dist/safe-fs/fs/s3/http/index.d.ts

@@ -0,0 +1,2 @@
+export { createS3HttpTransport } from "./transport.js";
+export type { S3HttpCredentials, S3HttpCredentialProvider, S3HttpRequestFactory, S3HttpTransportOptions } from "./types.js";

package/dist/safe-fs/fs/s3/http/transport.d.ts

@@ -0,0 +1,3 @@
+import type { S3Transport } from "../transport.js";
+import type { S3HttpTransportOptions } from "./types.js";
+export declare function createS3HttpTransport(options: S3HttpTransportOptions): S3Transport;