`error-codes`

(no submodules)

Purpose

Frozen registry of the six stable AUDIT_FILE.* error codes raised by the file-rotating audit sink, plus the concrete AuditFileError extends SuaveplanError subclass that carries them. Operators rely on the codes for dashboard slicing; package consumers rely on the typed subclass to differentiate sink failures from generic host errors without parsing message strings.

The registry is built with defineCodes("AUDIT_FILE", [...]) from @suaveplan/error, so every code is recorded in the global registry exactly once at module load. The OpenSpec conformance gate verifies every entry here is also raised by a production code path elsewhere in src/ — no dead codes are permitted.

Features

Six stable codes: INVALID_RECORD, WRITER_FAILED, QUEUE_FULL, ROTATION_FAILED, RETENTION_FAILED, PATH_NOT_WRITEABLE.
Typed union AuditFileCode for narrowing on error.code.
AuditFileError subclass with stable error.name === "AuditFileError".
Forwards cause, context, redacted, and other SuaveplanErrorOptions to the base constructor unchanged.

Usage: Basic

import {
    AUDIT_FILE_CODES,
    AuditFileError,
} from "@suaveplan/api-audit-file/error-codes";

throw new AuditFileError(
    AUDIT_FILE_CODES.PATH_NOT_WRITEABLE,
    "error.audit.file.path_not_writeable",
    { context: { path: "/var/log/suaveplan/audit.log" } }
);

Usage: Advanced

Narrow on the union after catching to drive code-specific recovery:

import {
    AUDIT_FILE_CODES,
    type AuditFileCode,
    AuditFileError,
} from "@suaveplan/api-audit-file/error-codes";

function recover(err: unknown): "retry" | "drop" {
    if (!(err instanceof AuditFileError)) throw err;
    const code: AuditFileCode = err.code;
    if (code === AUDIT_FILE_CODES.QUEUE_FULL) return "drop";
    if (code === AUDIT_FILE_CODES.WRITER_FAILED) return "retry";
    if (code === AUDIT_FILE_CODES.ROTATION_FAILED) return "retry";
    throw err;
}

API Reference

AUDIT_FILE_CODES: Readonly<Record<Name, "AUDIT_FILE.<Name>">>
type AuditFileCode = (typeof AUDIT_FILE_CODES)[keyof typeof AUDIT_FILE_CODES]
AUDIT_FILE_ERROR_NAME = "AuditFileError"
class AuditFileError extends SuaveplanError<AuditFileCode>
- new AuditFileError(code, messageKey, options?)

Implementation Notes

The codes are declared as const so TypeScript freezes both the keys and the fully-qualified string values. The name literal is exported separately because some structured loggers group errors on name before they inspect code — pinning a constant keeps that grouping stable across releases. The module is side-effect-imported from src/index.ts so a consumer who only loads a subpath (@suaveplan/api-audit-file/sink) still triggers code registration.

2.8 KiB Raw Blame History

error-codes