@pedrohb/errors 0.0.0-stage → 1.0.0

package/dist/error-params-CR2parjT.d.mts

@@ -0,0 +1,387 @@
+//#region src/types/error-param-delimiters.d.ts
+/**
+ * Delimitadores de abertura e fechamento usados para identificar os
+ * placeholders em uma mensagem de erro (ex.: `{id}`). Também pode
+ * ser usado para tipar, em runtime, o objeto de delimitadores.
+ *
+ * Os parâmetros de tipo têm `string` como padrão, de modo que
+ * `ErrorParamDelimiters` sem argumentos serve como restrição genérica
+ * (`extends ErrorParamDelimiters`) aceitando quaisquer delimitadores. Para o
+ * par padrão `{` e `}`, informe os literais explicitamente.
+ *
+ * @template Open - Tipo literal do delimitador de abertura. Por padrão, `string`.
+ * @template Close - Tipo literal do delimitador de fechamento. Por padrão, `string`.
+ *
+ * @example
+ * ```ts
+ * const keys = { open: "{", close: "}" } as const satisfies ErrorParamDelimiters;
+ *
+ * const brackets: ErrorParamDelimiters<"[", "]"> = {
+ *   open: "[",
+ *   close: "]",
+ * };
+ * // Mensagem correspondente: "Usuário [id] não encontrado"
+ * ```
+ */
+type ErrorParamDelimiters<Open extends string = string, Close extends string = string> = Readonly<{
+  /** Delimitador que marca o início de um placeholder (ex.: `"{"`). */
+  open: Open;
+  /** Delimitador que marca o fim de um placeholder (ex.: `"}"`). */
+  close: Close;
+}>;
+//#endregion
+//#region src/functions/create-param-placeholder.d.ts
+/**
+ * Delimitadores padrão dos placeholders em mensagens de erro: `{` para abrir
+ * e `}` para fechar (ex.: `{id}`).
+ *
+ * Declarado com `as const`, então mantém os tipos literais `"{"` e `"}"`,
+ * o que permite derivar {@link DefaultParamDelimiters} a partir dele.
+ */
+declare const DEFAULT_PARAM_DELIMITERS: {
+  readonly open: "{";
+  readonly close: "}";
+};
+/**
+ * Tipo dos delimitadores padrão equivalente a
+ * `{ readonly open: "{"; readonly close: "}" }`.
+ *
+ * É usado como valor padrão de `Delimiters` em tipos como `ErrorParams`.
+ */
+type DefaultParamDelimiters = typeof DEFAULT_PARAM_DELIMITERS;
+/**
+ * Cria uma expressão regular global que localiza os placeholders de uma
+ * mensagem de erro com base nos delimitadores informados.
+ *
+ * Os delimitadores são escapados com {@link escapeRegExp}, então símbolos como
+ * `[`, `(` ou `$` são tratados como texto literal. Delimitadores com mais de
+ * um caractere (ex.: `{{` e `}}`) também são aceitos.
+ *
+ * Em cada correspondência o grupo de captura `1` contém o texto entre os
+ * delimitadores, exatamente como aparece na mensagem (sem aparar espaços).
+ * O conteúdo pode ocupar várias linhas, mas não pode conter os delimitadores
+ * de abertura ou de fechamento. Em casos como `{{id}}` a correspondência
+ * recai sobre o par mais interno (`{id}`). Placeholders vazios (ex.: `{}`)
+ * também correspondem com o grupo `1` igual a `""`.
+ *
+ * Cada chamada devolve uma nova instância de `RegExp`. Como ela usa a flag
+ * `g` que mantém estado em `lastIndex`, isso evita que usos diferentes
+ * compartilhem o mesmo estado.
+ *
+ * @param delimiters - Delimitadores `open` e `close` do placeholder. Por
+ * padrão, {@link DEFAULT_PARAM_DELIMITERS} (`{` e `}`).
+ * @returns Expressão regular global que corresponde a cada placeholder.
+ * @throws {InvalidParamDelimitersError} Se `open` ou `close` for uma string
+ * vazia.
+ *
+ * @example
+ * ```ts
+ * const regex = createParamPlaceholder();
+ *
+ * for (const match of "Usuário {id} não encontrado em {table}".matchAll(regex)) {
+ *   console.log(match[1]);
+ * }
+ * // "id"
+ * // "table"
+ *
+ * "Olá, {nome}!".replace(regex, (_, param) => `<${param}>`);
+ * // "Olá, <nome>!"
+ *
+ * // Delimitadores personalizados
+ * const brackets = createParamPlaceholder({ open: "[", close: "]" });
+ * "Rota [route] não encontrada".match(brackets); // ["[route]"]
+ *
+ * // Delimitadores vazios não são permitidos
+ * createParamPlaceholder({ open: "", close: "}" });
+ * // Lança InvalidParamDelimitersError
+ * ```
+ */
+declare function createParamPlaceholder(delimiters?: ErrorParamDelimiters): RegExp;
+//#endregion
+//#region src/types/error-descriptor.d.ts
+/**
+ * Descreve um erro do catálogo: um código identificador e a mensagem associada.
+ *
+ * A mensagem pode conter placeholders (ex.: `"Usuário {id} não encontrado"`),
+ * que são preenchidos com os parâmetros informados na criação do erro.
+ *
+ * @template Code - Tipo literal do código do erro. Por padrão, `string`.
+ * @template Message - Tipo literal da mensagem do erro. Por padrão, `string`.
+ *
+ * @example
+ * ```ts
+ * const USER_NOT_FOUND = {
+ *   code: "USER_NOT_FOUND",
+ *   message: "Usuário {id} não encontrado",
+ * } as const satisfies ErrorDescriptor;
+ * ```
+ */
+interface ErrorDescriptor<Code extends string = string, Message extends string = string> {
+  /** Código único que identifica o erro (ex.: `"USER_NOT_FOUND"`). */
+  readonly code: Code;
+  /** Mensagem do erro, podendo conter placeholders como `{id}`. */
+  readonly message: Message;
+}
+//#endregion
+//#region src/types/error-catalog.d.ts
+/**
+ * Catálogo de erros somente leitura, derivado de um objeto que associa cada
+ * código de erro à sua mensagem.
+ *
+ * Para cada entrada de `Definitions`, a chave vira o `code` e o valor vira a
+ * `message` de um {@link ErrorDescriptor}, preservando os tipos literais de
+ * ambos. Assim, `TEST_ERROR_CODES.USER_NOT_FOUND.code` tem o tipo `"USER_NOT_FOUND"`
+ * e `TEST_ERROR_CODES.USER_NOT_FOUND.message` tem o tipo literal da mensagem definida.
+ *
+ * Apenas chaves do tipo `string` são consideradas.
+ *
+ * @template Definitions - Objeto que mapeia códigos de erro para suas
+ * mensagens. Por padrão, `Record<string, string>`.
+ *
+ * @example
+ * ```ts
+ * type TEST_ERROR_CODES = ErrorCatalog<{
+ *   USER_NOT_FOUND: "Usuário {id} não encontrado";
+ *   INVALID_TOKEN: "Token inválido";
+ * }>;
+ * // {
+ * //   readonly USER_NOT_FOUND: ErrorDescriptor<"USER_NOT_FOUND", "Usuário {id} não encontrado">;
+ * //   readonly INVALID_TOKEN: ErrorDescriptor<"INVALID_TOKEN", "Token inválido">;
+ * // }
+ * ```
+ */
+type ErrorCatalog<Definitions extends Record<string, string> = Record<string, string>> = Readonly<{ [Code in keyof Definitions & string]: ErrorDescriptor<Code, Definitions[Code]>; }>;
+//#endregion
+//#region src/types/catalog-code.d.ts
+/**
+ * Extrai a união de todos os códigos de erro presentes em um catálogo.
+ *
+ * Percorre cada {@link ErrorDescriptor} do catálogo e coleta o tipo literal de
+ * sua propriedade `code`. Útil para tipar parâmetros que aceitam apenas
+ * códigos válidos de um catálogo específico.
+ *
+ * @template Catalog - Catálogo de erros a ser analisado. Por padrão,
+ * `ErrorCatalog`, caso em que o resultado é `string`.
+ *
+ * @example
+ * ```ts
+ * type TEST_ERROR_CODES = ErrorCatalog<{
+ *   USER_NOT_FOUND: "Usuário {id} não encontrado";
+ *   INVALID_TOKEN: "Token inválido";
+ * }>;
+ *
+ * type TestErrorCatalogCode = CatalogCode<TEST_ERROR_CODES>;
+ * // "USER_NOT_FOUND" | "INVALID_TOKEN"
+ * ```
+ */
+type CatalogCode<Catalog extends ErrorCatalog = ErrorCatalog> = Catalog[keyof Catalog]["code"];
+//#endregion
+//#region src/types/catalog-descriptor.d.ts
+/**
+ * Obtém o descritor de erro correspondente a um código específico de um
+ * catálogo.
+ *
+ * Busca em `Catalog` a entrada cujo `code` é `Code` e retorna o respectivo
+ * `ErrorDescriptor`, com `code` e `message` em seus tipos literais. Se `Code`
+ * for uma união de códigos, o resultado é a união dos descritores
+ * correspondentes. Se `Code` não for informado, o resultado é a união de todos
+ * os descritores do catálogo.
+ *
+ * @template Catalog - Catálogo de erros a ser consultado. Por padrão,
+ * `ErrorCatalog`.
+ * @template Code - Código (ou união de códigos) a ser buscado, restrito aos
+ * códigos existentes no catálogo (ver {@link CatalogCode}). Por padrão, todos
+ * os códigos do catálogo.
+ *
+ * @example
+ * ```ts
+ * type TEST_ERROR_CODES = ErrorCatalog<{
+ *   USER_NOT_FOUND: "Usuário {id} não encontrado";
+ *   INVALID_TOKEN: "Token inválido";
+ * }>;
+ *
+ * type A = CatalogDescriptor<TEST_ERROR_CODES, "USER_NOT_FOUND">;
+ * // ErrorDescriptor<"USER_NOT_FOUND", "Usuário {id} não encontrado">
+ *
+ * type B = CatalogDescriptor<TEST_ERROR_CODES, "USER_NOT_FOUND" | "INVALID_TOKEN">;
+ * // ErrorDescriptor<"USER_NOT_FOUND", ...> | ErrorDescriptor<"INVALID_TOKEN", ...>
+ *
+ * type C = CatalogDescriptor<TEST_ERROR_CODES>;
+ * // união de todos os descritores do catálogo
+ * ```
+ */
+type CatalogDescriptor<Catalog extends ErrorCatalog = ErrorCatalog, Code extends CatalogCode<Catalog> = CatalogCode<Catalog>> = Extract<Catalog[Code], {
+  code: Code;
+}>;
+//#endregion
+//#region src/types/extract-placeholders.d.ts
+/**
+ * Caracteres de espaço em branco reconhecidos pelos tipos utilitários deste módulo.
+ *
+ * Inclui espaço, tabulação, quebra de linha (`\n`) e retorno de carro (`\r`).
+ */
+type Whitespace = " " | "\t" | "\n" | "\r";
+/**
+ * Remove, em tempo de compilação, todos os espaços em branco no início e no fim
+ * de uma string literal. É o equivalente em nível de tipos a `String.prototype.trim()`.
+ *
+ * O tipo é recursivo: remove um caractere de espaço por vez do início e
+ * quando não há mais nenhum, do fim até restar apenas o conteúdo "limpo".
+ *
+ * @template T - Tipo string literal a ser aparado. Por padrão, `string`.
+ *
+ * @example
+ * ```ts
+ * type A = Trim<"  olá  ">;   // "olá"
+ * type B = Trim<"\n\tabc\r">; // "abc"
+ * type C = Trim<"sem-espaço">; // "sem-espaço"
+ * type D = Trim<string>;       // string
+ * ```
+ */
+type Trim<T extends string = string> = T extends `${Whitespace}${infer Rest}` ? Trim<Rest> : T extends `${infer Rest}${Whitespace}` ? Trim<Rest> : T;
+/**
+ * Extrai, em tempo de compilação, os nomes dos placeholders presentes em uma
+ * string de mensagem, retornando-os como uma união de string literals.
+ *
+ * Os delimitadores de abertura e fechamento são informados por meio de um
+ * objeto {@link ErrorParamDelimiters}. O conteúdo de cada placeholder é
+ * aparado com {@link Trim} e placeholders vazios (ex.: `{}` ou `{   }`) são
+ * ignorados.
+ *
+ * Se `Message` for o tipo genérico `string` (ou seja, não for um literal),
+ * não é possível inferir os placeholders e o resultado é `string`. Se a
+ * mensagem não contiver nenhum placeholder, o resultado é `never`.
+ *
+ *
+ * @template Message - Mensagem a ser analisada. Por padrão, `string`.
+ * @template Delimiters - Objeto com os delimitadores `open` e `close` do
+ * placeholder. Por padrão, {@link DefaultParamDelimiters}.
+ *
+ * @example
+ * ```ts
+ * type Keys = { readonly open: "{"; readonly close: "}" };
+ *
+ * type A = ExtractPlaceholders<"Olá, {nome}! Você tem {qtd} mensagens.", Keys>;
+ * // "nome" | "qtd"
+ *
+ * type B = ExtractPlaceholders<"Valor: { valor }", Keys>;
+ * // "valor" (espaços internos são removidos)
+ *
+ * type C = ExtractPlaceholders<"Sem placeholders", Keys>;
+ * // never
+ *
+ * type D = ExtractPlaceholders<"Olá, {}!", Keys>;
+ * // never (placeholder vazio é ignorado)
+ *
+ * type E = ExtractPlaceholders<
+ *   "Olá, [nome]!",
+ *   { readonly open: "["; readonly close: "]" }
+ * >;
+ * // "nome" (delimitadores personalizados)
+ *
+ * type F = ExtractPlaceholders<string, Keys>;
+ * // string (mensagem não literal)
+ * ```
+ */
+type ExtractPlaceholders<Message extends string = string, Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters> = string extends Message ? string : Message extends `${string}${Delimiters["open"]}${infer Param}${Delimiters["close"]}${infer Rest}` ? Trim<Param> extends "" ? ExtractPlaceholders<Rest, Delimiters> : Trim<Param> | ExtractPlaceholders<Rest, Delimiters> : never;
+//#endregion
+//#region src/types/params-from-message.d.ts
+/**
+ * Valores aceitos como parâmetros para preencher os placeholders de uma
+ * mensagem de erro.
+ *
+ * Restringe-se a tipos primitivos simples e serializáveis, o que evita
+ * objetos arbitrários e referências circulares nos parâmetros do erro.
+ */
+type ErrorParamValue = string | number | boolean | bigint | null;
+/**
+ * Deriva em tempo de compilação, o tipo do objeto de parâmetros exigido por
+ * uma mensagem com base nos placeholders presentes nela.
+ *
+ * Cada placeholder encontrado (via {@link ExtractPlaceholders}) vira uma
+ * propriedade obrigatória e somente leitura do tipo {@link ErrorParamValue}.
+ * Os delimitadores dos placeholders são informados por meio de um objeto
+ * {@link ErrorParamDelimiters}.
+ *
+ * - Se a mensagem **não** tiver placeholders o resultado é `never`, indicando
+ *   que nenhum parâmetro deve ser informado.
+ * - Se `Message` for o tipo genérico `string` (não literal), não é possível
+ *   inferir os placeholders e o resultado é um objeto com chaves `string`
+ *   arbitrárias, ou seja, `Readonly<Record<string, ErrorParamValue>>`.
+ *
+ * @template Message - Mensagem a ser analisada. Por padrão, `string`.
+ * @template Delimiters - Objeto com os delimitadores `open` e `close` do
+ * placeholder. Por padrão, {@link DefaultParamDelimiters}.
+ *
+ * @example
+ * ```ts
+ * type Keys = { readonly open: "{"; readonly close: "}" };
+ *
+ * type A = ParamsFromMessage<"Usuário {id} não encontrado em {table}", Keys>;
+ * // Readonly<{ id: ErrorParamValue; table: ErrorParamValue }>
+ *
+ * type B = ParamsFromMessage<"Algo deu errado", Keys>;
+ * // never (sem placeholders, sem parâmetros)
+ *
+ * type C = ParamsFromMessage<
+ *   "Falha em [resource]",
+ *   { readonly open: "["; readonly close: "]" }
+ * >;
+ * // Readonly<{ resource: ErrorParamValue }>
+ *
+ * type D = ParamsFromMessage<string, Keys>;
+ * // Readonly<Record<string, ErrorParamValue>>
+ * ```
+ */
+type ParamsFromMessage<Message extends string = string, Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters> = [ExtractPlaceholders<Message, Delimiters>] extends [never] ? never : Readonly<{ [K in ExtractPlaceholders<Message, Delimiters>]: ErrorParamValue; }>;
+//#endregion
+//#region src/types/error-params.d.ts
+/**
+ * Deriva em tempo de compilação, o tipo do objeto de parâmetros exigido para
+ * criar o erro de um código específico de um catálogo.
+ *
+ * Localiza o descritor do código em `Catalog` (via {@link CatalogDescriptor}),
+ * lê sua `message` e converte os placeholders encontrados em propriedades
+ * obrigatórias (via {@link ParamsFromMessage}). Os delimitadores dos
+ * placeholders são informados por meio de um objeto
+ * {@link ErrorParamDelimiters}.
+ *
+ * - Se a mensagem do código **não** tiver placeholders, o resultado é `never`,
+ *   indicando que nenhum parâmetro deve ser informado.
+ * - Se `Code` for uma união de códigos, o resultado exige os placeholders de
+ *   todas as mensagens correspondentes, e não apenas os de uma delas.
+ *
+ * @template Catalog - Catálogo de erros a ser consultado. Por padrão,
+ * `ErrorCatalog`.
+ * @template Code - Código (ou união de códigos) do erro, restrito aos códigos
+ * existentes no catálogo (ver {@link CatalogCode}). Por padrão, todos os
+ * códigos do catálogo.
+ * @template Delimiters - Objeto com os delimitadores `open` e `close` do
+ * placeholder. Por padrão, {@link DefaultParamDelimiters}.
+ *
+ * @example
+ * ```ts
+ * type TEST_ERROR_CODES = ErrorCatalog<{
+ *   USER_NOT_FOUND: "Usuário {id} não encontrado em {tabela}";
+ *   INVALID_TOKEN: "Token inválido";
+ *   ROUTE_NOT_FOUND: "Rota [rota] não encontrada";
+ * }>;
+ *
+ * type A = ErrorParams<TEST_ERROR_CODES, "USER_NOT_FOUND">;
+ * // Readonly<{ id: ErrorParamValue; tabela: ErrorParamValue }>
+ *
+ * type B = ErrorParams<TEST_ERROR_CODES, "INVALID_TOKEN">;
+ * // never (sem placeholders, sem parâmetros)
+ *
+ * type C = ErrorParams<
+ *   TEST_ERROR_CODES,
+ *   "ROUTE_NOT_FOUND",
+ *   { readonly open: "["; readonly close: "]" }
+ * >;
+ * // Readonly<{ rota: ErrorParamValue }> (delimitadores personalizados)
+ * ```
+ */
+type ErrorParams<Catalog extends ErrorCatalog = ErrorCatalog, Code extends CatalogCode<Catalog> = CatalogCode<Catalog>, Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters> = ParamsFromMessage<CatalogDescriptor<Catalog, Code>["message"], Delimiters>;
+//#endregion
+export { Trim as a, CatalogCode as c, DEFAULT_PARAM_DELIMITERS as d, DefaultParamDelimiters as f, ExtractPlaceholders as i, ErrorCatalog as l, ErrorParamDelimiters as m, ErrorParamValue as n, Whitespace as o, createParamPlaceholder as p, ParamsFromMessage as r, CatalogDescriptor as s, ErrorParams as t, ErrorDescriptor as u };
+//# sourceMappingURL=error-params-CR2parjT.d.mts.map

package/dist/errors/index.cjs

@@ -0,0 +1,6 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_invalid_param_delimiters_error = require("../invalid-param-delimiters-error-C6UxV7cK.cjs");
+const require_errors = require("../errors-TgPe2YUV.cjs");
+exports.EitherUnwrapError = require_errors.EitherUnwrapError;
+exports.InvalidErrorCode = require_errors.InvalidErrorCode;
+exports.InvalidParamDelimitersError = require_invalid_param_delimiters_error.InvalidParamDelimitersError;

package/dist/errors/index.d.cts

@@ -0,0 +1,115 @@
+//#region src/errors/either-unwrap-error.d.ts
+/**
+ * Erro lançado quando `unwrap()` é chamado em um `Err` ou `unwrapErr()` é
+ * chamado em um `Ok`, ou seja, quando se tenta extrair de um {@link Either}
+ * o valor da variante que ele não possui.
+ *
+ * O valor contido na variante realmente presente é anexado como `cause`
+ * (o valor de erro em `unwrap()` num `Err`; o valor de sucesso em
+ * `unwrapErr()` num `Ok`). Esse valor pode ser de qualquer tipo, não
+ * necessariamente um `Error`.
+ *
+ * O `name` do erro é o nome da classe concreta (`new.target.name`) e o
+ * protótipo é ajustado explicitamente para que `instanceof` funcione mesmo em
+ * subclasses e em alvos de compilação antigos.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   err<number, string>("falhou").unwrap();
+ * } catch (error) {
+ *   if (error instanceof EitherUnwrapError) {
+ *     error.message; // "Chamado unwrap() em Err."
+ *     error.cause;   // "falhou"
+ *   }
+ * }
+ * ```
+ */
+export declare class EitherUnwrapError extends Error {
+  /**
+   * Cria o erro de extração inválida de um `Either`.
+   *
+   * @param message - Mensagem do erro. Por padrão, uma mensagem genérica
+   * ("Chamado unwrap() ou unwrapErr() em resultado incompatível.").
+   * @param options - Opções padrão de `Error` como `cause` que normalmente
+   * carrega o valor contido no `Either`.
+   */
+  constructor(message?: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/errors/invalid-error-code.d.ts
+/**
+ * Erro lançado quando um código de erro não está em UPPER_SNAKE_CASE.
+ *
+ * Estende `TypeError` pois indica um valor de tipo ou formato inadequado.
+ * É lançado em tempo de execução por `defineErrorCatalog` complementando a
+ * validação feita em tempo de compilação por `ValidateErrorDefinitions`.
+ *
+ * A mensagem é gerada por {@link invalidCodeMessage} e o código inválido fica
+ * disponível na propriedade `code`.
+ *
+ * O `name` do erro é o nome da classe concreta (`new.target.name`) e o
+ * protótipo é ajustado explicitamente para que `instanceof` funcione mesmo em
+ * subclasses e em alvos de compilação antigos.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   defineErrorCatalog({ userNotFound: "Usuário não encontrado" });
+ * } catch (error) {
+ *   if (error instanceof InvalidErrorCode) {
+ *     error.code;    // "userNotFound"
+ *     error.message; // 'Código de erro inválido "userNotFound". Os códigos de erro devem usar UPPER_SNAKE_CASE.'
+ *   }
+ * }
+ * ```
+ */
+export declare class InvalidErrorCode extends TypeError {
+  /** Código de erro inválido que provocou a exceção. */
+  readonly code: string;
+  /**
+   * Cria o erro de código inválido.
+   *
+   * @param code - Código de erro que não está em UPPER_SNAKE_CASE.
+   * @param options - Opções padrão de `Error` como `cause`.
+   */
+  constructor(code: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/errors/invalid-param-delimiters-error.d.ts
+/**
+ * Erro lançado quando os delimitadores de placeholders são inválidos, ou
+ * seja, quando `open` ou `close` é uma string vazia.
+ *
+ * Estende `TypeError` pois indica um valor de formato inadequado. É lançado
+ * em tempo de execução por `createParamPlaceholder` e por consequência, por
+ * quem o utiliza como `interpolateErrorMessage` e o construtor de
+ * `BaseError`.
+ *
+ * O `name` do erro é o nome da classe concreta (`new.target.name`) e o
+ * protótipo é ajustado explicitamente para que `instanceof` funcione mesmo em
+ * subclasses e em alvos de compilação antigos.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   createParamPlaceholder({ open: "", close: "}" });
+ * } catch (error) {
+ *   if (error instanceof InvalidParamDelimitersError) {
+ *     error.message; // "Os delimitadores open e close não podem ser vazios."
+ *   }
+ * }
+ * ```
+ */
+export declare class InvalidParamDelimitersError extends TypeError {
+  /**
+   * Cria o erro de delimitadores inválidos.
+   *
+   * @param message - Mensagem do erro. Por padrão, "Os delimitadores open e
+   * close não podem ser vazios.".
+   * @param options - Opções padrão de `Error` como `cause`.
+   */
+  constructor(message?: string, options?: ErrorOptions);
+}
+//#endregion
+//# sourceMappingURL=index.d.cts.map

package/dist/errors/index.d.mts

@@ -0,0 +1,115 @@
+//#region src/errors/either-unwrap-error.d.ts
+/**
+ * Erro lançado quando `unwrap()` é chamado em um `Err` ou `unwrapErr()` é
+ * chamado em um `Ok`, ou seja, quando se tenta extrair de um {@link Either}
+ * o valor da variante que ele não possui.
+ *
+ * O valor contido na variante realmente presente é anexado como `cause`
+ * (o valor de erro em `unwrap()` num `Err`; o valor de sucesso em
+ * `unwrapErr()` num `Ok`). Esse valor pode ser de qualquer tipo, não
+ * necessariamente um `Error`.
+ *
+ * O `name` do erro é o nome da classe concreta (`new.target.name`) e o
+ * protótipo é ajustado explicitamente para que `instanceof` funcione mesmo em
+ * subclasses e em alvos de compilação antigos.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   err<number, string>("falhou").unwrap();
+ * } catch (error) {
+ *   if (error instanceof EitherUnwrapError) {
+ *     error.message; // "Chamado unwrap() em Err."
+ *     error.cause;   // "falhou"
+ *   }
+ * }
+ * ```
+ */
+export declare class EitherUnwrapError extends Error {
+  /**
+   * Cria o erro de extração inválida de um `Either`.
+   *
+   * @param message - Mensagem do erro. Por padrão, uma mensagem genérica
+   * ("Chamado unwrap() ou unwrapErr() em resultado incompatível.").
+   * @param options - Opções padrão de `Error` como `cause` que normalmente
+   * carrega o valor contido no `Either`.
+   */
+  constructor(message?: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/errors/invalid-error-code.d.ts
+/**
+ * Erro lançado quando um código de erro não está em UPPER_SNAKE_CASE.
+ *
+ * Estende `TypeError` pois indica um valor de tipo ou formato inadequado.
+ * É lançado em tempo de execução por `defineErrorCatalog` complementando a
+ * validação feita em tempo de compilação por `ValidateErrorDefinitions`.
+ *
+ * A mensagem é gerada por {@link invalidCodeMessage} e o código inválido fica
+ * disponível na propriedade `code`.
+ *
+ * O `name` do erro é o nome da classe concreta (`new.target.name`) e o
+ * protótipo é ajustado explicitamente para que `instanceof` funcione mesmo em
+ * subclasses e em alvos de compilação antigos.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   defineErrorCatalog({ userNotFound: "Usuário não encontrado" });
+ * } catch (error) {
+ *   if (error instanceof InvalidErrorCode) {
+ *     error.code;    // "userNotFound"
+ *     error.message; // 'Código de erro inválido "userNotFound". Os códigos de erro devem usar UPPER_SNAKE_CASE.'
+ *   }
+ * }
+ * ```
+ */
+export declare class InvalidErrorCode extends TypeError {
+  /** Código de erro inválido que provocou a exceção. */
+  readonly code: string;
+  /**
+   * Cria o erro de código inválido.
+   *
+   * @param code - Código de erro que não está em UPPER_SNAKE_CASE.
+   * @param options - Opções padrão de `Error` como `cause`.
+   */
+  constructor(code: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/errors/invalid-param-delimiters-error.d.ts
+/**
+ * Erro lançado quando os delimitadores de placeholders são inválidos, ou
+ * seja, quando `open` ou `close` é uma string vazia.
+ *
+ * Estende `TypeError` pois indica um valor de formato inadequado. É lançado
+ * em tempo de execução por `createParamPlaceholder` e por consequência, por
+ * quem o utiliza como `interpolateErrorMessage` e o construtor de
+ * `BaseError`.
+ *
+ * O `name` do erro é o nome da classe concreta (`new.target.name`) e o
+ * protótipo é ajustado explicitamente para que `instanceof` funcione mesmo em
+ * subclasses e em alvos de compilação antigos.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   createParamPlaceholder({ open: "", close: "}" });
+ * } catch (error) {
+ *   if (error instanceof InvalidParamDelimitersError) {
+ *     error.message; // "Os delimitadores open e close não podem ser vazios."
+ *   }
+ * }
+ * ```
+ */
+export declare class InvalidParamDelimitersError extends TypeError {
+  /**
+   * Cria o erro de delimitadores inválidos.
+   *
+   * @param message - Mensagem do erro. Por padrão, "Os delimitadores open e
+   * close não podem ser vazios.".
+   * @param options - Opções padrão de `Error` como `cause`.
+   */
+  constructor(message?: string, options?: ErrorOptions);
+}
+//#endregion
+//# sourceMappingURL=index.d.mts.map

package/dist/errors/index.mjs

@@ -0,0 +1,3 @@
+import { t as InvalidParamDelimitersError } from "../invalid-param-delimiters-error-BFxlVXp3.mjs";
+import { n as InvalidErrorCode, t as EitherUnwrapError } from "../errors-DrDL51y9.mjs";
+export { EitherUnwrapError, InvalidErrorCode, InvalidParamDelimitersError };