Interface MountFs

A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root; the accessor resolves them under mount.path. Async-only (ZenFS rides a MessagePort). Obtain one with openFs.

interface MountFs {
    mount: SandboxMount;
    canWrite(relPath?: string): boolean;
    exists(relPath: string): Promise<boolean>;
    mkdir(relPath: string, opts?: { recursive?: boolean }): Promise<void>;
    onChange(cb: (changedRelPaths: string[]) => void): () => void;
    readBlob(relPath: string, opts?: { type?: string }): Promise<Blob>;
    readdir(relPath?: string): Promise<DirEntry[]>;
    readFile(relPath: string, encoding: "utf8"): Promise<string>;
    readFile(relPath: string): Promise<Uint8Array<ArrayBufferLike>>;
    readObjectUrl(
        relPath: string,
        opts?: { type?: string },
    ): Promise<{ revoke: () => void; url: string }>;
    rename(fromRel: string, toRel: string): Promise<void>;
    rm(relPath: string, opts?: { recursive?: boolean }): Promise<void>;
    stat(relPath: string): Promise<FileStat>;
    writeFile(
        relPath: string,
        data: string | Uint8Array<ArrayBufferLike>,
    ): Promise<void>;
}

Properties

mount

Methods

canWrite exists mkdir onChange readBlob readdir readFile readObjectUrl rename rm stat writeFile

Properties

Readonlymount

mount: SandboxMount

The mount this view is anchored to (read mode/rules for writability).

Methods

canWrite

  • canWrite(relPath?: string): boolean

    Client-side writability hint for relPath (mount mode ∩ longest-matching rule), so an app can hide an "edit" affordance instead of catching read-only (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on onMountsChange — a role downgrade flips it. EROFS from the host stays authoritative.

    Parameters

    • OptionalrelPath: string

    Returns boolean

exists

  • exists(relPath: string): Promise<boolean>

    Does relPath exist? Never throws on absence.

    Parameters

    • relPath: string

    Returns Promise<boolean>

mkdir

  • mkdir(relPath: string, opts?: { recursive?: boolean }): Promise<void>

    Create a directory (pass { recursive: true } to make parents).

    Parameters

    • relPath: string
    • Optionalopts: { recursive?: boolean }

    Returns Promise<void>

onChange

  • onChange(cb: (changedRelPaths: string[]) => void): () => void

    Subscribe to changes to files in this mount — the mount-scoped projection of the host working-tree change stream (onFsChange), so a viewer re-reads an affected file instead of polling (SDK_FS_SURFACE_SPEC §5). The callback gets the changed paths RELATIVE to this mount (feed them straight back into readFile/stat/…). Returns an unsubscribe fn.

    Working-tree-only in v1 (an honest gap, O2): the host push channel carries only working-tree changes, so onChange on a NON-working-tree mount (a space) is an inert subscription that never fires until that channel lands. Like onFsChange, origin-exclusion (ignoring the echo of your own write) is the caller's responsibility.

    Parameters

    • cb: (changedRelPaths: string[]) => void

    Returns () => void

readBlob

  • readBlob(relPath: string, opts?: { type?: string }): Promise<Blob>

    Read a file's bytes as a Blob, tagged with a MIME type inferred from the extension (mimeTypeFor) or opts.type when given (falls back to application/octet-stream). The building block for downloads and object URLs.

    Parameters

    • relPath: string
    • Optionalopts: { type?: string }

    Returns Promise<Blob>

readdir

  • readdir(relPath?: string): Promise<DirEntry[]>

    List a directory (the mount root when relPath is omitted).

    Parameters

    • OptionalrelPath: string

    Returns Promise<DirEntry[]>

readFile

  • readFile(relPath: string, encoding: "utf8"): Promise<string>

    Read a file as UTF-8 text (encoding: 'utf8') or raw bytes (omit encoding).

    Parameters

    • relPath: string
    • encoding: "utf8"

    Returns Promise<string>

  • readFile(relPath: string): Promise<Uint8Array<ArrayBufferLike>>

    Parameters

    • relPath: string

    Returns Promise<Uint8Array<ArrayBufferLike>>

readObjectUrl

  • readObjectUrl(
        relPath: string,
        opts?: { type?: string },
    ): Promise<{ revoke: () => void; url: string }>

    Read a file into an object URL suitable for <img src> / <a href> — the fix for "an opaque-origin iframe can't fetch a mount path". Returns the url and a revoke() you MUST call when done (typically on unmount) or the URL leaks. Prefer the useObjectUrl hook / MountImage component, which revoke for you; reach for this directly only outside React.

    Parameters

    • relPath: string
    • Optionalopts: { type?: string }

    Returns Promise<{ revoke: () => void; url: string }>

rename

  • rename(fromRel: string, toRel: string): Promise<void>

    Rename/move within the mount.

    Parameters

    • fromRel: string
    • toRel: string

    Returns Promise<void>

rm

  • rm(relPath: string, opts?: { recursive?: boolean }): Promise<void>

    Remove a file, or a directory with { recursive: true }.

    Parameters

    • relPath: string
    • Optionalopts: { recursive?: boolean }

    Returns Promise<void>

stat

  • stat(relPath: string): Promise<FileStat>

    Stat a path. Throws not-found if absent.

    Parameters

    • relPath: string

    Returns Promise<FileStat>

writeFile

  • writeFile(
        relPath: string,
        data: string | Uint8Array<ArrayBufferLike>,
    ): Promise<void>

    Write text or bytes, creating or truncating the file. Throws read-only on a ro mount.

    Parameters

    • relPath: string
    • data: string | Uint8Array<ArrayBufferLike>

    Returns Promise<void>

Settings

Member Visibility

On This Page

Properties
Methods