# `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

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

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

## Usage: Advanced Example

```ts
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`.