---
title: Referência da API
description: Especificações de I18nErrorBase, setErrorMessage e dos tipos relacionados.
---

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

Classe base para herança de `Error`. A `message` é resolvida consoante o `lang`.

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

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

### Parâmetros de tipo [#type-params]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `TMeta` | `ErrorMeta \| undefined` | `ErrorMeta \| undefined` | O tipo de `meta`. Indique `undefined` quando não o utilizar. |

### Propriedades estáticas [#static-props]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `prefix?` | `string` | `undefined` | Anteposto à mensagem resolvida. |

### Propriedades de instância [#instance-props]

| Prop | Type | Description |
| ---- | ---- | ----------- |
| `meta` | `TMeta` | Informação auxiliar do construtor. Pode ser lida e escrita. |
| `message` | `string` | Resolvida consoante o `lang`. É enumerável. |
| `cause` | `unknown` | Causa passada em `ErrorOptions`. Propriedade-padrão de `Error`. |

### Construtor [#constructor]

Quando `TMeta` não inclui `undefined`, o `meta` é obrigatório.

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

Quando `TMeta` é `undefined`, o `meta` pode ser omitido.

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

| Parâmetro | Tipo | Descrição |
| --------- | ---- | --------- |
| `meta` | `TMeta` | Informação auxiliar para gerar mensagens. |
| `message` | `string \| MessageFactory<TMeta>` | Mensagem por omissão para idiomas sem registo. As funções recebem o `meta`. |
| `options` | `ErrorOptions` | Opções compatíveis com o segundo argumento de `Error` (como `{ cause }`). |

### Ordem de resolução [#resolution-order]

1. Obtém o `lang` de `getGlobalConfig()` (quando não definido, `"en"`).
2. Executa, com o `meta`, a função registada para essa classe e esse idioma.
3. Sem registo, utiliza a mensagem por omissão.
4. Se existir `static prefix`, antepõe-no.

:::note
Os registos são por classe. Os do pai não são herdados. Registe cada classe.
:::

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

Regista funções de criação de mensagens por idioma.

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

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

| Parâmetro | Tipo | Descrição |
| --------- | ---- | --------- |
| `reference` | `I18nErrorBaseConstructor` | Classe que herda de `I18nErrorBase`. As que não herdam dão erro de tipo. |
| `message` | `string \| (meta) => string` | Mensagem a registar. O tipo de `meta` é inferido a partir da classe visada. |
| `lang` | `string \| Iterable<string>` | Idioma visado. Um único código ou um iterável (como um vetor). |

Voltar a registar a mesma classe e idioma substitui.

## Tipos [#types]

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

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

Restrição por omissão de `TMeta`. Objeto só de leitura com propriedades arbitrárias.

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

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

Tipo derivado do segundo argumento de `Error`. Permite passar `cause`.

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

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

Função que gera uma mensagem a partir de `meta`. Usada tanto na mensagem por omissão como nas registadas.

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

Sobrecargas de argumentos do construtor.

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

A forma abreviada sem `meta` só é permitida quando `TMeta` é `undefined`.

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

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

Tipo do primeiro argumento de `setErrorMessage`.

## Notas [#notes]

- O valor por omissão de `lang` é `"en"`. Mude-o com `setGlobalConfig({ lang })`.
- Sem normalização de códigos nem cadeia de recurso (ex.: `en-US` → `en`). Idiomas sem registo usam a mensagem por omissão.