`error-codes` — `AUDIT_STDOUT_*` registry

(no submodules)

Purpose

This module declares the four stable error codes the stdout audit sink exposes to consumers. Every failure path inside createStdoutAuditSink maps onto exactly one of them, so callers can branch on error.code without parsing messages or stack traces. The registry uses @suaveplan/error's defineCodes so the union narrows under instanceof AuditStdoutError.

The codes capture the four observable failure modes of a write-only, fire-and-forget audit pipeline: a record that fails its own Zod schema (INVALID_RECORD), an option bag that fails the constructor schema (INVALID_OPTIONS), a transport error from the supplied writer (WRITER_FAILED), and the bounded-backpressure drop case (QUEUE_FULL). The codes are surfaced through the AuditStdoutError subclass, which carries a code property typed as the literal union — instanceof narrowing flows through.

Features

Stable string codes via defineCodes("AUDIT_STDOUT", [...]).
AuditStdoutError subclass with public constructor (lint rule check-error-subclass-constructors enforced).
Code union exported as AuditStdoutErrorCode for callers who want to switch over every member.
No runtime side effects — the registry is a frozen object literal.

Usage: Basic

import {
    AUDIT_STDOUT_CODES,
    AuditStdoutError,
} from "@suaveplan/api-audit-stdout/error-codes";

throw new AuditStdoutError(
    AUDIT_STDOUT_CODES.INVALID_RECORD,
    "error.audit_stdout.invalid_record"
);

Usage: Advanced

import {
    AUDIT_STDOUT_CODES,
    AuditStdoutError,
    type AuditStdoutErrorCode,
} from "@suaveplan/api-audit-stdout/error-codes";

function handle(err: unknown): "drop" | "rethrow" {
    if (!(err instanceof AuditStdoutError)) return "rethrow";
    const code: AuditStdoutErrorCode = err.code;
    switch (code) {
        case AUDIT_STDOUT_CODES.QUEUE_FULL:
        case AUDIT_STDOUT_CODES.WRITER_FAILED:
            return "drop";
        case AUDIT_STDOUT_CODES.INVALID_RECORD:
        case AUDIT_STDOUT_CODES.INVALID_OPTIONS:
            return "rethrow";
    }
}

API Reference

AUDIT_STDOUT_CODES — frozen { INVALID_RECORD, WRITER_FAILED, QUEUE_FULL, INVALID_OPTIONS } mapping to the corresponding "AUDIT_STDOUT.*" literal.
AuditStdoutErrorCode — union of the four literal strings.
AuditStdoutError — SuaveplanError<AuditStdoutErrorCode> subclass with a public constructor accepting (code, message, options?).

Implementation Notes

defineCodes returns a frozen object — adding a new code requires an OpenSpec change. The subclass declares its own public constructor so new AuditStdoutError(...) is callable from outside the module (the base class is abstract with a protected constructor). The auditStdoutCode field is a typed alias of code for callers who want a non-generic accessor.

2.9 KiB Raw Permalink Blame History

error-codes — AUDIT_STDOUT_* registry