---
title: API 參考
description: I18nErrorBase、setErrorMessage 及相關型別的規格。
---

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

用於繼承 `Error` 的基底類別。`message` 根據 `lang` 解析。

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

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

### 型別參數 [#type-params]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `TMeta` | `ErrorMeta \| undefined` | `ErrorMeta \| undefined` | `meta` 的型別。不使用時請指定 `undefined`。 |

### 靜態屬性 [#static-props]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `prefix?` | `string` | `undefined` | 串接至解析後訊息的開頭。 |

### 實例屬性 [#instance-props]

| Prop | Type | Description |
| ---- | ---- | ----------- |
| `meta` | `TMeta` | 建構函式的附加資訊，可讀寫。 |
| `message` | `string` | 根據 `lang` 解析的訊息，可列舉。 |
| `cause` | `unknown` | 經 `ErrorOptions` 傳入的原因，`Error` 的標準屬性。 |

### 建構函式 [#constructor]

`TMeta` 不包含 `undefined` 時，`meta` 為必填。

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

`TMeta` 為 `undefined` 時，可省略 `meta`。

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

| 參數 | 型別 | 說明 |
| ------------ | -- | ---- |
| `meta` | `TMeta` | 用於訊息產生的附加資訊。 |
| `message` | `string \| MessageFactory<TMeta>` | 用於未註冊語言的預設訊息。為函式時會接收 `meta`。 |
| `options` | `ErrorOptions` | 與 `Error` 第二個參數相容的選項（例如 `{ cause }`）。 |

### 解析順序 [#resolution-order]

1. 取得 `getGlobalConfig()` 的 `lang`（未設定時為 `"en"`）
2. 執行該類別、該語言的註冊函式，並傳入 `meta`
3. 未註冊時使用預設訊息
4. 若有 `static prefix`，則串接至開頭

:::note
註冊按類別區分。父類別的註冊不會被子類別繼承，請按類別分別註冊。
:::

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

註冊各語言的訊息產生函式。

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

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

| 參數 | 型別 | 說明 |
| ------------ | -- | ---- |
| `reference` | `I18nErrorBaseConstructor` | 繼承了 `I18nErrorBase` 的類別。未繼承的類別是型別錯誤。 |
| `message` | `string \| (meta) => string` | 要註冊的訊息。`meta` 的型別自目標類別推斷。 |
| `lang` | `string \| Iterable<string>` | 目標語言。單一代碼或可迭代物件（例如陣列）。 |

同一類別、同一語言的重新註冊會覆寫。

## 型別 [#types]

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

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

`TMeta` 的預設約束。具有任意屬性的唯讀物件。

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

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

自 `Error` 第二個參數推導的型別。可傳入 `cause`。

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

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

根據 `meta` 產生訊息的函式。既可用於預設訊息，亦可用於註冊值。

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

建構函式參數多載的型別。

```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];
```

僅當 `TMeta` 為 `undefined` 時，才可省略 `meta`。

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

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

`setErrorMessage` 第一個參數的型別。

## 補充說明 [#notes]

- `lang` 預設值為 `"en"`，請透過 `setGlobalConfig({ lang })` 切換
- 不正規化語言代碼，亦無後備鏈（例如 `en-US` → `en`）。未註冊的語言使用預設訊息