---
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`)은 없습니다. 미등록 언어는 기본 메시지입니다