error-codes

(no submodules)

Purpose

Stable error-code registry for @suaveplan/email-templates. Every failure raised by the package extends SuaveplanError with a discriminant code drawn from EMAIL_TEMPLATES_CODES, enabling programmatic dispatch by consumers without coupling to error-message text.

The registry is the contract: every code listed here MUST be thrown by at least one production code path under src/. Removing an entry without removing its call site is forbidden by §2c of AGENTS.md.

Features

Six stable codes registered via defineCodes("EMAIL_TEMPLATES", [...]).
EmailTemplatesError class with public constructor (so external callers can synthesise an instance for re-throw / wrapping).
EmailTemplatesCode discriminant union derived from the registry — every code field is statically narrowable.
Inherits OTel span-event adaptation, redaction, cause-chain traversal, and i18n message-key resolution from SuaveplanError.

Usage: Basic

import {
  EMAIL_TEMPLATES_CODES,
  EmailTemplatesError,
} from "@suaveplan/email-templates/errors";

throw new EmailTemplatesError(
  EMAIL_TEMPLATES_CODES.UNKNOWN_TEMPLATE,
  "email_templates.unknown_template",
);

Usage: Advanced

Wrap an unexpected throwable, preserving its cause for the OTel span-event adapter to surface in tracing:

import {
  EMAIL_TEMPLATES_CODES,
  EmailTemplatesError,
} from "@suaveplan/email-templates/errors";

try {
  renderToHtml(template, props);
} catch (cause) {
  throw new EmailTemplatesError(
    EMAIL_TEMPLATES_CODES.RENDER_FAILURE,
    "email_templates.render_failure",
    { cause: cause instanceof Error ? cause : new Error(String(cause)) },
  );
}

API Reference

Symbol	Kind	Description
`EMAIL_TEMPLATES_CODES`	const	Frozen record of `EMAIL_TEMPLATES.<NAME>` strings.
`EmailTemplatesCode`	type	Discriminant union of every registered code.
`EmailTemplatesError`	class	`SuaveplanError<EmailTemplatesCode>` subclass.

Codes (six): INVALID_TEMPLATE, INVALID_OPTIONS, RENDER_FAILURE, DUPLICATE_NAME, UNKNOWN_TEMPLATE, INVALID_HEADING_LEVEL.

Implementation Notes

The defineCodes helper from @suaveplan/error returns a frozen Record<K, "EMAIL_TEMPLATES.K"> and side-steps the literal-string-typing pitfall by inferring each key as a string-literal type. EmailTemplatesCode is derived via (typeof EMAIL_TEMPLATES_CODES)[keyof typeof ...] so adding or removing a code automatically widens or narrows the union — the TypeScript compiler will refuse to throw an unknown code.

name = "EmailTemplatesError" is set in the constructor (not via static class-name reflection) so that downcasting via the standard err.name === "EmailTemplatesError" discriminant works under minified production bundles. timestamp is supplied by SuaveplanError.

3.1 KiB Raw Blame History