first commit

docs/persistence/storage/storage-browser-opfs/src/error-codes.md

@@ -0,0 +1,54 @@
+# `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`.