# `errors/errors.ts`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Defines the `PWA_CODES` stable error-code registry, the `PwaError` base class, and
the frozen `PWA_ERROR_METADATA` table mapping every code to its HTTP status,
severity, retryability, and human-readable description. Every error thrown or
reported by `@suaveplan/pwa` carries one of these codes so retry strategies,
logger pipelines, and observability sinks can classify failures without
string-matching on the `Error.message`. Codes are namespaced under `PWA.*`.

## Features

- 8 stable codes covering every documented failure path (service-worker
  unsupported / registration / update, push unsupported / permission, sync-queue
  full / validation, manifest validation).
- `PwaError extends SuaveplanError` so the project's logger and wire serialiser
  treat the error identically to every other domain error.
- Frozen `PWA_ERROR_METADATA` table with `{ httpStatus, severity, retryable,
  description }` per code.

## Usage: Basic

```ts
import { PWA_CODES, PwaError } from "@suaveplan/pwa";

throw new PwaError(
    PWA_CODES.SW_REGISTRATION_FAILED,
    "Service worker registration failed for /sw.js"
);
```

## Usage: Advanced

Inspect metadata for retry decisions:

```ts
import { PWA_ERROR_METADATA, PwaError, PWA_CODES } from "@suaveplan/pwa";

function shouldRetry(err: unknown): boolean {
    if (!(err instanceof PwaError)) return false;
    return PWA_ERROR_METADATA[err.code].retryable;
}

const err = new PwaError(
    PWA_CODES.SW_UPDATE_FAILED,
    "ServiceWorkerRegistration.update rejected",
    { cause: new Error("Network down") }
);
console.assert(shouldRetry(err));
```

## API Reference

- `PWA_CODES` — frozen record of `{ [Reason]: "PWA.<Reason>" }`.
- `PwaErrorCode` — union of every documented code.
- `PwaCodeMetadata` — `{ httpStatus, severity, retryable, description }`.
- `PWA_ERROR_METADATA` — frozen mapping of every `PwaErrorCode` to its metadata.
- `PwaError` — base error class, subclass of `SuaveplanError`.

## Implementation Notes

`PWA_ERROR_METADATA` is constructed with `Object.freeze` so consumers cannot mutate
classifications at runtime. The class name is set to `PwaError` in the constructor
so `error.name` matches the export name across every JS engine (including those
that minimise class names). Codes are defined via `defineCodes("PWA", [...])`
from `@suaveplan/error` to keep the namespace prefix in one place and to type the
returned codes as template-literal strings (`"PWA.SW_UNSUPPORTED"`, etc.). This
allows literal-typed unions in `PwaError<TCode>` without the implementation
needing to thread the namespace string through every callsite.