@pedrohb/errors 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Henrique Bergamo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @pedrohb/errors
+
+Um sistema de erros tipado para aplicações TypeScript. Defina catálogos imutáveis de códigos, associe mensagens parametrizadas a erros e serialize causas com segurança.
+
+## Instalação
+
+```sh
+pnpm add @pedrohb/errors
+```
+
+## Catálogo e erros tipados
+
+```ts
+import { BaseError, defineErrorCatalog } from "@pedrohb/errors";
+
+const errors = defineErrorCatalog({
+  USER_NOT_FOUND: "Usuário {userId} não encontrado.",
+  INVALID_CREDENTIALS: "Credenciais inválidas.",
+});
+
+class UserNotFoundError extends BaseError<typeof errors, "USER_NOT_FOUND"> {
+  public constructor(userId: string, options?: ErrorOptions) {
+    super(errors.USER_NOT_FOUND, {
+      ...options,
+      params: { userId },
+    });
+  }
+}
+
+const error = new UserNotFoundError("user-123");
+console.log(error.code, error.message);
+```
+
+Os códigos devem estar em `UPPER_SNAKE_CASE`. Os placeholders entre chaves são inferidos pelo TypeScript e usados para tipar os parâmetros da mensagem.
+
+## Serialização
+
+`BaseError` preserva `code`, `message` e parâmetros. `serialize()` retorna uma representação apropriada para logs e transporte; a pilha é omitida por padrão e pode ser incluída chamando `serialize(true)`. Causas nativas, erros da biblioteca, datas, valores não serializáveis por JSON e referências circulares são tratadas pela serialização.
+
+## Resultado `Either`
+
+O pacote também exporta `Either`, `Ok`, `Err`, `ok` e `err` para representar resultados de sucesso ou falha sem lançar exceções. Os métodos `map`, `mapErr`, `flatMap`, `orElse` e `match` permitem compor e consumir esses resultados.
+
+## Imports por subpath
+
+```ts
+import { InvalidErrorCode } from "@pedrohb/errors/errors";
+import { serializeBaseError } from "@pedrohb/errors/functions";
+import type { ErrorCatalog } from "@pedrohb/errors/types";
+```
+
+O pacote fornece formatos ESM e CommonJS, com declarações TypeScript correspondentes.

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

@@ -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.cts.map