error-codes

(no submodules)

Purpose

error-codes is the public re-export surface for the serialization error code registry. It imports serialize-error as a side effect — which ensures all SERIALIZE_CODES are registered with @suaveplan/error's global code table at the moment any consumer first imports this module — and then re-exports the codes and the SerializationErrorCode union type under the stable public alias SERIALIZE_ERROR_METADATA.

The module also exports a registerSerializeErrorCodes() function for callers that need an explicit, named registration step (e.g., test setup files or dependency injection bootstraps) rather than relying on side-effect imports.

Features

Triggers side-effect registration of all SERIALIZE_CODES via a single import
Re-exports SERIALIZE_CODES as SERIALIZE_ERROR_METADATA to match the @suaveplan/error naming convention for externally-published code registries
Re-exports the SerializationErrorCode union type for use in typed error handling
Provides an explicit registerSerializeErrorCodes() no-op function for consumers that prefer named-import bootstrapping over implicit side effects
Lightweight: no runtime logic beyond the re-export and the single side-effect import

Usage: Basic Example

import { SERIALIZE_ERROR_METADATA } from "@suaveplan/serialize/error-codes";

// SERIALIZE_ERROR_METADATA is now populated with all SERIALIZE_* codes
console.log(SERIALIZE_ERROR_METADATA["CODEC.CIRCULAR_REFERENCE"]);
// => "SERIALIZE.CODEC.CIRCULAR_REFERENCE"

Usage: Advanced Example

import { registerSerializeErrorCodes, SERIALIZE_ERROR_METADATA, type SerializationErrorCode } from "@suaveplan/serialize/error-codes";
import { SuaveplanError } from "@suaveplan/error";

// Explicit bootstrap for DI containers that prefer named calls
registerSerializeErrorCodes(); // no-op, side effect already happened at import

function isSerializeError(err: unknown): err is SuaveplanError {
  if (!(err instanceof SuaveplanError)) return false;
  const codes = Object.values(SERIALIZE_ERROR_METADATA) as SerializationErrorCode[];
  return codes.includes(err.code as SerializationErrorCode);
}

API Reference

`SERIALIZE_ERROR_METADATA`

Re-export of SERIALIZE_CODES from ./errors/codes. A frozen record mapping each short code key (e.g., "CODEC.CIRCULAR_REFERENCE") to its fully-qualified "SERIALIZE.CODEC.CIRCULAR_REFERENCE" string.

`type SerializationErrorCode`

Union of all values in SERIALIZE_ERROR_METADATA. Use this type to narrow SuaveplanError.code in catch blocks.

`registerSerializeErrorCodes(): void`

Intentional no-op. The actual registration occurs as a side effect of importing this module. The function exists for callers that want a named, explicit registration call for documentation or DI-bootstrap clarity.

Implementation Notes

The side-effect import pattern (import "./errors/serialize-error.js") is the standard approach used across all @suaveplan/* packages to ensure error codes are registered before any error can be constructed or inspected. Consumers that import this module at application startup (or in a test setup file) are guaranteed that all SERIALIZE_* codes are present in the global registry even if no serialization operation has been attempted yet.

The registerSerializeErrorCodes() stub is provided as a forward-compatible hook: if registration ever needs to become asynchronous or accept configuration parameters, the function signature can evolve without breaking existing callers.

3.5 KiB Raw Blame History