Referência da API

Especificações de I18nErrorBase, setErrorMessage e dos tipos relacionados.

`I18nErrorBase`

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

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

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

Parâmetros de tipo

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

Propriedades estáticas

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

Propriedades de instância

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

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

new MyError(meta, message, options?)

Quando TMeta é undefined, o meta pode ser omitido.

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

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

`setErrorMessage`

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

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

`ErrorMeta`

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

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

`ErrorOptions`

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

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

Sobrecargas de argumentos do construtor.

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`

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

Tipo do primeiro argumento de setErrorMessage.

Notas

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.