`error-codes` — `DB_ADAPTER.*` registry + `DbAdapterError`

(no submodules)

Purpose

This module is the single source of truth for every public failure code raised by @suaveplan/api-db-adapter. Codes are namespaced under DB_ADAPTER.* and exposed through both a const registry (DB_ADAPTER_CODES) and a typed SuaveplanError subclass (DbAdapterError).

Consumers branch on the literal value at runtime — never on the message text — which means the wire format of every error is stable across releases. The registry is consumed by the migration runner, the tenant-scoped wrapper, the options validator, the engine registry, and the db.unsafe-queries capability gate.

Features

Five stable codes covering every public failure path: TENANT_SCOPE_VIOLATION, UNSAFE_NOT_PERMITTED, MIGRATION_FAILED, ENGINE_UNSUPPORTED, INVALID_OPTIONS.
Single DbAdapterError class extending SuaveplanError — discriminable by instanceof or by code string.
SuaveplanErrorOptions.cause is honoured, so engine-side throws (e.g. a Postgres protocol error during migration) are preserved on the cause chain.
Compatible with the standard SuaveplanError wire format — no per-package deviations.

Usage: Basic

import {
    DB_ADAPTER_CODES,
    DbAdapterError,
} from "@suaveplan/api-db-adapter/error-codes";

throw new DbAdapterError(
    DB_ADAPTER_CODES.UNSAFE_NOT_PERMITTED,
    "plugin 'audit' does not declare db.unsafe-queries"
);

Usage: Advanced

import {
    DB_ADAPTER_CODES,
    DbAdapterError,
} from "@suaveplan/api-db-adapter/error-codes";

try {
    await runMigrations(plugin, capabilities);
} catch (cause) {
    throw new DbAdapterError(
        DB_ADAPTER_CODES.MIGRATION_FAILED,
        `migration ${cause.file} failed`,
        { cause, context: { file: cause.file } }
    );
}

API Reference

DB_ADAPTER_CODES — const registry of the five codes.
DbAdapterCode — union of all registry values.
DbAdapterError — subclass of SuaveplanError<DbAdapterCode>.

Implementation Notes

The codes are declared via defineCodes("DB_ADAPTER", [...]) which produces a frozen mapping { TENANT_SCOPE_VIOLATION: "DB_ADAPTER.TENANT_SCOPE_VIOLATION", ... }. Comparisons against the registry value never drift even if a future change reorders the input array because the keys are spelled identically to the prefixed value's tail.

2.4 KiB Raw Blame History

error-codes — DB_ADAPTER.* registry + DbAdapterError