---
title: API Reference
description: Specifications for I18nErrorBase, setErrorMessage, and related types.
---

## `I18nErrorBase` [#i18n-error-base]

A base class for extending `Error`. `message` resolves according to `lang`.

```ts
import { I18nErrorBase } from "i18n-error-base";

class MyError extends I18nErrorBase<{ code: string }> {}
```

### Type parameters [#type-params]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `TMeta` | `ErrorMeta \| undefined` | `ErrorMeta \| undefined` | The type of `meta`. Specify `undefined` when unused. |

### Static properties [#static-props]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `prefix?` | `string` | `undefined` | Prepended to the resolved message. |

### Instance properties [#instance-props]

| Prop | Type | Description |
| ---- | ---- | ----------- |
| `meta` | `TMeta` | Constructor auxiliary info. Readable and writable. |
| `message` | `string` | Resolves according to `lang`. Enumerable. |
| `cause` | `unknown` | The cause from `ErrorOptions`. A standard `Error` property. |

### Constructor [#constructor]

When `TMeta` excludes `undefined`, `meta` is required.

```ts
new MyError(meta, message, options?)
```

When `TMeta` is `undefined`, `meta` can be omitted.

```ts
new MyError(message, options?)
new MyError(meta, message, options?)
```

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `meta` | `TMeta` | Auxiliary info for message generation. |
| `message` | `string \| MessageFactory<TMeta>` | Default message for unregistered languages. Functions receive `meta`. |
| `options` | `ErrorOptions` | Options compatible with `Error`'s second argument (e.g. `{ cause }`). |

### Resolution order [#resolution-order]

1. Get `lang` from `getGlobalConfig()` (`"en"` when unset).
2. Run the registered function for that class and language with `meta`.
3. When unregistered, use the default message.
4. If `static prefix` is set, prepend it.

:::note
Registrations are per-class. Parent registrations are not inherited. Register each class.
:::

## `setErrorMessage` [#set-error-message]

Registers per-language message factory functions.

```ts
import { setErrorMessage } from "i18n-error-base";

setErrorMessage(MyError, (meta) => `...: ${meta.code}`, "ja");
```

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `reference` | `I18nErrorBaseConstructor` | A class extending `I18nErrorBase`. Non-subclasses are a type error. |
| `message` | `string \| (meta) => string` | The message to register. `meta` is inferred from the target class. |
| `lang` | `string \| Iterable<string>` | The target language. A single code or an iterable (e.g. an array). |

Re-registering the same class and language overwrites.

## Types [#types]

### `ErrorMeta` [#error-meta]

```ts
type ErrorMeta = {
  readonly [prop: string]: unknown;
};
```

The default constraint for `TMeta`. A readonly object with arbitrary properties.

### `ErrorOptions` [#error-options]

```ts
type ErrorOptions =
  ConstructorParameters<typeof Error> extends [
    message?: unknown,
    options?: (infer TOptions) | undefined,
  ]
    ? TOptions
    : { readonly cause?: unknown };
```

A type derived from `Error`'s second argument. You can pass `cause`.

### `MessageFactory<TMeta>` [#message-factory]

```ts
interface MessageFactory<TMeta extends ErrorMeta | undefined = ErrorMeta | undefined> {
  (meta: TMeta): string;
}
```

A function that creates a message from `meta`. Used for both default and registered messages.

### `I18nErrorBaseParams<TMeta>` [#i18n-error-base-params]

Constructor argument overloads.

```ts
type I18nErrorBaseParams<TMeta extends ErrorMeta | undefined = ErrorMeta | undefined> =
  [TMeta] extends [undefined]
    ?
        | [message: string | MessageFactory<TMeta>, options?: ErrorOptions | undefined]
        | [meta: undefined, message: string | MessageFactory<TMeta>, options?: ErrorOptions | undefined]
    : [meta: TMeta, message: string | MessageFactory<TMeta>, options?: ErrorOptions | undefined];
```

Omit `meta` only when `TMeta` is `undefined`.

### `I18nErrorBaseConstructor` [#i18n-error-base-constructor]

```ts
interface I18nErrorBaseConstructor {
  new (...args: any): I18nErrorBase;
}
```

The type of `setErrorMessage`'s first argument.

## Notes [#notes]

- The default `lang` is `"en"`. Switch with `setGlobalConfig({ lang })`.
- No language code normalization or fallback chain (e.g. `en-US` → `en`). Unregistered languages use the default message.