---
title: Riferimento API
description: Specifiche di I18nErrorBase, setErrorMessage e dei tipi correlati.
---

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

Classe base per estendere `Error`. `message` è risolto in base a `lang`.

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

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

### Parametri di tipo [#type-params]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `TMeta` | `ErrorMeta \| undefined` | `ErrorMeta \| undefined` | Il tipo di `meta`. Se non usato, specificare `undefined`. |

### Proprietà statiche [#static-props]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `prefix?` | `string` | `undefined` | Anteposto all'inizio del messaggio risolto. |

### Proprietà di istanza [#instance-props]

| Prop | Type | Description |
| ---- | ---- | ----------- |
| `meta` | `TMeta` | Informazioni aggiuntive del costruttore. Leggibili e scrivibili. |
| `message` | `string` | Risolto in base a `lang`. Enumerabile. |
| `cause` | `unknown` | Causa passata tramite `ErrorOptions`. Proprietà standard di `Error`. |

### Costruttore [#constructor]

Quando `TMeta` non include `undefined`, `meta` è obbligatorio.

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

Quando `TMeta` è `undefined`, `meta` può essere omesso.

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

| Parametro | Tipo | Descrizione |
| --------- | ---- | ----------- |
| `meta` | `TMeta` | Informazioni aggiuntive per generare i messaggi. |
| `message` | `string \| MessageFactory<TMeta>` | Messaggio predefinito per le lingue senza registrazione. Le funzioni ricevono `meta`. |
| `options` | `ErrorOptions` | Opzioni compatibili con il secondo argomento di `Error` (come `{ cause }`). |

### Ordine di risoluzione [#resolution-order]

1. Ottiene `lang` da `getGlobalConfig()` (se non impostato, `"en"`).
2. Esegue con `meta` la funzione registrata per quella classe e quella lingua.
3. Se non registrata, usa il messaggio predefinito.
4. Se esiste uno `static prefix`, lo antepone.

:::note
Le registrazioni sono per classe. Quelle del padre non sono ereditate. Registrare ogni classe.
:::

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

Registra le funzioni di creazione dei messaggi per lingua.

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

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

| Parametro | Tipo | Descrizione |
| --------- | ---- | ----------- |
| `reference` | `I18nErrorBaseConstructor` | La classe che estende `I18nErrorBase`. Le altre causano un errore di tipo. |
| `message` | `string \| (meta) => string` | Il messaggio da registrare. Il tipo di `meta` è inferito dalla classe di destinazione. |
| `lang` | `string \| Iterable<string>` | La lingua di destinazione. Un singolo codice o un iterabile (come un array). |

La registrazione ripetuta per la stessa classe e lingua sovrascrive.

## Tipi [#types]

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

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

Il vincolo predefinito di `TMeta`. Oggetto di sola lettura con proprietà arbitrarie.

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

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

Tipo derivato dal secondo argomento di `Error`. Permette di passare `cause`.

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

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

Funzione che genera un messaggio da `meta`. Usata sia per il predefinito sia per i registrati.

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

Overload degli argomenti del costruttore.

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

La forma abbreviata senza `meta` è consentita solo quando `TMeta` è `undefined`.

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

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

Il tipo del primo argomento di `setErrorMessage`.

## Note aggiuntive [#notes]

- Il valore predefinito di `lang` è `"en"`. Cambiarlo con `setGlobalConfig({ lang })`.
- Nessuna normalizzazione dei codici né catena di ripiego (ad es. `en-US` → `en`). Le lingue non registrate usano il messaggio predefinito.