error-codes

(no submodules)

Purpose

error-codes.ts defines the stable, namespaced error-code registry for the @suaveplan/audience-rules package, alongside the discriminated AudienceRulesError class that every failure path raises. It exists so that consumers can dispatch on a stable string ("AUDIENCE_RULES.SEGMENT_NOT_FOUND") rather than parsing error messages, and so that diagnostic context (segmentId / tenantId) survives transport across logger sinks, OTel span events, and structured-output channels without polluting the base SuaveplanError context map.

Features

AUDIENCE_RULES_CODES registry built via defineCodes("AUDIENCE_RULES", [...]) with four stable codes: INVALID_INPUT, SEGMENT_NOT_FOUND, UNKNOWN_OPERATOR, PROVIDER_FAILED.
AudienceRulesErrorCode union type narrowing every legal code value.
AudienceRulesError extends SuaveplanError<AudienceRulesErrorCode> carrying optional segmentId and tenantId discriminants.
AudienceRulesErrorOptions extending SuaveplanErrorOptions with the two discriminant fields.
Compatible with the @suaveplan/error cause-chain traversal, redaction, and OTel span-event adapter without further wiring.

Usage: Basic Example

import {
    AUDIENCE_RULES_CODES,
    AudienceRulesError,
} from "@suaveplan/audience-rules";

throw new AudienceRulesError(
    AUDIENCE_RULES_CODES.SEGMENT_NOT_FOUND,
    "segment 'seg_42' does not exist",
    { segmentId: "seg_42", tenantId: "tenant-1" }
);

Usage: Advanced Example

import {
    AudienceRulesError,
    AUDIENCE_RULES_CODES,
} from "@suaveplan/audience-rules";

function handleRefresh(error: unknown) {
    if (
        error instanceof AudienceRulesError &&
        error.code === AUDIENCE_RULES_CODES.PROVIDER_FAILED
    ) {
        // narrow tenantId for diagnostics, then re-throw with extra context
        throw new AudienceRulesError(
            AUDIENCE_RULES_CODES.PROVIDER_FAILED,
            "contact provider failed during scheduled refresh",
            { tenantId: error.tenantId, cause: error }
        );
    }
    throw error;
}

API Reference

AUDIENCE_RULES_CODES — frozen record mapping every short name to its namespaced string (e.g. INVALID_INPUT → "AUDIENCE_RULES.INVALID_INPUT").
type AudienceRulesErrorCode — union of every namespaced string value.
interface AudienceRulesErrorOptions extends SuaveplanErrorOptions — accepts segmentId?: string, tenantId?: string, plus every option from the base SuaveplanErrorOptions (e.g. cause, context).
class AudienceRulesError extends SuaveplanError<AudienceRulesErrorCode> — constructor (code, message, options?); exposes segmentId?: string and tenantId?: string as readonly own-properties.

Implementation Notes

The registry is intentionally small at v0.1.0. Adding a code requires bumping the package and updating the OpenSpec delta; deleting a code is a breaking change. See AGENTS.md §2c — codes are never removed just because a call site has not been wired yet.
segmentId / tenantId are assigned only when the constructor option is non-undefined, so the runtime shape stays compact for logger redaction passes that walk own-property keys.
defineCodes from @suaveplan/error guarantees the namespaced prefix at type-time, so a typo in the literal ("AUDIENCE_RULE.X") is a compile error, not a silent registry shift.

3.4 KiB Raw Permalink Blame History