Type Alias: FileHandle

FileHandle = { status: "pending"; } | { status: "local"; url: string; mime: string; name?: string; } | { status: "uploading"; url: string; mime: string; name?: string; } | { status: "ready"; url: string; mime: string; name?: string; } | { status: "missing"; } | { status: "error"; error: unknown; }

Defined in: react/src/use-plasma-file.ts:24

Discriminated union returned by usePlasmaFile(ref). The url variants are safe to hand directly to an <img> / <video> / <a download> — revocation is scheduled from inside the hook so the caller never has to think about URL.revokeObjectURL.

pending: initial state until the first read resolves.
local: bytes are cached locally, no upload record on this tab (the ref was fetched from the server or handed in from a rebuild replay).
uploading: bytes are cached locally and the upload worker is (or was) trying to send them upstream.
ready: bytes are cached locally and the server has them too.
missing: the ref is broken (BrokenFileRef sentinel) or the server returned 404. Render a placeholder rather than retrying.
error: the sync API returned a non-404 error or the network call threw. Retryable at the app layer.