error-codes/error-codes

(no submodules)

Purpose

Defines the stable error-code registry for @suaveplan/api-plugin-audit and the concrete AuditPluginError class used by every production code path. The registry is shared with @suaveplan/error's singleton via defineCodes("AUDIT_PLUGIN", [...]), so every code surfaces in the unified ErrorCodes table consumed by logging, metrics, and translation layers.

Every code documented here corresponds to a real failure mode the plugin can surface at the call site. Consumers branch on the string code (error.code === AUDIT_PLUGIN_CODES.INVALID_INPUT) rather than instanceof checks against private subclasses.

Features

Four stable codes: INVALID_INPUT, SERVICE_NOT_AVAILABLE, SINK_INIT_FAILED, SINK_WRITE_FAILED.
AuditPluginError carries cause, context, and the code discriminant via the SuaveplanError base.
Every code is raised by at least one production code path and pinned by src/api-plugin-audit.spec-conformance.test.ts.

Usage: Basic

import {
    AUDIT_PLUGIN_CODES,
    AuditPluginError,
} from "@suaveplan/api-plugin-audit/error-codes/error-codes";

throw new AuditPluginError(
    AUDIT_PLUGIN_CODES.SERVICE_NOT_AVAILABLE,
    "audit plugin requires the `app` service in ServiceRegistry",
    { context: { missing: ["app"], statusCode: 500 } }
);

Usage: Advanced

import {
    AUDIT_PLUGIN_CODES,
    AuditPluginError,
} from "@suaveplan/api-plugin-audit/error-codes/error-codes";

try {
    await sink.save(event);
} catch (cause) {
    const err = new AuditPluginError(
        AUDIT_PLUGIN_CODES.SINK_WRITE_FAILED,
        "audit sink rejected save()",
        { cause, context: { eventId: event.id } }
    );
    logger.warn(err.message, { code: err.code, cause: err.cause });
}

API Reference

AUDIT_PLUGIN_CODES — frozen record from defineCodes("AUDIT_PLUGIN", [...]).
AuditPluginErrorCode — string-literal union of the registered codes.
class AuditPluginError extends SuaveplanError<AuditPluginErrorCode> — public constructor accepts (code, message, options?).

Implementation Notes

The registry is small on purpose. Validation failures map to INVALID_INPUT; structural prerequisite failures map to SERVICE_NOT_AVAILABLE; sink construction failures map to SINK_INIT_FAILED; per-request sink rejections map to SINK_WRITE_FAILED. The middleware path never re-throws SINK_WRITE_FAILED — it logs and counts so the request response is unaffected (telemetry must not 500 the caller).

2.5 KiB Raw Blame History