@pgxsinkit/pgwasm/dist/fs/base-filesystem.d.ts

/** Stat results, in the shape a POSIX `stat` returns them. Times are milliseconds since the epoch. */
export interface FsStats {
    dev: number;
    ino: number;
    mode: number;
    nlink: number;
    uid: number;
    gid: number;
    rdev: number;
    size: number;
    blksize: number;
    blocks: number;
    atime: number;
    mtime: number;
    ctime: number;
}
/**
 * Errno values, in the numbering Postgres builds use (Emscripten's). A filesystem reports a failed
 * operation by throwing an error whose `code` is one of these; an error without a `code` is reported to
 * Postgres as `EIO`.
 */
export declare const ERRNO_CODES: {
    readonly EBADF: 8;
    readonly EBADFD: 127;
    readonly EEXIST: 20;
    readonly EINVAL: 28;
    readonly EIO: 29;
    readonly EISDIR: 31;
    readonly ENODEV: 43;
    readonly ENOENT: 44;
    readonly ENOTDIR: 54;
    readonly ENOTEMPTY: 55;
};
/**
 * A filesystem call that failed and was reported to Postgres as an errno. Kept in a small ring so
 * that when Postgres later fails, the storage failures underneath it are visible.
 */
export interface SyscallError {
    readonly op: string;
    readonly path: string;
    readonly errno: number;
    readonly message: string;
    readonly timeMs: number;
}
/**
 * What a filesystem says about itself, reported in `pg.storage` as `{ kind: "vfs", ...description }`:
 * a short name for diagnostics, and whether what it holds survives the process (or the page) that wrote it.
 */
export interface FilesystemDescription {
    /** A short name for diagnostics, e.g. `opfs-repacked`. */
    readonly name: string;
    /**
     * Whether the data directory outlives the process (or page) that wrote it. Absent when the filesystem
     * doesn't say: nothing outside it can tell, so callers treat an undeclared filesystem as the author's
     * own call rather than as non-persistent.
     */
    readonly persistent?: boolean;
}
/**
 * A synchronous virtual filesystem that holds a data directory, mounted by a Postgres build in place
 * of its built-in storage (pass it as `createPgwasm({ fs })`). Paths are absolute within the
 * filesystem, `/`-separated, `/` being the data directory itself.
 *
 * Besides the POSIX-shaped operations, a filesystem takes part in durability: pgwasm calls
 * `syncToFs(relaxed)` after statements (see `createPgwasm`'s `relaxedDurability`), the build calls
 * `initialSyncFs()` once when it mounts the filesystem, `closeFs()` when the database closes and
 * `cleanupFailedInit()` when a boot fails after the filesystem was handed over.
 */
export declare abstract class BaseFilesystem {
    #private;
    readonly debug: boolean;
    constructor({ debug }?: {
        debug?: boolean;
    });
    /**
     * What this filesystem is, as `pg.storage` reports it. Defaults to `{ name: "custom" }`, persistence
     * undeclared: a filesystem overrides it to name itself and to say whether its data outlives the process
     * (`persistent: true`) or not (`persistent: false`), since nothing else can tell.
     */
    get description(): FilesystemDescription;
    /** The most recent failed filesystem calls reported to Postgres (up to 50), oldest first. */
    get recentSyscallErrors(): readonly SyscallError[];
    /** Record a failed call. The build's mount calls this where it turns a thrown error into an errno. */
    recordSyscallError(op: string, path: string, errno: number, message: string): void;
    /** Make everything written so far durable. `relaxed` is pgwasm's background persist. */
    syncToFs(_relaxed?: boolean): Promise<void>;
    /** Called once when the build mounts the filesystem, before anything reads it. */
    initialSyncFs(): Promise<void>;
    /** Release everything the filesystem holds. Called when the database closes. */
    closeFs(): Promise<void>;
    /** Release what the filesystem holds after a boot failed. Defaults to {@link closeFs}. */
    cleanupFailedInit(): Promise<void>;
    abstract chmod(path: string, mode: number): void;
    abstract close(fd: number): void;
    abstract fstat(fd: number): FsStats;
    abstract lstat(path: string): FsStats;
    abstract mkdir(path: string, options?: {
        recursive?: boolean;
        mode?: number;
    }): void;
    abstract open(path: string, flags?: string, mode?: number): number;
    abstract readdir(path: string): string[];
    /** Read into `buffer[offset, offset + length)` from `position`; returns the bytes read. */
    abstract read(fd: number, buffer: Uint8Array, offset: number, length: number, position: number): number;
    abstract rename(oldPath: string, newPath: string): void;
    abstract rmdir(path: string): void;
    abstract truncate(path: string, length: number): void;
    abstract unlink(path: string): void;
    abstract utimes(path: string, atime: number, mtime: number): void;
    abstract writeFile(path: string, data: string | Uint8Array, options?: {
        encoding?: string;
        mode?: number;
        flag?: string;
    }): void;
    /** Write `buffer[offset, offset + length)` at `position`; returns the bytes written. */
    abstract write(fd: number, buffer: Uint8Array, offset: number, length: number, position: number): number;
}
//# sourceMappingURL=base-filesystem.d.ts.map