@pedrohb/errors 0.0.0-stage → 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,510 @@
+import { EitherUnwrapError, InvalidErrorCode, InvalidParamDelimitersError } from "./errors/index.mjs";
+import { a as Trim, c as CatalogCode, d as DEFAULT_PARAM_DELIMITERS, f as DefaultParamDelimiters, i as ExtractPlaceholders, l as ErrorCatalog, m as ErrorParamDelimiters, n as ErrorParamValue, o as Whitespace, p as createParamPlaceholder, r as ParamsFromMessage, s as CatalogDescriptor, t as ErrorParams, u as ErrorDescriptor } from "./error-params-CR2parjT.mjs";
+import { a as CIRCULAR_MARKER, c as BASE_ERROR_BRAND, d as BaseErrorOptions, f as BaseErrorOptionsArgs, i as serializeBaseError, l as isBaseError, n as serializeNativeError, o as SeenReferences, p as escapeRegExp, r as SerializedBaseError, s as serializeCauseError, t as SerializedNativeError, u as BaseError } from "./index-B4tdSdCF.mjs";
+import { AlphaNumeric, Digit, InvalidCodeMessage, IsUpperSnakeCase, Segment, Tail, UpperLetter, ValidateErrorDefinitions } from "./types/index.mjs";
+//#region src/define-error-catalog.d.ts
+/**
+ * Cria um catálogo de erros imutável a partir de um objeto que associa cada
+ * código de erro à sua mensagem.
+ *
+ * Para cada entrada de `definitions` gera um {@link ErrorDescriptor} com
+ * `code` e `message` congelado com `Object.freeze`. O próprio catálogo
+ * retornado também é congelado, de modo que nem o catálogo nem seus
+ * descritores podem ser alterados depois de criados.
+ *
+ * A validação ocorre em duas camadas:
+ * - em tempo de compilação via {@link ValidateErrorDefinitions}: códigos fora
+ *   de UPPER_SNAKE_CASE geram um erro de tipo com uma mensagem explicativa;
+ * - em tempo de execução via {@link isUpperSnakeCase}: códigos inválidos
+ *   lançam {@link InvalidErrorCode}, o que protege contra definições que
+ *   escapem da checagem de tipos (ex.: objetos tipados como `any` ou
+ *   `Record<string, string>`).
+ *
+ * O parâmetro de tipo `T` é declarado como `const`, o que preserva os tipos
+ * literais dos códigos e das mensagens sem a necessidade de `as const` na
+ * chamada.
+ *
+ * @template Codes - Objeto que mapeia códigos de erro para suas mensagens.
+ * @param definitions - Definições do catálogo: chaves são os códigos em
+ * UPPER_SNAKE_CASE.
+ * @returns Catálogo de erros somente leitura com um descritor para cada
+ * código informado.
+ * @throws {InvalidErrorCode} Se algum código não estiver em UPPER_SNAKE_CASE.
+ *
+ * @example
+ * ```ts
+ * const TEST_ERROR_CODES = defineErrorCatalog({
+ *   USER_NOT_FOUND: "Usuário {id} não encontrado",
+ *   INVALID_TOKEN: "Token inválido",
+ * });
+ *
+ * TEST_ERROR_CODES.USER_NOT_FOUND.code;    // "USER_NOT_FOUND"
+ * TEST_ERROR_CODES.USER_NOT_FOUND.message; // "Usuário {id} não encontrado"
+ *
+ * // Erro de compilação (e de execução): código fora de UPPER_SNAKE_CASE
+ * defineErrorCatalog({
+ *   userNotFound: "Usuário não encontrado",
+ * });
+ * // Lança InvalidErrorCode
+ * ```
+ */
+export declare function defineErrorCatalog<const Codes extends Record<string, string>>(definitions: ValidateErrorDefinitions<Codes>): ErrorCatalog<Codes>;
+//#endregion
+//#region src/either.d.ts
+/**
+ * Representa o resultado de uma operação que pode ter sucesso (`Ok`) ou
+ * falhar (`Err`), tornando o erro parte explícita do tipo de retorno em vez
+ * de depender de exceções.
+ *
+ * Um `Either<O, E>` é sempre uma instância de {@link Ok} que carrega um
+ * valor de sucesso do tipo `O`, ou de {@link Err} que carrega um valor de
+ * erro do tipo `E`. Use {@link ok} e {@link err} para criá-los.
+ *
+ * Os métodos {@link Either.map}, {@link Either.mapErr}, {@link Either.flatMap}
+ * e {@link Either.orElse} retornam um novo `Either` e não alteram o original.
+ * Para tratar os dois casos use {@link Either.match}, ou os type guards
+ * {@link Either.isOk} e {@link Either.isErr}.
+ *
+ * @template O - Tipo do valor de sucesso.
+ * @template E - Tipo do valor de erro.
+ *
+ * @example
+ * ```ts
+ * function toDivide(a: number, b: number): Either<number, string> {
+ *   return b === 0 ? err("Divisão por zero") : ok(a / b);
+ * }
+ *
+ * const message = toDivide(10, 2)
+ *   .map((resultado) => resultado * 3)
+ *   .match({
+ *     onOk: (valor) => `Resultado: ${valor}`,
+ *     onErr: (erro) => `Falha: ${erro}`,
+ *   });
+ * // "Resultado: 15"
+ * ```
+ */
+export declare abstract class Either<O, E> {
+  /** Discriminante da variante: `"Ok"` para sucesso e `"Err"` para erro. */
+  abstract readonly tag: "Ok" | "Err";
+  /**
+   * Retorna o valor de sucesso.
+   *
+   * @returns O valor contido em `Ok`.
+   * @throws {EitherUnwrapError} Se for um `Err`. A `cause` do erro é o valor
+   * de erro contido.
+   */
+  abstract unwrap(): O;
+  /**
+   * Retorna o valor de erro.
+   *
+   * @returns O valor contido em `Err`.
+   * @throws {EitherUnwrapError} Se for um `Ok`. A `cause` do erro é o valor
+   * de sucesso contido.
+   */
+  abstract unwrapErr(): E;
+  /**
+   * Verifica se é um `Ok` funcionando como type guard.
+   *
+   * @returns `true` se for `Ok` (restringindo o tipo para {@link Ok});
+   * caso contrário, `false`.
+   */
+  abstract isOk(): this is Ok<O, E>;
+  /**
+   * Verifica se é um `Err` funcionando como type guard.
+   *
+   * @returns `true` se for `Err` (restringindo o tipo para {@link Err});
+   * caso contrário, `false`.
+   */
+  abstract isErr(): this is Err<O, E>;
+  /**
+   * Transforma o valor de sucesso mantendo o erro intacto.
+   *
+   * Se for `Ok` aplica `fn` ao valor e retorna um novo `Ok` com o resultado.
+   * Se for `Err` `fn` não é chamada e um novo `Err` com o mesmo erro é
+   * retornado. Exceções lançadas por `fn` não são capturadas.
+   *
+   * @template O2 - Tipo do novo valor de sucesso.
+   * @param fn - Função que converte o valor de sucesso.
+   * @returns Um `Either` com o valor transformado ou o erro original.
+   *
+   * @example
+   * ```ts
+   * ok<number, string>(2).map((n) => n * 2).unwrap(); // 4
+   * err<number, string>("falhou").map((n) => n * 2).unwrapErr(); // "falhou"
+   * ```
+   */
+  map<O2>(fn: (value: O) => O2): Either<O2, E>;
+  /**
+   * Transforma o valor de erro mantendo o sucesso intacto.
+   *
+   * Se for `Err` aplica `fn` ao erro e retorna um novo `Err` com o resultado.
+   * Se for `Ok` `fn` não é chamada e um novo `Ok` com o mesmo valor é
+   * retornado. Exceções lançadas por `fn` não são capturadas.
+   *
+   * @template E2 - Tipo do novo valor de erro.
+   * @param fn - Função que converte o valor de erro.
+   * @returns Um `Either` com o erro transformado ou o valor original.
+   *
+   * @example
+   * ```ts
+   * err<number, string>("falhou").mapErr((e) => e.length).unwrapErr(); // 7
+   * ok<number, string>(1).mapErr((e) => e.length).unwrap(); // 1
+   * ```
+   */
+  mapErr<E2>(fn: (value: E) => E2): Either<O, E2>;
+  /**
+   * Encadeia uma operação que também retorna um `Either` usada quando o
+   * próximo passo também pode falhar.
+   *
+   * Se for `Ok`, retorna diretamente o `Either` produzido por `fn` (sem
+   * aninhamento). Se for `Err` `fn` não é chamada e o erro é propagado.
+   * O tipo de erro resultante é a união `E | E2`. Exceções lançadas por `fn`
+   * não são capturadas.
+   *
+   * @template O2 - Tipo do valor de sucesso retornado por `fn`.
+   * @template E2 - Tipo do valor de erro retornado por `fn`.
+   * @param fn - Função que recebe o valor de sucesso e retorna um `Either`.
+   * @returns O `Either` retornado por `fn`, ou o erro original.
+   *
+   * @example
+   * ```ts
+   * const forNumber = (s: string): Either<number, string> => {
+   *   const n = Number(s);
+   *   return Number.isNaN(n) ? err("Não é número") : ok(n);
+   * };
+   *
+   * ok<string, string>("42").flatMap(forNumber).unwrap(); // 42
+   * ok<string, string>("abc").flatMap(forNumber).unwrapErr(); // "Não é número"
+   * ```
+   */
+  flatMap<O2, E2>(fn: (value: O) => Either<O2, E2>): Either<O2, E | E2>;
+  /**
+   * Tenta se recuperar de um erro encadeando uma operação alternativa que
+   * também retorna um `Either`. É o oposto de {@link Either.flatMap}.
+   *
+   * Se for `Err` retorna diretamente o `Either` produzido por `fn`. Se for
+   * `Ok` `fn` não é chamada e o valor é mantido. O tipo de sucesso
+   * resultante é a união `O | O2`. Exceções lançadas por `fn` não são
+   * capturadas.
+   *
+   * @template O2 - Tipo do valor de sucesso retornado por `fn`.
+   * @template E2 - Tipo do valor de erro retornado por `fn`.
+   * @param fn - Função que recebe o valor de erro e retorna um `Either`.
+   * @returns O `Either` retornado por `fn`, ou o valor de sucesso original.
+   *
+   * @example
+   * ```ts
+   * err<number, string>("falhou").orElse(() => ok(0)).unwrap(); // 0
+   * ok<number, string>(5).orElse(() => ok(0)).unwrap(); // 5
+   * ```
+   */
+  orElse<O2, E2>(fn: (value: E) => Either<O2, E2>): Either<O | O2, E2>;
+  /**
+   * Trata os dois casos e produz um único valor chamando o handler da
+   * variante correspondente.
+   *
+   * @template R - Tipo do valor retornado pelos handlers.
+   * @param handlers - Objeto com `onOk` chamado com o valor de sucesso e
+   * `onErr` chamado com o valor de erro.
+   * @returns O resultado do handler chamado.
+   *
+   * @example
+   * ```ts
+   * const texto = resultado.match({
+   *   onOk: (valor) => `Sucesso: ${valor}`,
+   *   onErr: (erro) => `Erro: ${erro}`,
+   * });
+   * ```
+   */
+  match<R>(handlers: Readonly<{
+    onOk(value: O): R;
+    onErr(value: E): R;
+  }>): R;
+}
+/**
+ * Variante de sucesso de {@link Either} que carrega um valor do tipo `O`.
+ *
+ * O construtor é `protected`; para criar uma instância use {@link Ok.create}
+ * ou a função {@link ok}.
+ *
+ * @template O - Tipo do valor de sucesso. Por padrão, `never`.
+ * @template E - Tipo do valor de erro usado apenas para compatibilidade com
+ * {@link Either}. Por padrão, `never`.
+ */
+export declare class Ok<O = never, E = never> extends Either<O, E> {
+  /** Discriminante da variante sempre `"Ok"`. */
+  readonly tag: "Ok";
+  /** Valor de sucesso armazenado. */
+  private readonly value;
+  /**
+   * @param value - Valor de sucesso a ser armazenado.
+   */
+  protected constructor(value: O);
+  /**
+   * Retorna o valor de sucesso armazenado.
+   *
+   * @returns O valor contido.
+   */
+  unwrap(): O;
+  /**
+   * Sempre lança um erro pois um `Ok` não possui valor de erro.
+   *
+   * @throws {EitherUnwrapError} Sempre. A `cause` é o valor de sucesso contido.
+   */
+  unwrapErr(): E;
+  /** @returns Sempre `true`. */
+  isOk(): this is Ok<O, E>;
+  /** @returns Sempre `false`. */
+  isErr(): this is Err<O, E>;
+  /**
+   * Cria um `Ok` com o valor informado.
+   *
+   * @template O - Tipo do valor de sucesso. Por padrão, `never`.
+   * @template E - Tipo do valor de erro. Por padrão, `never`.
+   * @param value - Valor de sucesso.
+   * @returns Uma nova instância de `Ok`.
+   */
+  static create<O = never, E = never>(value: O): Ok<O, E>;
+}
+/**
+ * Variante de erro de {@link Either} que carrega um valor do tipo `E`.
+ *
+ * O construtor é `protected`; para criar uma instância use {@link Err.create}
+ * ou a função {@link err}.
+ *
+ * @template O - Tipo do valor de sucesso usado apenas para compatibilidade
+ * com {@link Either}. Por padrão, `never`.
+ * @template E - Tipo do valor de erro. Por padrão, `never`.
+ */
+export declare class Err<O = never, E = never> extends Either<O, E> {
+  /** Discriminante da variante sempre `"Err"`. */
+  readonly tag: "Err";
+  /** Valor de erro armazenado. */
+  private readonly value;
+  /**
+   * @param value - Valor de erro a ser armazenado.
+   */
+  protected constructor(value: E);
+  /**
+   * Sempre lança um erro pois um `Err` não possui valor de sucesso.
+   *
+   * @throws {EitherUnwrapError} Sempre. A `cause` é o valor de erro contido.
+   */
+  unwrap(): O;
+  /**
+   * Retorna o valor de erro armazenado.
+   *
+   * @returns O valor contido.
+   */
+  unwrapErr(): E;
+  /** @returns Sempre `false`. */
+  isOk(): this is Ok<O, E>;
+  /** @returns Sempre `true`. */
+  isErr(): this is Err<O, E>;
+  /**
+   * Cria um `Err` com o valor informado.
+   *
+   * @template O - Tipo do valor de sucesso. Por padrão, `never`.
+   * @template E - Tipo do valor de erro. Por padrão, `never`.
+   * @param value - Valor de erro.
+   * @returns Uma nova instância de `Err`.
+   */
+  static create<O = never, E = never>(value: E): Err<O, E>;
+}
+/**
+ * Cria um {@link Either} de sucesso (`Ok`) com o valor informado.
+ *
+ * O retorno é tipado como `Either<O, E>` e não como `Ok` para que possa ser
+ * usado onde se espera qualquer variante. Como `E` não pode ser inferido a
+ * partir do argumento, informe-o explicitamente quando necessário.
+ *
+ * @template O - Tipo do valor de sucesso. Por padrão, `never`.
+ * @template E - Tipo do valor de erro. Por padrão, `never`.
+ * @param value - Valor de sucesso.
+ * @returns Um `Either` que é um `Ok` contendo `value`.
+ *
+ * @example
+ * ```ts
+ * const result = ok<number, string>(42);
+ * result.isOk();   // true
+ * result.unwrap(); // 42
+ * ```
+ */
+export declare function ok<O = never, E = never>(value: O): Either<O, E>;
+/**
+ * Cria um {@link Either} de erro (`Err`) com o valor informado.
+ *
+ * O retorno é tipado como `Either<O, E>` e não como `Err` para que possa ser
+ * usado onde se espera qualquer variante. Como `O` não pode ser inferido a
+ * partir do argumento, informe-o explicitamente quando necessário.
+ *
+ * @template O - Tipo do valor de sucesso. Por padrão, `never`.
+ * @template E - Tipo do valor de erro. Por padrão, `never`.
+ * @param value - Valor de erro.
+ * @returns Um `Either` que é um `Err` contendo `value`.
+ *
+ * @example
+ * ```ts
+ * const result = err<number, string>("Algo deu errado");
+ * result.isErr();      // true
+ * result.unwrapErr();  // "Algo deu errado"
+ * ```
+ */
+export declare function err<O = never, E = never>(value: E): Either<O, E>;
+//#endregion
+//#region src/interpolate-error-message.d.ts
+/**
+ * Deriva, em tempo de compilação a lista de argumentos extras exigida para
+ * interpolar uma mensagem de erro.
+ *
+ * - Se a mensagem **não** tiver placeholders o resultado é uma tupla vazia
+ *   (`[]`), ou seja, nenhum argumento adicional deve ser passado.
+ * - Se tiver placeholders o resultado é uma tupla com um único argumento
+ *   obrigatório, `params` do tipo {@link ParamsFromMessage}.
+ *
+ * É pensado para ser usado como tipo de parâmetro rest (`...args`) de modo
+ * que o objeto de parâmetros seja exigido apenas quando necessário.
+ *
+ * @template Message - Mensagem a ser analisada.
+ * @template Delimiters - Objeto com os delimitadores `open` e `close` do
+ * placeholder. Por padrão, {@link DefaultParamDelimiters}.
+ *
+ * @example
+ * ```ts
+ * type A = ErrorMessageArgs<"Usuário {id} não encontrado">;
+ * // [params: Readonly<{ id: ErrorParamValue }>]
+ *
+ * type B = ErrorMessageArgs<"Token inválido">;
+ * // []
+ *
+ * type C = ErrorMessageArgs<
+ *   "Rota [route] não encontrada",
+ *   { readonly open: "["; readonly close: "]" }
+ * >;
+ * // [params: Readonly<{ route: ErrorParamValue }>]
+ * ```
+ */
+export type ErrorMessageArgs<Message extends string, Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters> = [ParamsFromMessage<Message, Delimiters>] extends [never] ? [] : [params: ParamsFromMessage<Message, Delimiters>];
+/**
+ * Interpola os parâmetros informados na mensagem de um descritor de erro
+ * substituindo cada placeholder pelo valor correspondente.
+ *
+ * Os placeholders são localizados com {@link createParamPlaceholder} a partir
+ * dos delimitadores informados. O nome de cada placeholder é aparado
+ * (`{ id }` equivale a `{id}`) e o valor é convertido para texto com `String`.
+ *
+ * O placeholder é mantido exatamente como está na mensagem (sem substituição)
+ * quando:
+ * - o nome é vazio (ex.: `{}` ou `{   }`);
+ * - o nome não existe como propriedade própria de `params`.
+ *
+ * O objeto de parâmetros é exigido ou omitido conforme a mensagem via
+ * {@link ErrorMessageArgs}: mensagens sem placeholders não aceitam `params` e
+ * mensagens com placeholders exigem todos eles.
+ *
+ * @template Descriptor - Tipo do descritor de erro cuja `message` define os
+ * parâmetros exigidos.
+ * @template Delimiters - Tipo dos delimitadores dos placeholders. Por padrão,
+ * {@link DefaultParamDelimiters}.
+ * @param descriptor - Descritor de erro cuja mensagem será interpolada.
+ * @param delimiters - Delimitadores `open` e `close` dos placeholders.
+ * @param args - Objeto `params` com os valores dos placeholders exigido
+ * apenas se a mensagem tiver placeholders.
+ * @returns A mensagem com os placeholders substituídos.
+ * @throws {InvalidParamDelimitersError} Se `open` ou `close` for uma string
+ * vazia (lançado por {@link createParamPlaceholder}).
+ *
+ * @example
+ * ```ts
+ * const keys = { open: "{", close: "}" } as const;
+ *
+ * const USER_NOT_FOUND = {
+ *   code: "USER_NOT_FOUND",
+ *   message: "Usuário {id} não encontrado em {table}",
+ * } as const satisfies ErrorDescriptor;
+ *
+ * interpolateErrorMessage(USER_NOT_FOUND, keys, {
+ *   id: 42,
+ *   table: "users",
+ * });
+ * // "Usuário 42 não encontrado em users"
+ *
+ * const INVALID_TOKEN = {
+ *   code: "INVALID_TOKEN",
+ *   message: "Token inválido",
+ * } as const satisfies ErrorDescriptor;
+ *
+ * interpolateErrorMessage(INVALID_TOKEN, keys);
+ * // "Token inválido" (sem params)
+ *
+ * // Delimitadores personalizados
+ * const ROUTE_NOT_FOUND = {
+ *   code: "ROUTE_NOT_FOUND",
+ *   message: "Rota [route] não encontrada",
+ * } as const satisfies ErrorDescriptor;
+ *
+ * interpolateErrorMessage(
+ *   ROUTE_NOT_FOUND,
+ *   { open: "[", close: "]" } as const,
+ *   { route: "/home" },
+ * );
+ * // "Rota /home não encontrada"
+ * ```
+ */
+export declare function interpolateErrorMessage<Descriptor extends ErrorDescriptor, Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters>(descriptor: Descriptor, delimiters: Delimiters, ...args: ErrorMessageArgs<Descriptor["message"], Delimiters>): string;
+//#endregion
+//#region src/upper-snake-case.d.ts
+/**
+ * Expressão regular que valida códigos em UPPER_SNAKE_CASE em tempo de
+ * execução.
+ *
+ * Regras (espelham o tipo {@link IsUpperSnakeCase}):
+ * - deve começar com uma letra maiúscula (`A-Z`);
+ * - pode conter letras maiúsculas, dígitos e `_`;
+ * - `_` só pode aparecer entre caracteres alfanuméricos, ou seja, não pode
+ *   estar no início nem no fim e não pode ser repetido em sequência.
+ */
+export declare const UPPER_SNAKE_CASE: RegExp;
+/**
+ * Verifica em tempo de execução, se uma string está em UPPER_SNAKE_CASE.
+ *
+ * É o equivalente em runtime do tipo {@link IsUpperSnakeCase}, usando a
+ * expressão regular {@link UPPER_SNAKE_CASE}.
+ *
+ * @param value - String a ser verificada.
+ * @returns `true` se `value` estiver em UPPER_SNAKE_CASE; caso contrário,
+ * `false`.
+ *
+ * @example
+ * ```ts
+ * isUpperSnakeCase("USER_NOT_FOUND"); // true
+ * isUpperSnakeCase("ERROR_404");      // true
+ * isUpperSnakeCase("userNotFound");   // false
+ * isUpperSnakeCase("_USER");          // false
+ * isUpperSnakeCase("USER__NOT");      // false
+ * isUpperSnakeCase("1ERROR");         // false
+ * ```
+ */
+export declare function isUpperSnakeCase(value: string): boolean;
+/**
+ * Monta a mensagem de erro exibida quando um código não está em
+ * UPPER_SNAKE_CASE.
+ *
+ * O retorno é tipado como {@link InvalidCodeMessage}, de modo que o texto em
+ * runtime corresponde exatamente ao tipo literal usado na validação em tempo
+ * de compilação.
+ *
+ * @template Code - Tipo literal do código inválido.
+ * @param code - Código de erro inválido a ser incluído na mensagem.
+ * @returns Mensagem descrevendo o código inválido e o formato esperado.
+ *
+ * @example
+ * ```ts
+ * invalidCodeMessage("userNotFound");
+ * // 'Código de erro inválido "userNotFound". Os códigos de erro devem usar UPPER_SNAKE_CASE.'
+ * ```
+ */
+export declare function invalidCodeMessage<Code extends string>(code: Code): InvalidCodeMessage<Code>;
+//#endregion
+export { AlphaNumeric, BASE_ERROR_BRAND, BaseError, BaseErrorOptions, BaseErrorOptionsArgs, CIRCULAR_MARKER, CatalogCode, CatalogDescriptor, DEFAULT_PARAM_DELIMITERS, DefaultParamDelimiters, Digit, EitherUnwrapError, ErrorCatalog, ErrorDescriptor, ErrorParamDelimiters, ErrorParamValue, ErrorParams, ExtractPlaceholders, InvalidCodeMessage, InvalidErrorCode, InvalidParamDelimitersError, IsUpperSnakeCase, ParamsFromMessage, SeenReferences, Segment, SerializedBaseError, SerializedNativeError, Tail, Trim, UpperLetter, ValidateErrorDefinitions, Whitespace, createParamPlaceholder, escapeRegExp, isBaseError, serializeBaseError, serializeCauseError, serializeNativeError };
+//# sourceMappingURL=index.d.mts.map