Stone.js API
    Preparing search index...

    Interface FileSystem

    Agnostic storage-driver contract for Stone.js.

    This is the abstraction that makes the filesystem layer backend-independent: the local disk (LocalFileSystem) implements it today, and a future S3FileSystem (or GCS, Azure Blob, R2, in-memory…) implements the exact same interface. Application/domain code depends only on FileSystem, never on node:fs, so switching or mixing backends is a configuration concern (see StorageManager), not a code change.

    Every operation is async — object stores are inherently network-bound, and even the local driver uses non-blocking I/O so a file operation never stalls the event loop. Paths are always relative to the driver's root (its "disk"/"bucket"); a driver MUST confine access to that root.

    interface FileSystem {
        copy: (source: string, destination: string) => Promise<void>;
        delete: (path: string) => Promise<boolean>;
        exists: (path: string) => Promise<boolean>;
        files: (directory?: string, recursive?: boolean) => Promise<string[]>;
        get: (path: string) => Promise<Buffer<ArrayBufferLike>>;
        getText: (path: string, encoding?: BufferEncoding) => Promise<string>;
        lastModified: (path: string) => Promise<number>;
        makeDirectory: (path: string) => Promise<void>;
        mimeType: (path: string) => Promise<string>;
        move: (source: string, destination: string) => Promise<void>;
        name: string;
        put: (
            path: string,
            content: string | Buffer<ArrayBufferLike>,
        ) => Promise<void>;
        readStream: (path: string) => Promise<Readable>;
        size: (path: string) => Promise<number>;
        stat: (path: string) => Promise<StorageStat>;
        url: (path: string) => Promise<string>;
        writeStream: (path: string, stream: Readable) => Promise<void>;
    }

    Implemented by

    Index
    copy delete exists files get getText lastModified makeDirectory mimeType move name put readStream size stat url writeStream
    copy: (source: string, destination: string) => Promise<void>

    Copy source to destination within the disk.

    delete: (path: string) => Promise<boolean>

    Delete path. Resolves to whether something was actually deleted.

    exists: (path: string) => Promise<boolean>

    Whether a file (or object) exists at path.

    files: (directory?: string, recursive?: boolean) => Promise<string[]>

    List the file paths under directory (relative to the root), optionally recursively.

    get: (path: string) => Promise<Buffer<ArrayBufferLike>>

    Read the raw bytes at path.

    getText: (path: string, encoding?: BufferEncoding) => Promise<string>

    Read the content at path decoded as text.

    lastModified: (path: string) => Promise<number>

    The last-modified time (epoch ms) of path, if known.

    makeDirectory: (path: string) => Promise<void>

    Ensure a directory/prefix exists.

    mimeType: (path: string) => Promise<string>

    The best-effort MIME type of path, if known.

    move: (source: string, destination: string) => Promise<void>

    Move/rename source to destination within the disk.

    name: string

    A human-readable disk name (e.g. 'local', 's3'), used by the StorageManager.

    put: (path: string, content: string | Buffer<ArrayBufferLike>) => Promise<void>

    Write content to path, creating parent directories/prefixes as needed (overwrites).

    readStream: (path: string) => Promise<Readable>

    Open a readable stream for path (streaming large objects without buffering).

    size: (path: string) => Promise<number>

    The size in bytes of path.

    stat: (path: string) => Promise<StorageStat>

    Full metadata for path.

    url: (path: string) => Promise<string>

    A URL for path (a file:// URL locally; a public/presigned URL for object stores).

    writeStream: (path: string, stream: Readable) => Promise<void>

    Write a readable stream to path.

    Settings
    Member Visibility

    On This Page
    Properties