delivery-tracking-error

(no submodules)

Purpose

DeliveryTrackingError is the stable typed error class raised by every code path inside @suaveplan/delivery-tracking. It extends @suaveplan/error's SuaveplanError with a discriminant code drawn from the DELIVERY_TRACKING_CODES registry, giving consumers instanceof + code branching without inspecting the i18n-keyed message string.

The codes are stable across versions: each entry exists because at least one production code path can produce it (lifecycle dedupe, store I/O, token parsing, webhook routing). Consumers can build exhaustive switches over the union derived from the registry and rely on TypeScript's exhaustiveness check to flag any future addition.

Features

Code registry generated via defineCodes("DELIVERY_TRACKING", […]).
Five stable codes: INVALID_INPUT, INVALID_TOKEN, UNSUPPORTED_PROVIDER, STORE_FAILURE, QUERY_FAILURE.
Subclass of SuaveplanError preserving cause chains, context bags, and i18n message keys.
Type-safe DeliveryTrackingCode union derived from the registry — no manual sync.

Usage: Basic

import {
    DELIVERY_TRACKING_CODES,
    DeliveryTrackingError,
} from "@suaveplan/delivery-tracking/errors";

throw new DeliveryTrackingError(
    DELIVERY_TRACKING_CODES.INVALID_INPUT,
    "error.delivery_tracking.invalid_input",
    { context: { field: "tenantId" } }
);

Usage: Advanced

import {
    DELIVERY_TRACKING_CODES,
    DeliveryTrackingError,
    type DeliveryTrackingCode,
} from "@suaveplan/delivery-tracking/errors";

function classify(err: unknown): "client" | "server" | "other" {
    if (!(err instanceof DeliveryTrackingError)) return "other";
    const code: DeliveryTrackingCode = err.code;
    switch (code) {
        case DELIVERY_TRACKING_CODES.INVALID_INPUT:
        case DELIVERY_TRACKING_CODES.INVALID_TOKEN:
        case DELIVERY_TRACKING_CODES.UNSUPPORTED_PROVIDER:
            return "client";
        case DELIVERY_TRACKING_CODES.STORE_FAILURE:
        case DELIVERY_TRACKING_CODES.QUERY_FAILURE:
            return "server";
    }
}

API Reference

DELIVERY_TRACKING_CODES — frozen record of stable codes, each value prefixed DELIVERY_TRACKING.*.
type DeliveryTrackingCode — union of the registry's values.
class DeliveryTrackingError extends SuaveplanError<DeliveryTrackingCode> — accepts (code, messageKey, options?) and exposes code, messageKey, cause, and context on the resulting instance.

Implementation Notes

The registry is defineCodes("DELIVERY_TRACKING", [...] as const); the as const is what keeps the resulting object literal-typed so the union can be derived. The class only widens the protected constructor to public and sets this.name = "DeliveryTrackingError" — every other behaviour (cause chains, redaction, OTel span enrichment) is inherited from SuaveplanError.

2.9 KiB Raw Blame History