error

Utilities for creating structured errors with stable runtime contracts.

Template and coded errors retain their original interpolation values. Symbol-based branding, detected consistently with is.branded(), allows the supplied guards to recognize errors across package instances and JavaScript realms.

import error from "@rcompat/error";
import type { CodeError, TemplateError } from "@rcompat/error";

error.CodeError#

Structured template error carrying a stable string code.

Type parameters

• Code — String literal type of the error code.

declare class CodeError<Code extends string = string> extends TemplateError {}

CodeError constructor#

new error.CodeError()#

Creates a coded error from template segments and interpolation values.

Parameters

• code — Stable error code.
• strings — Template string segments.
• params — Interpolated template values.

constructor(code: Code, strings: TemplateStringsArray, ...params: unknown[])

CodeError static methods#

error.CodeError.is()#

Checks whether a value carries the global CodeError brand.

Parameters

• value — Value to inspect.

error.CodeError.is(value: unknown): value is CodeError

error.CodeError.matches()#

Checks for a coded error and narrows it to one code.

Parameters

• value — Value to inspect.
• code — Required error code.

error.CodeError.matches<Code extends string>(
    value: unknown,
    code: Code,
  ): value is CodeError<Code>

CodeError instance properties#

codedError.code#

Stable string code carried by this error.

get code(): Code

error.coded#

Wraps template-error factories with their keys as stable error codes.

Type parameters

• T — Dictionary of named template-error factories.

Parameters

• factories — Factories to wrap.

Returns: Factories with the same parameters that return coded errors.

error.coded<T extends Dict<ErrorFunction>>(factories: T): {
    [K in keyof T]: (...args: Parameters<T[K]>) => CodeError<K & string>;
  };

Example

const E = error.coded({
  missing: (name: string) => error.template`Missing ${name}`,
});
const failure = E.missing("config.json");
failure.code; // "missing"
failure.message; // "Missing config.json"

error.names#

Maps every own enumerable key of an object to its own name.

Type parameters

• T — Object whose keys become names.

Parameters

• object — Object supplying the keys.

Returns: A typed key-to-name object.

error.names<T extends Dict>(object: T): { [K in keyof T]: K };

error.template#

Creates a structured error from a tagged template.

Parameters

• strings — Template string segments supplied by the tag call.
• params — Interpolated template values.

Returns: An error retaining the segments and values.

error.template(
    strings: TemplateStringsArray,
    ...params: unknown[]
  ): TemplateError;

TemplateError#

Error created from a tagged template with its source values retained.

Import this class as a type. Create instances with error.template.

declare class TemplateError extends Error {}

TemplateError instance properties#

templateError.strings#

Template string segments from the original tagged-template call.

get strings(): TemplateStringsArray

templateError.params#

Interpolated values from the original tagged-template call.

get params(): unknown[]

Supporting contracts#

ErrorFunction#

Factory that creates a structured template error.

type ErrorFunction = (...args: any[]) => TemplateError;

Coded#

Converts template-error factories to coded-error factories.

Type parameters

• T — Dictionary of template-error factories.

type Coded<T extends Dict<ErrorFunction>> = {
  [K in keyof T]: (...args: Parameters<T[K]>) => CodeError<K & string>;
};