`error-codes`

(no submodules)

Purpose

Defines the stable DATABASE_* error-code registry consumed by every other module in the @suaveplan/api-plugin-database package and by downstream observers that branch on error.code. The codes are registered through defineCodes from @suaveplan/error so they participate in the cross-package code namespace and inherit the canonical SuaveplanError wire-format, redaction, and OTel span-event integration.

The companion DatabaseError class extends SuaveplanError<DatabaseErrorCode> so instanceof DatabaseError narrows error.code to the literal union at every catch site. Consumers can write if (error instanceof DatabaseError && error.code === DATABASE_CODES.POOL_EXHAUSTED) and get exhaustive type checking from TypeScript.

Features

Eight stable codes spanning connection, pool, query, migration, lock, tenant, and configuration concerns.
Literal-typed code values ("DATABASE.POOL_EXHAUSTED", etc.) computed by defineCodes.
DatabaseError carries cause, context, timestamp, and i18n message-key support inherited from SuaveplanError.
Frozen registry object — runtime mutation throws.

Usage: Basic

import {
    DATABASE_CODES,
    DatabaseError,
} from "@suaveplan/api-plugin-database/error-codes/error-codes";

throw new DatabaseError(
    DATABASE_CODES.POOL_EXHAUSTED,
    "no free connections available after 5s"
);

Usage: Advanced

import {
    DATABASE_CODES,
    DatabaseError,
    type DatabaseErrorCode,
} from "@suaveplan/api-plugin-database";

function isTransient(code: DatabaseErrorCode): boolean {
    return (
        code === DATABASE_CODES.POOL_EXHAUSTED ||
        code === DATABASE_CODES.CONNECTION_FAILED
    );
}

try {
    await db.query("SELECT * FROM users");
} catch (err) {
    if (err instanceof DatabaseError && isTransient(err.code)) {
        // exponential backoff retry path
    } else {
        throw err;
    }
}

API Reference

`DATABASE_CODES`

Frozen object mapping reason → fully-qualified code string. Exact keys: CONNECTION_FAILED, POOL_EXHAUSTED, POOL_CLOSED, QUERY_FAILED, MIGRATION_FAILED, LOCK_CONTENDED, TENANT_INVALID, INVALID_CONFIG.

`DatabaseErrorCode`

Literal union of the eight code strings (e.g. "DATABASE.POOL_EXHAUSTED").

`class DatabaseError extends SuaveplanError<DatabaseErrorCode>`

new DatabaseError(code, message, options?) — constructs an error carrying the supplied code. Options accept cause, context, and clock per the parent class.
databaseCode — convenience alias of code typed at the literal union.

Implementation Notes

The registry intentionally avoids redundant INTERNAL / UNKNOWN slots. Every wrapper in this package uses one of the eight codes; anything truly unexpected propagates as the underlying Error.
Adding a code is a breaking change for the API surface (the literal union widens) — bump the package version and add a ## MODIFIED Requirements entry in the spec delta.
defineCodes freezes the returned object; tests verify the surface against the registered list rather than the implementation.

3.2 KiB Raw Blame History

error-codes