`error-codes` — OPFS error registry

Purpose

Single source of truth for every error code the @suaveplan/storage-browser-opfs package can throw. The registry uses defineCodes("OPFS", [...]) from @suaveplan/error so each code is namespaced (OPFS.NOT_FOUND, OPFS.QUOTA_EXCEEDED, etc.), frozen at module load, and surfaced via a typed OpfsErrorCode union. Centralising the registry keeps the boundary error vocabulary tiny, prevents drift between the implementation and the spec, and lets callers pattern-match on a stable string code rather than parsing message text.

Features

Nine frozen codes covering every observable failure mode: NOT_FOUND, PERMISSION_DENIED, QUOTA_EXCEEDED, UNAVAILABLE, INVALID_KEY, KEY_TOO_LONG, INVALID_OPTIONS, ABORTED, IO_FAILED.
OpfsError extends SuaveplanError<OpfsErrorCode> with an optional key discriminant.
cause chain preserved from upstream DOMException instances.
TypeScript-narrowed OpfsErrorCode union for exhaustive switches.

Usage: Basic Example

import { OPFS_CODES, OpfsError } from "@suaveplan/storage-browser-opfs";

throw new OpfsError(OPFS_CODES.NOT_FOUND, "missing entry", { key: "user/42" });

Usage: Advanced Example

import {
    OPFS_CODES,
    OpfsError,
    type OpfsErrorCode,
} from "@suaveplan/storage-browser-opfs";

function handle(err: unknown): "retry" | "fail" | "ignore" {
    if (!(err instanceof OpfsError)) return "fail";
    const code: OpfsErrorCode = err.code;
    switch (code) {
        case OPFS_CODES.NOT_FOUND:
            return "ignore";
        case OPFS_CODES.QUOTA_EXCEEDED:
        case OPFS_CODES.IO_FAILED:
            return "retry";
        default:
            return "fail";
    }
}

API Reference

OPFS_CODES — frozen Readonly<Record<CodeName, "OPFS.CodeName">> produced by defineCodes.
OpfsErrorCode — the union type of every member of OPFS_CODES.
OpfsError extends SuaveplanError<OpfsErrorCode> — constructor (code, message, options?) where options.key carries the offending key for correlation and options.cause chains the original error.

Implementation Notes

The registry is frozen at module load — adding a new code requires changing this file, which forces the spec delta to be updated in lockstep. OpfsError.name is set to "OpfsError" so devtools display useful labels. The key discriminant is the only optional field on the error class because no other piece of error context is universal across the nine paths; callers needing more should consult cause.

2.5 KiB Raw Blame History

error-codes — OPFS error registry