`errors/errors.ts`

(no submodules)

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

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:

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.

2.6 KiB Raw Blame History

errors/errors.ts