@catmint-fs/core 0.0.0-prealpha.0

package/dist/index.d.ts

@@ -0,0 +1,297 @@
+interface FsAdapter {
+    readFile(path: string): Promise<Uint8Array>;
+    createReadStream(path: string): ReadableStream<Uint8Array>;
+    readdir(path: string): Promise<DirentEntry[]>;
+    stat(path: string): Promise<StatResult>;
+    lstat(path: string): Promise<StatResult>;
+    readlink(path: string): Promise<string>;
+    exists(path: string): Promise<boolean>;
+    writeFile(path: string, data: Uint8Array, options?: WriteOptions): Promise<void>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    symlink(target: string, path: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+    chown(path: string, uid: number, gid: number): Promise<void>;
+    lchown(path: string, uid: number, gid: number): Promise<void>;
+    checkPermission(path: string, op: PermissionOp): Promise<void>;
+    initialize?(root: string): Promise<void>;
+    capabilities(): AdapterCapabilities;
+}
+
+interface WriteOptions {
+    mode?: number;
+    uid?: number;
+    gid?: number;
+}
+interface MkdirOptions {
+    recursive?: boolean;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+}
+interface RmOptions {
+    recursive?: boolean;
+    force?: boolean;
+}
+type PermissionOp = "read" | "write" | "execute";
+interface DirentEntry {
+    name: string;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+interface StatResult {
+    mode: number;
+    uid: number;
+    gid: number;
+    size: number;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs: number;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+type EntryType = "file" | "directory" | "symlink";
+type ChangeEntry = {
+    type: "create";
+    entryType: "file" | "directory";
+    path: string;
+} | {
+    type: "update";
+    path: string;
+} | {
+    type: "delete";
+    entryType: EntryType;
+    path: string;
+} | {
+    type: "rename";
+    from: string;
+    to: string;
+} | {
+    type: "chmod";
+    path: string;
+    mode: number;
+} | {
+    type: "chown";
+    path: string;
+    uid: number;
+    gid: number;
+} | {
+    type: "symlink";
+    path: string;
+    target: string;
+};
+type ChangeDetail = {
+    type: "create";
+    entryType: "file";
+    path: string;
+    content: Uint8Array;
+    mode: number;
+    uid: number;
+    gid: number;
+} | {
+    type: "create";
+    entryType: "directory";
+    path: string;
+    mode: number;
+    uid: number;
+    gid: number;
+} | {
+    type: "update";
+    path: string;
+    content: Uint8Array;
+    mode: number;
+    uid: number;
+    gid: number;
+} | {
+    type: "delete";
+    entryType: EntryType;
+    path: string;
+} | {
+    type: "rename";
+    from: string;
+    to: string;
+} | {
+    type: "chmod";
+    path: string;
+    mode: number;
+} | {
+    type: "chown";
+    path: string;
+    uid: number;
+    gid: number;
+} | {
+    type: "symlink";
+    path: string;
+    target: string;
+};
+interface ApplyError {
+    change: ChangeEntry;
+    error: Error;
+}
+interface ApplyResult {
+    applied: number;
+    errors: ApplyError[];
+}
+declare class TransactionError extends Error {
+    readonly rootCause: ChangeEntry;
+    readonly sourceError: Error;
+    readonly rollbackErrors: Array<{
+        change: ChangeEntry;
+        error: Error;
+    }>;
+    constructor(message: string, rootCause: ChangeEntry, sourceError: Error, rollbackErrors: Array<{
+        change: ChangeEntry;
+        error: Error;
+    }>);
+}
+interface AdapterCapabilities {
+    permissions: boolean;
+    symlinks: boolean;
+    caseSensitive: boolean;
+}
+interface ApplyOptions {
+    transaction?: boolean;
+}
+interface CreateLayerOptions {
+    root: string;
+    adapter?: FsAdapter;
+}
+
+type FsErrorCode = "ENOENT" | "EACCES" | "EPERM" | "EEXIST" | "ENOTDIR" | "EISDIR" | "ELOOP" | "EINVAL" | "ENOTEMPTY" | "DISPOSED" | "ENOSYS" | "TRANSACTION_FAILED";
+declare class FsError extends Error {
+    readonly code: FsErrorCode;
+    constructor(code: FsErrorCode, message: string);
+}
+
+declare class Layer {
+    private adapter;
+    private ledger;
+    private capabilities;
+    private root;
+    private disposed;
+    constructor(root: string, adapter: FsAdapter, capabilities: AdapterCapabilities);
+    private assertNotDisposed;
+    /**
+     * Enforce ENOSYS for operations that require symlink support.
+     */
+    private assertSymlinksSupported;
+    private resolvePath;
+    /**
+     * Follow symlinks to resolve the final path. Used by operations that
+     * follow symlinks (readFile, stat, writeFile, chmod, chown, exists).
+     */
+    private resolveSymlinks;
+    private resolveRelativeTarget;
+    readFile(path: string): Promise<Uint8Array>;
+    createReadStream(path: string): ReadableStream<Uint8Array>;
+    readdir(path: string): Promise<DirentEntry[]>;
+    private getChangePath;
+    stat(path: string): Promise<StatResult>;
+    lstat(path: string): Promise<StatResult>;
+    private statResolved;
+    readlink(path: string): Promise<string>;
+    exists(path: string): Promise<boolean>;
+    writeFile(path: string, data: string | Uint8Array, options?: WriteOptions): Promise<void>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    symlink(target: string, path: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+    chown(path: string, uid: number, gid: number): Promise<void>;
+    lchown(path: string, uid: number, gid: number): Promise<void>;
+    getOwner(path: string): Promise<{
+        uid: number;
+        gid: number;
+    }>;
+    getChanges(): ChangeEntry[];
+    getChangeDetail(path: string): Promise<ChangeDetail | null>;
+    apply(options?: ApplyOptions): Promise<ApplyResult>;
+    private applyBestEffort;
+    private applyTransaction;
+    /**
+     * Convert a flat ChangeDetail back to a ChangeEntry for error reporting.
+     */
+    private detailToChangeEntry;
+    /**
+     * Get the primary path from a ChangeDetail.
+     */
+    private getDetailPath;
+    private rollbackOne;
+    private applyOne;
+    dispose(): void;
+    reset(): void;
+}
+
+declare class Ledger {
+    private records;
+    private chmodChownPairs;
+    private nextOrder;
+    private caseSensitive;
+    constructor(caseSensitive?: boolean);
+    private normalizePath;
+    has(path: string): boolean;
+    get(path: string): ChangeEntry | undefined;
+    getDetail(path: string): ChangeDetail | null;
+    private recordToDetail;
+    getAll(): ChangeEntry[];
+    getAllDetails(): ChangeDetail[];
+    recordCreate(path: string, entryType: "file" | "directory", content?: Uint8Array, mode?: number, uid?: number, gid?: number): void;
+    recordUpdate(path: string, content?: Uint8Array, mode?: number, uid?: number, gid?: number): void;
+    recordDelete(path: string, entryType?: EntryType): void;
+    recordRename(from: string, to: string): void;
+    recordChmod(path: string, mode: number): void;
+    recordChown(path: string, uid: number, gid: number): void;
+    recordSymlink(path: string, target: string): void;
+    /**
+     * Returns the virtual mode for a path if it has been chmod'd (or created
+     * with a mode) in this ledger.
+     */
+    getVirtualMode(path: string): number | undefined;
+    /**
+     * Returns virtual ownership for a path if it has been chown'd (or created
+     * with ownership) in this ledger.
+     */
+    getVirtualOwnership(path: string): {
+        uid: number;
+        gid: number;
+    } | undefined;
+    /**
+     * Returns the content stored for a path, if any.
+     */
+    getContent(path: string): Uint8Array | undefined;
+    clear(): void;
+}
+
+declare class LocalAdapter implements FsAdapter {
+    private _capabilities;
+    initialize(root: string): Promise<void>;
+    capabilities(): AdapterCapabilities;
+    readFile(filePath: string): Promise<Uint8Array>;
+    createReadStream(filePath: string): ReadableStream<Uint8Array>;
+    readdir(dirPath: string): Promise<DirentEntry[]>;
+    stat(filePath: string): Promise<StatResult>;
+    lstat(filePath: string): Promise<StatResult>;
+    readlink(filePath: string): Promise<string>;
+    exists(filePath: string): Promise<boolean>;
+    writeFile(filePath: string, data: Uint8Array, options?: WriteOptions): Promise<void>;
+    mkdir(dirPath: string, options?: MkdirOptions): Promise<void>;
+    rm(filePath: string, options?: RmOptions): Promise<void>;
+    rmdir(dirPath: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    chmod(filePath: string, mode: number): Promise<void>;
+    chown(filePath: string, uid: number, gid: number): Promise<void>;
+    lchown(filePath: string, uid: number, gid: number): Promise<void>;
+    checkPermission(filePath: string, op: PermissionOp): Promise<void>;
+    private mapError;
+}
+
+declare function createLayer(options: CreateLayerOptions): Promise<Layer>;
+
+export { type AdapterCapabilities, type ApplyError, type ApplyOptions, type ApplyResult, type ChangeDetail, type ChangeEntry, type CreateLayerOptions, type DirentEntry, type EntryType, type FsAdapter, FsError, type FsErrorCode, Layer, Ledger, LocalAdapter, type MkdirOptions, type PermissionOp, type RmOptions, type StatResult, TransactionError, type WriteOptions, createLayer };