@pedrohb/errors 0.0.0-stage → 1.0.0

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["createParamPlaceholder","DEFAULT_PARAM_DELIMITERS","BASE_ERROR_BRAND","serializeBaseError","isBaseError","serializeCauseError","isUpperSnakeCase","InvalidErrorCode","EitherUnwrapError"],"sources":["../src/interpolate-error-message.ts","../src/base-error.ts","../src/define-error-catalog.ts","../src/either.ts"],"sourcesContent":["import {\r\n  createParamPlaceholder,\r\n  type DefaultParamDelimiters,\r\n} from \"./functions/create-param-placeholder.js\";\r\nimport type { ErrorDescriptor } from \"./types/error-descriptor.js\";\r\nimport type { ErrorParamDelimiters } from \"./types/error-param-delimiters.js\";\r\nimport type {\r\n  ErrorParamValue,\r\n  ParamsFromMessage,\r\n} from \"./types/params-from-message.js\";\r\n\r\n/**\r\n * Deriva, em tempo de compilação a lista de argumentos extras exigida para\r\n * interpolar uma mensagem de erro.\r\n *\r\n * - Se a mensagem **não** tiver placeholders o resultado é uma tupla vazia\r\n *   (`[]`), ou seja, nenhum argumento adicional deve ser passado.\r\n * - Se tiver placeholders o resultado é uma tupla com um único argumento\r\n *   obrigatório, `params` do tipo {@link ParamsFromMessage}.\r\n *\r\n * É pensado para ser usado como tipo de parâmetro rest (`...args`) de modo\r\n * que o objeto de parâmetros seja exigido apenas quando necessário.\r\n *\r\n * @template Message - Mensagem a ser analisada.\r\n * @template Delimiters - Objeto com os delimitadores `open` e `close` do\r\n * placeholder. Por padrão, {@link DefaultParamDelimiters}.\r\n *\r\n * @example\r\n * ```ts\r\n * type A = ErrorMessageArgs<\"Usuário {id} não encontrado\">;\r\n * // [params: Readonly<{ id: ErrorParamValue }>]\r\n *\r\n * type B = ErrorMessageArgs<\"Token inválido\">;\r\n * // []\r\n *\r\n * type C = ErrorMessageArgs<\r\n *   \"Rota [route] não encontrada\",\r\n *   { readonly open: \"[\"; readonly close: \"]\" }\r\n * >;\r\n * // [params: Readonly<{ route: ErrorParamValue }>]\r\n * ```\r\n */\r\nexport type ErrorMessageArgs<\r\n  Message extends string,\r\n  Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters,\r\n> = [ParamsFromMessage<Message, Delimiters>] extends [never]\r\n  ? []\r\n  : [params: ParamsFromMessage<Message, Delimiters>];\r\n\r\n/**\r\n * Interpola os parâmetros informados na mensagem de um descritor de erro\r\n * substituindo cada placeholder pelo valor correspondente.\r\n *\r\n * Os placeholders são localizados com {@link createParamPlaceholder} a partir\r\n * dos delimitadores informados. O nome de cada placeholder é aparado\r\n * (`{ id }` equivale a `{id}`) e o valor é convertido para texto com `String`.\r\n *\r\n * O placeholder é mantido exatamente como está na mensagem (sem substituição)\r\n * quando:\r\n * - o nome é vazio (ex.: `{}` ou `{   }`);\r\n * - o nome não existe como propriedade própria de `params`.\r\n *\r\n * O objeto de parâmetros é exigido ou omitido conforme a mensagem via\r\n * {@link ErrorMessageArgs}: mensagens sem placeholders não aceitam `params` e\r\n * mensagens com placeholders exigem todos eles.\r\n *\r\n * @template Descriptor - Tipo do descritor de erro cuja `message` define os\r\n * parâmetros exigidos.\r\n * @template Delimiters - Tipo dos delimitadores dos placeholders. Por padrão,\r\n * {@link DefaultParamDelimiters}.\r\n * @param descriptor - Descritor de erro cuja mensagem será interpolada.\r\n * @param delimiters - Delimitadores `open` e `close` dos placeholders.\r\n * @param args - Objeto `params` com os valores dos placeholders exigido\r\n * apenas se a mensagem tiver placeholders.\r\n * @returns A mensagem com os placeholders substituídos.\r\n * @throws {InvalidParamDelimitersError} Se `open` ou `close` for uma string\r\n * vazia (lançado por {@link createParamPlaceholder}).\r\n *\r\n * @example\r\n * ```ts\r\n * const keys = { open: \"{\", close: \"}\" } as const;\r\n *\r\n * const USER_NOT_FOUND = {\r\n *   code: \"USER_NOT_FOUND\",\r\n *   message: \"Usuário {id} não encontrado em {table}\",\r\n * } as const satisfies ErrorDescriptor;\r\n *\r\n * interpolateErrorMessage(USER_NOT_FOUND, keys, {\r\n *   id: 42,\r\n *   table: \"users\",\r\n * });\r\n * // \"Usuário 42 não encontrado em users\"\r\n *\r\n * const INVALID_TOKEN = {\r\n *   code: \"INVALID_TOKEN\",\r\n *   message: \"Token inválido\",\r\n * } as const satisfies ErrorDescriptor;\r\n *\r\n * interpolateErrorMessage(INVALID_TOKEN, keys);\r\n * // \"Token inválido\" (sem params)\r\n *\r\n * // Delimitadores personalizados\r\n * const ROUTE_NOT_FOUND = {\r\n *   code: \"ROUTE_NOT_FOUND\",\r\n *   message: \"Rota [route] não encontrada\",\r\n * } as const satisfies ErrorDescriptor;\r\n *\r\n * interpolateErrorMessage(\r\n *   ROUTE_NOT_FOUND,\r\n *   { open: \"[\", close: \"]\" } as const,\r\n *   { route: \"/home\" },\r\n * );\r\n * // \"Rota /home não encontrada\"\r\n * ```\r\n */\r\nexport function interpolateErrorMessage<\r\n  Descriptor extends ErrorDescriptor,\r\n  Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters,\r\n>(\r\n  descriptor: Descriptor,\r\n  delimiters: Delimiters,\r\n  ...args: ErrorMessageArgs<Descriptor[\"message\"], Delimiters>\r\n) {\r\n  const params = (args[0] ?? {}) as Record<string, ErrorParamValue>;\r\n  const placeholder = createParamPlaceholder(delimiters);\r\n\r\n  return descriptor.message.replace(placeholder, (match, rawKey: string) => {\r\n    const key = rawKey.trim();\r\n\r\n    if (key === \"\" || !Object.hasOwn(params, key)) {\r\n      return match;\r\n    }\r\n\r\n    return String(params[key]);\r\n  });\r\n}\r\n","import {\r\n  DEFAULT_PARAM_DELIMITERS,\r\n  type DefaultParamDelimiters,\r\n} from \"./functions/create-param-placeholder.js\";\r\nimport { BASE_ERROR_BRAND, isBaseError } from \"./functions/is-base-error.js\";\r\nimport { serializeBaseError } from \"./functions/serialize-base-error.js\";\r\nimport { serializeCauseError } from \"./functions/serialize-cause-error.js\";\r\nimport {\r\n  type ErrorMessageArgs,\r\n  interpolateErrorMessage,\r\n} from \"./interpolate-error-message.js\";\r\nimport type { CatalogCode } from \"./types/catalog-code.js\";\r\nimport type { CatalogDescriptor } from \"./types/catalog-descriptor.js\";\r\nimport type { ErrorCatalog } from \"./types/error-catalog.js\";\r\nimport type { ErrorParamDelimiters } from \"./types/error-param-delimiters.js\";\r\nimport type { ErrorParams } from \"./types/error-params.js\";\r\n\r\n/**\r\n * Opções aceitas pelo construtor de {@link BaseError}.\r\n *\r\n * Estende `ErrorOptions` (que fornece `cause`) e acrescenta:\r\n * - `delimiters`: delimitadores dos placeholders da mensagem sempre opcional;\r\n * - `params`: valores dos placeholders **exigido apenas** quando a mensagem\r\n *   do código possui placeholders (ver {@link ErrorParams}). Se a mensagem não\r\n *   tiver placeholders a propriedade `params` não existe no tipo.\r\n *\r\n * @template Catalog - Catálogo de erros ao qual o código pertence. Por padrão,\r\n * `ErrorCatalog`.\r\n * @template Code - Código do erro dentro do catálogo. Por padrão, todos os\r\n * códigos do catálogo.\r\n * @template Delimiters - Tipo dos delimitadores dos placeholders. Por padrão,\r\n * {@link DefaultParamDelimiters}.\r\n *\r\n * @example\r\n * ```ts\r\n * // Mensagem sem placeholders: apenas `cause` e `delimiters` são aceitos\r\n * type A = BaseErrorOptions<typeof ERROR_CODES, \"INVALID_TOKEN\">;\r\n * // ErrorOptions & { delimiters?: DefaultParamDelimiters }\r\n *\r\n * // Mensagem com placeholders: `params` é obrigatório\r\n * type B = BaseErrorOptions<typeof ERROR_CODES, \"USER_NOT_FOUND\">;\r\n * // ErrorOptions & { params: Readonly<{ id: ErrorParamValue }>; delimiters?: ... }\r\n * ```\r\n */\r\nexport type BaseErrorOptions<\r\n  Catalog extends ErrorCatalog = ErrorCatalog,\r\n  Code extends CatalogCode<Catalog> = CatalogCode<Catalog>,\r\n  Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters,\r\n> = [ErrorParams<Catalog, Code, Delimiters>] extends [never]\r\n  ? ErrorOptions & {\r\n      delimiters?: Delimiters;\r\n    }\r\n  : ErrorOptions & {\r\n      params: ErrorParams<Catalog, Code, Delimiters>;\r\n      delimiters?: Delimiters;\r\n    };\r\n\r\n/**\r\n * Deriva em tempo de compilação a lista de argumentos de opções do\r\n * construtor de {@link BaseError}.\r\n *\r\n * - Se a mensagem **não** tiver placeholders `options` é opcional.\r\n * - Se tiver placeholders `options` é obrigatório (pois deve conter `params`).\r\n *\r\n * É pensado para ser usado como tipo de parâmetro rest (`...args`).\r\n *\r\n * @template Catalog - Catálogo de erros ao qual o código pertence. Por padrão,\r\n * `ErrorCatalog`.\r\n * @template Code - Código do erro dentro do catálogo. Por padrão, todos os\r\n * códigos do catálogo.\r\n * @template Delimiters - Tipo dos delimitadores dos placeholders. Por padrão,\r\n * {@link DefaultParamDelimiters}.\r\n *\r\n * @example\r\n * ```ts\r\n * type A = BaseErrorOptionsArgs<typeof ERROR_CODES, \"INVALID_TOKEN\">;\r\n * // [options?: BaseErrorOptions<...>]\r\n *\r\n * type B = BaseErrorOptionsArgs<typeof ERROR_CODES, \"USER_NOT_FOUND\">;\r\n * // [options: BaseErrorOptions<...>]\r\n * ```\r\n */\r\nexport type BaseErrorOptionsArgs<\r\n  Catalog extends ErrorCatalog = ErrorCatalog,\r\n  Code extends CatalogCode<Catalog> = CatalogCode<Catalog>,\r\n  Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters,\r\n> = [ErrorParams<Catalog, Code, Delimiters>] extends [never]\r\n  ? [options?: BaseErrorOptions<Catalog, Code, Delimiters>]\r\n  : [options: BaseErrorOptions<Catalog, Code, Delimiters>];\r\n\r\n/**\r\n * Classe base abstrata para erros tipados a partir de um catálogo de erros.\r\n *\r\n * Cada erro é criado a partir de um descritor do catálogo (código e mensagem).\r\n * A mensagem é interpolada com os `params` informados e o tipo dos `params` é\r\n * derivado dos placeholders da mensagem, de modo que o compilador exige\r\n * exatamente os parâmetros necessários.\r\n *\r\n * O construtor é `protected`: a classe não pode ser instanciada diretamente e\r\n * deve ser estendida por classes que escolhem o descritor e repassam as\r\n * opções.\r\n *\r\n * Além de `message`, `cause`, `stack` e `name` herdados de `Error`, a\r\n * instância expõe:\r\n * - `code`: o código do erro, com tipo literal;\r\n * - `params`: os parâmetros usados na interpolação (ou `undefined`);\r\n * - {@link BaseError.serialize} e {@link BaseError.toJSON} para serialização;\r\n * - uma marca interna ({@link BASE_ERROR_BRAND}) que permite reconhecer o\r\n *   erro com {@link isBaseError} mesmo com múltiplas cópias do pacote.\r\n *\r\n * O `name` do erro é o nome da classe concreta (`new.target.name`) e o\r\n * protótipo é ajustado explicitamente para que `instanceof` funcione em\r\n * subclasses mesmo em alvos de compilação antigos.\r\n *\r\n * @template Catalog - Catálogo de erros ao qual o código pertence. Por padrão,\r\n * `ErrorCatalog`.\r\n * @template Code - Código do erro dentro do catálogo. Por padrão, todos os\r\n * códigos do catálogo.\r\n * @template Delimiters - Tipo dos delimitadores dos placeholders. Por padrão,\r\n * {@link DefaultParamDelimiters}.\r\n *\r\n * @example\r\n * ```ts\r\n * const TEST_ERROR_CODES = defineErrorCatalog({\r\n *   USER_NOT_FOUND: \"Usuário {id} não encontrado\",\r\n *   INVALID_TOKEN: \"Token inválido\",\r\n * });\r\n *\r\n * type TestErrorCodes = typeof TEST_ERROR_CODES;\r\n *\r\n * class UserNotFoundError extends BaseError<TestErrorCodes, \"USER_NOT_FOUND\"> {\r\n *   public constructor(id: number, options?: ErrorOptions) {\r\n *     super(TEST_ERROR_CODES.USER_NOT_FOUND, { params: { id }, ...options });\r\n *   }\r\n * }\r\n *\r\n * class InvalidTokenError extends BaseError<TestErrorCodes, \"INVALID_TOKEN\"> {\r\n *   public constructor(options?: ErrorOptions) {\r\n *     super(TEST_ERROR_CODES.INVALID_TOKEN, options);\r\n *   }\r\n * }\r\n *\r\n * const erro = new UserNotFoundError(42);\r\n * erro.message; // \"Usuário 42 não encontrado\"\r\n * erro.code;    // \"USER_NOT_FOUND\"\r\n * erro.params;  // { id: 42 }\r\n * erro.name;    // \"UserNotFoundError\"\r\n *\r\n * BaseError.is(erro);                // true\r\n * JSON.stringify(erro);              // usa toJSON(), sem stack trace\r\n * erro.serialize(true);              // inclui o stack trace\r\n * ```\r\n */\r\nexport abstract class BaseError<\r\n  Catalog extends ErrorCatalog = ErrorCatalog,\r\n  Code extends CatalogCode<Catalog> = CatalogCode<Catalog>,\r\n  Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters,\r\n> extends Error {\r\n  /** Código do erro conforme o catálogo (ex.: `\"USER_NOT_FOUND\"`). */\r\n  public readonly code: Code;\r\n  /**\r\n   * Parâmetros usados para interpolar a mensagem. É `undefined` quando a\r\n   * mensagem não possui placeholders (ou quando nenhum `params` foi informado).\r\n   */\r\n  public readonly params?: ErrorParams<Catalog, Code, Delimiters>;\r\n\r\n  /**\r\n   * Cria um erro a partir de um descritor do catálogo.\r\n   *\r\n   * A mensagem do descritor é interpolada com `options.params` usando os\r\n   * delimitadores de `options.delimiters` (por padrão,\r\n   * {@link DEFAULT_PARAM_DELIMITERS}). Os delimitadores são usados apenas na\r\n   * interpolação e não são armazenados na instância. O objeto `options`\r\n   * também é repassado ao construtor de `Error`, que utiliza `cause`.\r\n   *\r\n   * É `protected` então só pode ser chamado por subclasses.\r\n   *\r\n   * @param descriptor - Descritor do erro no catálogo com `code` e `message`.\r\n   * @param args - Opções do erro ({@link BaseErrorOptions}). São obrigatórias\r\n   * se a mensagem tiver placeholders (por conter `params`) e opcionais caso\r\n   * contrário.\r\n   * @throws {InvalidParamDelimitersError} Se algum dos delimitadores for uma\r\n   * string vazia (lançado durante a interpolação).\r\n   */\r\n  protected constructor(\r\n    descriptor: CatalogDescriptor<Catalog, Code>,\r\n    ...args: BaseErrorOptionsArgs<Catalog, Code, Delimiters>\r\n  ) {\r\n    const options = args[0];\r\n    const delimiters = (options?.delimiters ??\r\n      DEFAULT_PARAM_DELIMITERS) as Delimiters;\r\n    const params = options && \"params\" in options ? options.params : undefined;\r\n    const interpolationArgs = (\r\n      params === undefined ? [] : [params]\r\n    ) as ErrorMessageArgs<\r\n      CatalogDescriptor<Catalog, Code>[\"message\"],\r\n      Delimiters\r\n    >;\r\n\r\n    super(\r\n      interpolateErrorMessage(descriptor, delimiters, ...interpolationArgs),\r\n      options,\r\n    );\r\n\r\n    this.name = new.target.name;\r\n    this.code = descriptor.code;\r\n    this.params = params;\r\n\r\n    Object.setPrototypeOf(this, new.target.prototype);\r\n\r\n    if (Error.captureStackTrace) {\r\n      Error.captureStackTrace(this, new.target);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Marca interna que identifica a instância como um `BaseError`.\r\n   *\r\n   * Sempre retorna `true` e é lida por {@link isBaseError}. Por ser um\r\n   * getter definido no protótipo, não é uma propriedade própria da instância\r\n   * e portanto, não aparece em serializações nem em `Object.keys`.\r\n   */\r\n  public get [BASE_ERROR_BRAND]() {\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Serializa o erro para um objeto simples apropriado para `JSON.stringify`,\r\n   * logs ou transmissão. Veja {@link serializeBaseError} para os detalhes do\r\n   * formato retornado.\r\n   *\r\n   * @param includeStack - Se `true` inclui o stack trace no resultado (e na\r\n   * serialização de causas e parâmetros). Por padrão, `false`.\r\n   * @returns Representação serializável do erro.\r\n   */\r\n  public serialize(includeStack = false) {\r\n    return serializeBaseError(this as Readonly<BaseError>, includeStack);\r\n  }\r\n\r\n  /**\r\n   * Chamado automaticamente por `JSON.stringify`. Equivale a\r\n   * {@link BaseError.serialize} sem stack trace.\r\n   *\r\n   * @returns Representação serializável do erro sem stack trace.\r\n   */\r\n  public toJSON() {\r\n    return this.serialize();\r\n  }\r\n\r\n  /**\r\n   * Verifica se um valor é uma instância de `BaseError` (type guard).\r\n   *\r\n   * Atalho para {@link isBaseError}: usa a marca interna em vez de\r\n   * `instanceof` funcionando mesmo com múltiplas cópias do pacote.\r\n   *\r\n   * @param error - Valor a ser verificado.\r\n   * @returns `true` se `error` for um `BaseError`; caso contrário, `false`.\r\n   */\r\n  public static is(error: unknown): error is BaseError {\r\n    return isBaseError(error);\r\n  }\r\n\r\n  /**\r\n   * Serializa de forma segura qualquer valor usado como causa de um erro.\r\n   *\r\n   * Atalho para {@link serializeCauseError}: trata erros, datas, arrays,\r\n   * objetos, funções, `bigint`, `symbol` e referências circulares.\r\n   *\r\n   * @param cause - Valor a ser serializado.\r\n   * @param includeStack - Se `true` inclui o stack trace ao serializar\r\n   * erros. Por padrão, `false`.\r\n   * @returns Representação serializável do valor.\r\n   */\r\n  public static serializeCauseError(cause: unknown, includeStack = false) {\r\n    return serializeCauseError(cause, includeStack);\r\n  }\r\n}\r\n","import { InvalidErrorCode } from \"./errors/invalid-error-code.js\";\r\nimport type { ErrorCatalog } from \"./types/error-catalog.js\";\r\nimport type { ErrorDescriptor } from \"./types/error-descriptor.js\";\r\nimport type { ValidateErrorDefinitions } from \"./types/validate-error-definitions.js\";\r\nimport { isUpperSnakeCase } from \"./upper-snake-case.js\";\r\n\r\n/**\r\n * Cria um catálogo de erros imutável a partir de um objeto que associa cada\r\n * código de erro à sua mensagem.\r\n *\r\n * Para cada entrada de `definitions` gera um {@link ErrorDescriptor} com\r\n * `code` e `message` congelado com `Object.freeze`. O próprio catálogo\r\n * retornado também é congelado, de modo que nem o catálogo nem seus\r\n * descritores podem ser alterados depois de criados.\r\n *\r\n * A validação ocorre em duas camadas:\r\n * - em tempo de compilação via {@link ValidateErrorDefinitions}: códigos fora\r\n *   de UPPER_SNAKE_CASE geram um erro de tipo com uma mensagem explicativa;\r\n * - em tempo de execução via {@link isUpperSnakeCase}: códigos inválidos\r\n *   lançam {@link InvalidErrorCode}, o que protege contra definições que\r\n *   escapem da checagem de tipos (ex.: objetos tipados como `any` ou\r\n *   `Record<string, string>`).\r\n *\r\n * O parâmetro de tipo `T` é declarado como `const`, o que preserva os tipos\r\n * literais dos códigos e das mensagens sem a necessidade de `as const` na\r\n * chamada.\r\n *\r\n * @template Codes - Objeto que mapeia códigos de erro para suas mensagens.\r\n * @param definitions - Definições do catálogo: chaves são os códigos em\r\n * UPPER_SNAKE_CASE.\r\n * @returns Catálogo de erros somente leitura com um descritor para cada\r\n * código informado.\r\n * @throws {InvalidErrorCode} Se algum código não estiver em UPPER_SNAKE_CASE.\r\n *\r\n * @example\r\n * ```ts\r\n * const TEST_ERROR_CODES = defineErrorCatalog({\r\n *   USER_NOT_FOUND: \"Usuário {id} não encontrado\",\r\n *   INVALID_TOKEN: \"Token inválido\",\r\n * });\r\n *\r\n * TEST_ERROR_CODES.USER_NOT_FOUND.code;    // \"USER_NOT_FOUND\"\r\n * TEST_ERROR_CODES.USER_NOT_FOUND.message; // \"Usuário {id} não encontrado\"\r\n *\r\n * // Erro de compilação (e de execução): código fora de UPPER_SNAKE_CASE\r\n * defineErrorCatalog({\r\n *   userNotFound: \"Usuário não encontrado\",\r\n * });\r\n * // Lança InvalidErrorCode\r\n * ```\r\n */\r\nexport function defineErrorCatalog<const Codes extends Record<string, string>>(\r\n  definitions: ValidateErrorDefinitions<Codes>,\r\n): ErrorCatalog<Codes> {\r\n  const catalog: Record<string, ErrorDescriptor> = {};\r\n\r\n  for (const [code, message] of Object.entries(\r\n    definitions as Record<string, string>,\r\n  )) {\r\n    if (!isUpperSnakeCase(code)) {\r\n      throw new InvalidErrorCode(code);\r\n    }\r\n\r\n    catalog[code] = Object.freeze({ code, message });\r\n  }\r\n\r\n  return Object.freeze(catalog) as ErrorCatalog<Codes>;\r\n}\r\n","import { EitherUnwrapError } from \"./errors/either-unwrap-error.js\";\r\n\r\n/**\r\n * Representa o resultado de uma operação que pode ter sucesso (`Ok`) ou\r\n * falhar (`Err`), tornando o erro parte explícita do tipo de retorno em vez\r\n * de depender de exceções.\r\n *\r\n * Um `Either<O, E>` é sempre uma instância de {@link Ok} que carrega um\r\n * valor de sucesso do tipo `O`, ou de {@link Err} que carrega um valor de\r\n * erro do tipo `E`. Use {@link ok} e {@link err} para criá-los.\r\n *\r\n * Os métodos {@link Either.map}, {@link Either.mapErr}, {@link Either.flatMap}\r\n * e {@link Either.orElse} retornam um novo `Either` e não alteram o original.\r\n * Para tratar os dois casos use {@link Either.match}, ou os type guards\r\n * {@link Either.isOk} e {@link Either.isErr}.\r\n *\r\n * @template O - Tipo do valor de sucesso.\r\n * @template E - Tipo do valor de erro.\r\n *\r\n * @example\r\n * ```ts\r\n * function toDivide(a: number, b: number): Either<number, string> {\r\n *   return b === 0 ? err(\"Divisão por zero\") : ok(a / b);\r\n * }\r\n *\r\n * const message = toDivide(10, 2)\r\n *   .map((resultado) => resultado * 3)\r\n *   .match({\r\n *     onOk: (valor) => `Resultado: ${valor}`,\r\n *     onErr: (erro) => `Falha: ${erro}`,\r\n *   });\r\n * // \"Resultado: 15\"\r\n * ```\r\n */\r\nexport abstract class Either<O, E> {\r\n  /** Discriminante da variante: `\"Ok\"` para sucesso e `\"Err\"` para erro. */\r\n  public abstract readonly tag: \"Ok\" | \"Err\";\r\n\r\n  /**\r\n   * Retorna o valor de sucesso.\r\n   *\r\n   * @returns O valor contido em `Ok`.\r\n   * @throws {EitherUnwrapError} Se for um `Err`. A `cause` do erro é o valor\r\n   * de erro contido.\r\n   */\r\n  public abstract unwrap(): O;\r\n\r\n  /**\r\n   * Retorna o valor de erro.\r\n   *\r\n   * @returns O valor contido em `Err`.\r\n   * @throws {EitherUnwrapError} Se for um `Ok`. A `cause` do erro é o valor\r\n   * de sucesso contido.\r\n   */\r\n  public abstract unwrapErr(): E;\r\n\r\n  /**\r\n   * Verifica se é um `Ok` funcionando como type guard.\r\n   *\r\n   * @returns `true` se for `Ok` (restringindo o tipo para {@link Ok});\r\n   * caso contrário, `false`.\r\n   */\r\n  public abstract isOk(): this is Ok<O, E>;\r\n\r\n  /**\r\n   * Verifica se é um `Err` funcionando como type guard.\r\n   *\r\n   * @returns `true` se for `Err` (restringindo o tipo para {@link Err});\r\n   * caso contrário, `false`.\r\n   */\r\n  public abstract isErr(): this is Err<O, E>;\r\n\r\n  /**\r\n   * Transforma o valor de sucesso mantendo o erro intacto.\r\n   *\r\n   * Se for `Ok` aplica `fn` ao valor e retorna um novo `Ok` com o resultado.\r\n   * Se for `Err` `fn` não é chamada e um novo `Err` com o mesmo erro é\r\n   * retornado. Exceções lançadas por `fn` não são capturadas.\r\n   *\r\n   * @template O2 - Tipo do novo valor de sucesso.\r\n   * @param fn - Função que converte o valor de sucesso.\r\n   * @returns Um `Either` com o valor transformado ou o erro original.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * ok<number, string>(2).map((n) => n * 2).unwrap(); // 4\r\n   * err<number, string>(\"falhou\").map((n) => n * 2).unwrapErr(); // \"falhou\"\r\n   * ```\r\n   */\r\n  public map<O2>(fn: (value: O) => O2): Either<O2, E> {\r\n    if (this.isOk()) {\r\n      return ok(fn(this.unwrap()));\r\n    }\r\n\r\n    return err(this.unwrapErr());\r\n  }\r\n\r\n  /**\r\n   * Transforma o valor de erro mantendo o sucesso intacto.\r\n   *\r\n   * Se for `Err` aplica `fn` ao erro e retorna um novo `Err` com o resultado.\r\n   * Se for `Ok` `fn` não é chamada e um novo `Ok` com o mesmo valor é\r\n   * retornado. Exceções lançadas por `fn` não são capturadas.\r\n   *\r\n   * @template E2 - Tipo do novo valor de erro.\r\n   * @param fn - Função que converte o valor de erro.\r\n   * @returns Um `Either` com o erro transformado ou o valor original.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * err<number, string>(\"falhou\").mapErr((e) => e.length).unwrapErr(); // 7\r\n   * ok<number, string>(1).mapErr((e) => e.length).unwrap(); // 1\r\n   * ```\r\n   */\r\n  public mapErr<E2>(fn: (value: E) => E2): Either<O, E2> {\r\n    if (this.isErr()) {\r\n      return err(fn(this.unwrapErr()));\r\n    }\r\n\r\n    return ok(this.unwrap());\r\n  }\r\n\r\n  /**\r\n   * Encadeia uma operação que também retorna um `Either` usada quando o\r\n   * próximo passo também pode falhar.\r\n   *\r\n   * Se for `Ok`, retorna diretamente o `Either` produzido por `fn` (sem\r\n   * aninhamento). Se for `Err` `fn` não é chamada e o erro é propagado.\r\n   * O tipo de erro resultante é a união `E | E2`. Exceções lançadas por `fn`\r\n   * não são capturadas.\r\n   *\r\n   * @template O2 - Tipo do valor de sucesso retornado por `fn`.\r\n   * @template E2 - Tipo do valor de erro retornado por `fn`.\r\n   * @param fn - Função que recebe o valor de sucesso e retorna um `Either`.\r\n   * @returns O `Either` retornado por `fn`, ou o erro original.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * const forNumber = (s: string): Either<number, string> => {\r\n   *   const n = Number(s);\r\n   *   return Number.isNaN(n) ? err(\"Não é número\") : ok(n);\r\n   * };\r\n   *\r\n   * ok<string, string>(\"42\").flatMap(forNumber).unwrap(); // 42\r\n   * ok<string, string>(\"abc\").flatMap(forNumber).unwrapErr(); // \"Não é número\"\r\n   * ```\r\n   */\r\n  public flatMap<O2, E2>(fn: (value: O) => Either<O2, E2>): Either<O2, E | E2> {\r\n    if (this.isOk()) {\r\n      return fn(this.unwrap());\r\n    }\r\n\r\n    return err(this.unwrapErr());\r\n  }\r\n\r\n  /**\r\n   * Tenta se recuperar de um erro encadeando uma operação alternativa que\r\n   * também retorna um `Either`. É o oposto de {@link Either.flatMap}.\r\n   *\r\n   * Se for `Err` retorna diretamente o `Either` produzido por `fn`. Se for\r\n   * `Ok` `fn` não é chamada e o valor é mantido. O tipo de sucesso\r\n   * resultante é a união `O | O2`. Exceções lançadas por `fn` não são\r\n   * capturadas.\r\n   *\r\n   * @template O2 - Tipo do valor de sucesso retornado por `fn`.\r\n   * @template E2 - Tipo do valor de erro retornado por `fn`.\r\n   * @param fn - Função que recebe o valor de erro e retorna um `Either`.\r\n   * @returns O `Either` retornado por `fn`, ou o valor de sucesso original.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * err<number, string>(\"falhou\").orElse(() => ok(0)).unwrap(); // 0\r\n   * ok<number, string>(5).orElse(() => ok(0)).unwrap(); // 5\r\n   * ```\r\n   */\r\n  public orElse<O2, E2>(fn: (value: E) => Either<O2, E2>): Either<O | O2, E2> {\r\n    if (this.isErr()) {\r\n      return fn(this.unwrapErr());\r\n    }\r\n\r\n    return ok(this.unwrap());\r\n  }\r\n\r\n  /**\r\n   * Trata os dois casos e produz um único valor chamando o handler da\r\n   * variante correspondente.\r\n   *\r\n   * @template R - Tipo do valor retornado pelos handlers.\r\n   * @param handlers - Objeto com `onOk` chamado com o valor de sucesso e\r\n   * `onErr` chamado com o valor de erro.\r\n   * @returns O resultado do handler chamado.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * const texto = resultado.match({\r\n   *   onOk: (valor) => `Sucesso: ${valor}`,\r\n   *   onErr: (erro) => `Erro: ${erro}`,\r\n   * });\r\n   * ```\r\n   */\r\n  public match<R>(\r\n    handlers: Readonly<{ onOk(value: O): R; onErr(value: E): R }>,\r\n  ): R {\r\n    if (this.isOk()) {\r\n      return handlers.onOk(this.unwrap());\r\n    }\r\n\r\n    return handlers.onErr(this.unwrapErr());\r\n  }\r\n}\r\n\r\n/**\r\n * Variante de sucesso de {@link Either} que carrega um valor do tipo `O`.\r\n *\r\n * O construtor é `protected`; para criar uma instância use {@link Ok.create}\r\n * ou a função {@link ok}.\r\n *\r\n * @template O - Tipo do valor de sucesso. Por padrão, `never`.\r\n * @template E - Tipo do valor de erro usado apenas para compatibilidade com\r\n * {@link Either}. Por padrão, `never`.\r\n */\r\nexport class Ok<O = never, E = never> extends Either<O, E> {\r\n  /** Discriminante da variante sempre `\"Ok\"`. */\r\n  public readonly tag = \"Ok\" as const;\r\n  /** Valor de sucesso armazenado. */\r\n  private readonly value: O;\r\n\r\n  /**\r\n   * @param value - Valor de sucesso a ser armazenado.\r\n   */\r\n  protected constructor(value: O) {\r\n    super();\r\n\r\n    this.value = value;\r\n  }\r\n\r\n  /**\r\n   * Retorna o valor de sucesso armazenado.\r\n   *\r\n   * @returns O valor contido.\r\n   */\r\n  public unwrap(): O {\r\n    return this.value;\r\n  }\r\n\r\n  /**\r\n   * Sempre lança um erro pois um `Ok` não possui valor de erro.\r\n   *\r\n   * @throws {EitherUnwrapError} Sempre. A `cause` é o valor de sucesso contido.\r\n   */\r\n  public unwrapErr(): E {\r\n    throw new EitherUnwrapError(\"Chamado unwrapErr() em Ok.\", {\r\n      cause: this.value,\r\n    });\r\n  }\r\n\r\n  /** @returns Sempre `true`. */\r\n  public isOk(): this is Ok<O, E> {\r\n    return true;\r\n  }\r\n\r\n  /** @returns Sempre `false`. */\r\n  public isErr(): this is Err<O, E> {\r\n    return false;\r\n  }\r\n\r\n  /**\r\n   * Cria um `Ok` com o valor informado.\r\n   *\r\n   * @template O - Tipo do valor de sucesso. Por padrão, `never`.\r\n   * @template E - Tipo do valor de erro. Por padrão, `never`.\r\n   * @param value - Valor de sucesso.\r\n   * @returns Uma nova instância de `Ok`.\r\n   */\r\n  public static create<O = never, E = never>(value: O): Ok<O, E> {\r\n    return new Ok(value);\r\n  }\r\n}\r\n\r\n/**\r\n * Variante de erro de {@link Either} que carrega um valor do tipo `E`.\r\n *\r\n * O construtor é `protected`; para criar uma instância use {@link Err.create}\r\n * ou a função {@link err}.\r\n *\r\n * @template O - Tipo do valor de sucesso usado apenas para compatibilidade\r\n * com {@link Either}. Por padrão, `never`.\r\n * @template E - Tipo do valor de erro. Por padrão, `never`.\r\n */\r\nexport class Err<O = never, E = never> extends Either<O, E> {\r\n  /** Discriminante da variante sempre `\"Err\"`. */\r\n  public readonly tag = \"Err\" as const;\r\n  /** Valor de erro armazenado. */\r\n  private readonly value: E;\r\n\r\n  /**\r\n   * @param value - Valor de erro a ser armazenado.\r\n   */\r\n  protected constructor(value: E) {\r\n    super();\r\n\r\n    this.value = value;\r\n  }\r\n\r\n  /**\r\n   * Sempre lança um erro pois um `Err` não possui valor de sucesso.\r\n   *\r\n   * @throws {EitherUnwrapError} Sempre. A `cause` é o valor de erro contido.\r\n   */\r\n  public unwrap(): O {\r\n    throw new EitherUnwrapError(\"Chamado unwrap() em Err.\", {\r\n      cause: this.value,\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Retorna o valor de erro armazenado.\r\n   *\r\n   * @returns O valor contido.\r\n   */\r\n  public unwrapErr(): E {\r\n    return this.value;\r\n  }\r\n\r\n  /** @returns Sempre `false`. */\r\n  public isOk(): this is Ok<O, E> {\r\n    return false;\r\n  }\r\n\r\n  /** @returns Sempre `true`. */\r\n  public isErr(): this is Err<O, E> {\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Cria um `Err` com o valor informado.\r\n   *\r\n   * @template O - Tipo do valor de sucesso. Por padrão, `never`.\r\n   * @template E - Tipo do valor de erro. Por padrão, `never`.\r\n   * @param value - Valor de erro.\r\n   * @returns Uma nova instância de `Err`.\r\n   */\r\n  public static create<O = never, E = never>(value: E): Err<O, E> {\r\n    return new Err(value);\r\n  }\r\n}\r\n\r\n/**\r\n * Cria um {@link Either} de sucesso (`Ok`) com o valor informado.\r\n *\r\n * O retorno é tipado como `Either<O, E>` e não como `Ok` para que possa ser\r\n * usado onde se espera qualquer variante. Como `E` não pode ser inferido a\r\n * partir do argumento, informe-o explicitamente quando necessário.\r\n *\r\n * @template O - Tipo do valor de sucesso. Por padrão, `never`.\r\n * @template E - Tipo do valor de erro. Por padrão, `never`.\r\n * @param value - Valor de sucesso.\r\n * @returns Um `Either` que é um `Ok` contendo `value`.\r\n *\r\n * @example\r\n * ```ts\r\n * const result = ok<number, string>(42);\r\n * result.isOk();   // true\r\n * result.unwrap(); // 42\r\n * ```\r\n */\r\nexport function ok<O = never, E = never>(value: O): Either<O, E> {\r\n  return Ok.create(value);\r\n}\r\n\r\n/**\r\n * Cria um {@link Either} de erro (`Err`) com o valor informado.\r\n *\r\n * O retorno é tipado como `Either<O, E>` e não como `Err` para que possa ser\r\n * usado onde se espera qualquer variante. Como `O` não pode ser inferido a\r\n * partir do argumento, informe-o explicitamente quando necessário.\r\n *\r\n * @template O - Tipo do valor de sucesso. Por padrão, `never`.\r\n * @template E - Tipo do valor de erro. Por padrão, `never`.\r\n * @param value - Valor de erro.\r\n * @returns Um `Either` que é um `Err` contendo `value`.\r\n *\r\n * @example\r\n * ```ts\r\n * const result = err<number, string>(\"Algo deu errado\");\r\n * result.isErr();      // true\r\n * result.unwrapErr();  // \"Algo deu errado\"\r\n * ```\r\n */\r\nexport function err<O = never, E = never>(value: E): Either<O, E> {\r\n  return Err.create(value);\r\n}\r\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,510 @@
+import { EitherUnwrapError, InvalidErrorCode, InvalidParamDelimitersError } from "./errors/index.cjs";
+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.cjs";
+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-BzFCOXvr.cjs";
+import { AlphaNumeric, Digit, InvalidCodeMessage, IsUpperSnakeCase, Segment, Tail, UpperLetter, ValidateErrorDefinitions } from "./types/index.cjs";
+//#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.cts.map