@pedrohb/errors 0.0.0-stage → 1.0.0

package/dist/index-B4tdSdCF.d.mts

@@ -0,0 +1,544 @@
+import { c as CatalogCode, f as DefaultParamDelimiters, l as ErrorCatalog, m as ErrorParamDelimiters, s as CatalogDescriptor, t as ErrorParams } from "./error-params-CR2parjT.mjs";
+//#region src/functions/escape-reg-exp.d.ts
+/**
+ * Escapa os caracteres especiais de expressões regulares em uma string, para
+ * que ela possa ser usada como texto literal dentro de um `RegExp`.
+ *
+ * Cada caractere especial (`. * + ? ^ $ { } ( ) | [ ] \`) é precedido por uma
+ * barra invertida. Caracteres comuns permanecem inalterados.
+ *
+ * Útil por exemplo, para montar uma expressão regular a partir de
+ * delimitadores informados pelo usuário (como os de placeholders), sem que
+ * símbolos como `[` ou `{` sejam interpretados como parte da sintaxe.
+ *
+ * @param value - String a ser escapada.
+ * @returns A string com os caracteres especiais escapados.
+ *
+ * @example
+ * ```ts
+ * escapeRegExp("{id}");        // "\\{id\\}"
+ * escapeRegExp("[nome]");      // "\\[nome\\]"
+ * escapeRegExp("a.b*c");       // "a\\.b\\*c"
+ * escapeRegExp("texto livre"); // "texto livre"
+ *
+ * const regex = new RegExp(escapeRegExp("(x)"), "g");
+ * "valor (x) aqui".replace(regex, "1"); // "valor 1 aqui"
+ * ```
+ */
+declare function escapeRegExp(value: string): string;
+//#endregion
+//#region src/base-error.d.ts
+/**
+ * Opções aceitas pelo construtor de {@link BaseError}.
+ *
+ * Estende `ErrorOptions` (que fornece `cause`) e acrescenta:
+ * - `delimiters`: delimitadores dos placeholders da mensagem sempre opcional;
+ * - `params`: valores dos placeholders **exigido apenas** quando a mensagem
+ *   do código possui placeholders (ver {@link ErrorParams}). Se a mensagem não
+ *   tiver placeholders a propriedade `params` não existe no tipo.
+ *
+ * @template Catalog - Catálogo de erros ao qual o código pertence. Por padrão,
+ * `ErrorCatalog`.
+ * @template Code - Código do erro dentro do catálogo. Por padrão, todos os
+ * códigos do catálogo.
+ * @template Delimiters - Tipo dos delimitadores dos placeholders. Por padrão,
+ * {@link DefaultParamDelimiters}.
+ *
+ * @example
+ * ```ts
+ * // Mensagem sem placeholders: apenas `cause` e `delimiters` são aceitos
+ * type A = BaseErrorOptions<typeof ERROR_CODES, "INVALID_TOKEN">;
+ * // ErrorOptions & { delimiters?: DefaultParamDelimiters }
+ *
+ * // Mensagem com placeholders: `params` é obrigatório
+ * type B = BaseErrorOptions<typeof ERROR_CODES, "USER_NOT_FOUND">;
+ * // ErrorOptions & { params: Readonly<{ id: ErrorParamValue }>; delimiters?: ... }
+ * ```
+ */
+type BaseErrorOptions<Catalog extends ErrorCatalog = ErrorCatalog, Code extends CatalogCode<Catalog> = CatalogCode<Catalog>, Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters> = [ErrorParams<Catalog, Code, Delimiters>] extends [never] ? ErrorOptions & {
+  delimiters?: Delimiters;
+} : ErrorOptions & {
+  params: ErrorParams<Catalog, Code, Delimiters>;
+  delimiters?: Delimiters;
+};
+/**
+ * Deriva em tempo de compilação a lista de argumentos de opções do
+ * construtor de {@link BaseError}.
+ *
+ * - Se a mensagem **não** tiver placeholders `options` é opcional.
+ * - Se tiver placeholders `options` é obrigatório (pois deve conter `params`).
+ *
+ * É pensado para ser usado como tipo de parâmetro rest (`...args`).
+ *
+ * @template Catalog - Catálogo de erros ao qual o código pertence. Por padrão,
+ * `ErrorCatalog`.
+ * @template Code - Código do erro dentro do catálogo. Por padrão, todos os
+ * códigos do catálogo.
+ * @template Delimiters - Tipo dos delimitadores dos placeholders. Por padrão,
+ * {@link DefaultParamDelimiters}.
+ *
+ * @example
+ * ```ts
+ * type A = BaseErrorOptionsArgs<typeof ERROR_CODES, "INVALID_TOKEN">;
+ * // [options?: BaseErrorOptions<...>]
+ *
+ * type B = BaseErrorOptionsArgs<typeof ERROR_CODES, "USER_NOT_FOUND">;
+ * // [options: BaseErrorOptions<...>]
+ * ```
+ */
+type BaseErrorOptionsArgs<Catalog extends ErrorCatalog = ErrorCatalog, Code extends CatalogCode<Catalog> = CatalogCode<Catalog>, Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters> = [ErrorParams<Catalog, Code, Delimiters>] extends [never] ? [options?: BaseErrorOptions<Catalog, Code, Delimiters>] : [options: BaseErrorOptions<Catalog, Code, Delimiters>];
+/**
+ * Classe base abstrata para erros tipados a partir de um catálogo de erros.
+ *
+ * Cada erro é criado a partir de um descritor do catálogo (código e mensagem).
+ * A mensagem é interpolada com os `params` informados e o tipo dos `params` é
+ * derivado dos placeholders da mensagem, de modo que o compilador exige
+ * exatamente os parâmetros necessários.
+ *
+ * O construtor é `protected`: a classe não pode ser instanciada diretamente e
+ * deve ser estendida por classes que escolhem o descritor e repassam as
+ * opções.
+ *
+ * Além de `message`, `cause`, `stack` e `name` herdados de `Error`, a
+ * instância expõe:
+ * - `code`: o código do erro, com tipo literal;
+ * - `params`: os parâmetros usados na interpolação (ou `undefined`);
+ * - {@link BaseError.serialize} e {@link BaseError.toJSON} para serialização;
+ * - uma marca interna ({@link BASE_ERROR_BRAND}) que permite reconhecer o
+ *   erro com {@link isBaseError} mesmo com múltiplas cópias do pacote.
+ *
+ * O `name` do erro é o nome da classe concreta (`new.target.name`) e o
+ * protótipo é ajustado explicitamente para que `instanceof` funcione em
+ * subclasses mesmo em alvos de compilação antigos.
+ *
+ * @template Catalog - Catálogo de erros ao qual o código pertence. Por padrão,
+ * `ErrorCatalog`.
+ * @template Code - Código do erro dentro do catálogo. Por padrão, todos os
+ * códigos do catálogo.
+ * @template Delimiters - Tipo dos delimitadores dos placeholders. Por padrão,
+ * {@link DefaultParamDelimiters}.
+ *
+ * @example
+ * ```ts
+ * const TEST_ERROR_CODES = defineErrorCatalog({
+ *   USER_NOT_FOUND: "Usuário {id} não encontrado",
+ *   INVALID_TOKEN: "Token inválido",
+ * });
+ *
+ * type TestErrorCodes = typeof TEST_ERROR_CODES;
+ *
+ * class UserNotFoundError extends BaseError<TestErrorCodes, "USER_NOT_FOUND"> {
+ *   public constructor(id: number, options?: ErrorOptions) {
+ *     super(TEST_ERROR_CODES.USER_NOT_FOUND, { params: { id }, ...options });
+ *   }
+ * }
+ *
+ * class InvalidTokenError extends BaseError<TestErrorCodes, "INVALID_TOKEN"> {
+ *   public constructor(options?: ErrorOptions) {
+ *     super(TEST_ERROR_CODES.INVALID_TOKEN, options);
+ *   }
+ * }
+ *
+ * const erro = new UserNotFoundError(42);
+ * erro.message; // "Usuário 42 não encontrado"
+ * erro.code;    // "USER_NOT_FOUND"
+ * erro.params;  // { id: 42 }
+ * erro.name;    // "UserNotFoundError"
+ *
+ * BaseError.is(erro);                // true
+ * JSON.stringify(erro);              // usa toJSON(), sem stack trace
+ * erro.serialize(true);              // inclui o stack trace
+ * ```
+ */
+declare abstract class BaseError<Catalog extends ErrorCatalog = ErrorCatalog, Code extends CatalogCode<Catalog> = CatalogCode<Catalog>, Delimiters extends ErrorParamDelimiters = DefaultParamDelimiters> extends Error {
+  /** Código do erro conforme o catálogo (ex.: `"USER_NOT_FOUND"`). */
+  readonly code: Code;
+  /**
+   * Parâmetros usados para interpolar a mensagem. É `undefined` quando a
+   * mensagem não possui placeholders (ou quando nenhum `params` foi informado).
+   */
+  readonly params?: ErrorParams<Catalog, Code, Delimiters>;
+  /**
+   * Cria um erro a partir de um descritor do catálogo.
+   *
+   * A mensagem do descritor é interpolada com `options.params` usando os
+   * delimitadores de `options.delimiters` (por padrão,
+   * {@link DEFAULT_PARAM_DELIMITERS}). Os delimitadores são usados apenas na
+   * interpolação e não são armazenados na instância. O objeto `options`
+   * também é repassado ao construtor de `Error`, que utiliza `cause`.
+   *
+   * É `protected` então só pode ser chamado por subclasses.
+   *
+   * @param descriptor - Descritor do erro no catálogo com `code` e `message`.
+   * @param args - Opções do erro ({@link BaseErrorOptions}). São obrigatórias
+   * se a mensagem tiver placeholders (por conter `params`) e opcionais caso
+   * contrário.
+   * @throws {InvalidParamDelimitersError} Se algum dos delimitadores for uma
+   * string vazia (lançado durante a interpolação).
+   */
+  protected constructor(descriptor: CatalogDescriptor<Catalog, Code>, ...args: BaseErrorOptionsArgs<Catalog, Code, Delimiters>);
+  /**
+   * Marca interna que identifica a instância como um `BaseError`.
+   *
+   * Sempre retorna `true` e é lida por {@link isBaseError}. Por ser um
+   * getter definido no protótipo, não é uma propriedade própria da instância
+   * e portanto, não aparece em serializações nem em `Object.keys`.
+   */
+  get [BASE_ERROR_BRAND](): boolean;
+  /**
+   * Serializa o erro para um objeto simples apropriado para `JSON.stringify`,
+   * logs ou transmissão. Veja {@link serializeBaseError} para os detalhes do
+   * formato retornado.
+   *
+   * @param includeStack - Se `true` inclui o stack trace no resultado (e na
+   * serialização de causas e parâmetros). Por padrão, `false`.
+   * @returns Representação serializável do erro.
+   */
+  serialize(includeStack?: boolean): Readonly<{
+    cause?: unknown;
+    code: string;
+    message: string;
+    name: string;
+    params?: Readonly<Record<string, unknown>>;
+    stack?: string;
+  }>;
+  /**
+   * Chamado automaticamente por `JSON.stringify`. Equivale a
+   * {@link BaseError.serialize} sem stack trace.
+   *
+   * @returns Representação serializável do erro sem stack trace.
+   */
+  toJSON(): Readonly<{
+    cause?: unknown;
+    code: string;
+    message: string;
+    name: string;
+    params?: Readonly<Record<string, unknown>>;
+    stack?: string;
+  }>;
+  /**
+   * Verifica se um valor é uma instância de `BaseError` (type guard).
+   *
+   * Atalho para {@link isBaseError}: usa a marca interna em vez de
+   * `instanceof` funcionando mesmo com múltiplas cópias do pacote.
+   *
+   * @param error - Valor a ser verificado.
+   * @returns `true` se `error` for um `BaseError`; caso contrário, `false`.
+   */
+  static is(error: unknown): error is BaseError;
+  /**
+   * Serializa de forma segura qualquer valor usado como causa de um erro.
+   *
+   * Atalho para {@link serializeCauseError}: trata erros, datas, arrays,
+   * objetos, funções, `bigint`, `symbol` e referências circulares.
+   *
+   * @param cause - Valor a ser serializado.
+   * @param includeStack - Se `true` inclui o stack trace ao serializar
+   * erros. Por padrão, `false`.
+   * @returns Representação serializável do valor.
+   */
+  static serializeCauseError(cause: unknown, includeStack?: boolean): unknown;
+}
+//#endregion
+//#region src/functions/is-base-error.d.ts
+/**
+ * Símbolo usado como marca ("brand") para identificar instâncias de
+ * `BaseError` em tempo de execução.
+ *
+ * É criado com `Symbol.for` que consulta o registro global de símbolos. Assim
+ * mesmo que o pacote seja carregado mais de uma vez (ex.: versões duplicadas
+ * em `node_modules` ou diferentes bundles), todas as cópias compartilham o
+ * mesmo símbolo e {@link isBaseError} continua reconhecendo os erros, algo que
+ * `instanceof` sozinho não garante.
+ */
+declare const BASE_ERROR_BRAND: unique symbol;
+/**
+ * Verifica se um valor é uma instância de `BaseError` funcionando como um
+ * type guard.
+ *
+ * A checagem exige que o valor seja uma instância de `Error` e que possua a
+ * propriedade marcada por {@link BASE_ERROR_BRAND} com o valor `true`. Por
+ * usar a marca em vez de `instanceof BaseError`, o resultado é confiável
+ * mesmo quando há múltiplas cópias do pacote carregadas na mesma aplicação.
+ *
+ * @param value - Valor a ser verificado.
+ * @returns `true` se `value` for um `BaseError` (e nesse caso o TypeScript
+ * restringe o tipo para `BaseError`); caso contrário `false`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await execute();
+ * } catch (error) {
+ *   if (isBaseError(error)) {
+ *     console.log(error.code); // `error` é tipado como BaseError
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ *
+ * isBaseError(new Error("comum")); // false
+ * isBaseError("texto");            // false
+ * isBaseError(null);               // false
+ * ```
+ */
+declare function isBaseError(value: unknown): value is BaseError;
+//#endregion
+//#region src/functions/serialize-cause-error.d.ts
+/**
+ * Texto que substitui uma referência circular durante a serialização.
+ *
+ * É retornado no lugar de um objeto que já está sendo serializado mais acima
+ * na mesma cadeia evitando recursão infinita.
+ */
+declare const CIRCULAR_MARKER = "[Circular]";
+/**
+ * Conjunto de referências em processo de serialização usado para detectar
+ * ciclos.
+ *
+ * Por ser um `WeakSet` não impede que os objetos sejam coletados pelo
+ * garbage collector.
+ */
+type SeenReferences = WeakSet<object>;
+/**
+ * Serializa de forma segura, o valor de uma `cause` (causa) de erro para uma
+ * estrutura simples e apropriada para `JSON.stringify`, logs ou transmissão.
+ *
+ * A conversão depende do tipo do valor:
+ * - `string`, `number`, `boolean` e `undefined`: retornados sem alteração;
+ * - `null`: retorna `null`;
+ * - `bigint` e `symbol`: convertidos para texto com `toString()`
+ *   (ex.: `10n` vira `"10"`);
+ * - função: vira o texto `"[Function: nome]"` ou `"[Function: anonymous]"`
+ *   se não tiver nome;
+ * - `BaseError`: delegado a {@link serializeBaseError};
+ * - `Error` nativo: delegado a {@link serializeNativeError};
+ * - `Date`: convertida para string ISO 8601 ou `"Invalid Date"` se a data
+ *   for inválida;
+ * - array: cada item é serializado recursivamente;
+ * - objeto comum: cada propriedade própria enumerável de chave `string` é
+ *   serializada recursivamente, resultando em um novo objeto simples.
+ *
+ * **Referências circulares:** apenas as referências da cadeia atual (os
+ * "ancestrais" do valor sendo serializado) são rastreadas. Quando um objeto
+ * aparece dentro de si mesmo o ponto de repetição é substituído por
+ * {@link CIRCULAR_MARKER}. Como cada objeto é removido do conjunto ao terminar
+ * de ser serializado, um mesmo objeto referenciado em dois lugares distintos
+ * (sem ciclo) é serializado por completo nas duas ocorrências e não marcado
+ * como circular.
+ *
+ * **Limitações:** protótipos e métodos de objetos comuns são descartados e
+ * propriedades com chave `symbol` são ignoradas. Instâncias como `Map` e
+ * `Set`, que não possuem propriedades próprias enumeráveis resultam em `{}`.
+ *
+ * @param cause - Valor a ser serializado normalmente a propriedade `cause`
+ * de um erro, mas pode ser qualquer valor.
+ * @param includeStack - Se `true`, inclui o stack trace ao serializar erros
+ * (`BaseError` e `Error` nativo), repassando a opção aos respectivos
+ * serializadores. Por padrão, `false`.
+ * @param seen - Conjunto de referências em processo de serialização usado
+ * internamente na recursão para detectar ciclos. Em geral não deve ser
+ * informado; por padrão, um novo `WeakSet` vazio.
+ * @returns Representação serializável do valor cujo formato depende do tipo
+ * recebido (ver lista acima).
+ *
+ * @example
+ * ```ts
+ * serializeCauseError("falha");      // "falha"
+ * serializeCauseError(10n);          // "10"
+ * serializeCauseError(Symbol("x"));  // "Symbol(x)"
+ * serializeCauseError(function foo() {}); // "[Function: foo]"
+ * serializeCauseError(new Date("2026-01-01T00:00:00Z"));
+ * // "2026-01-01T00:00:00.000Z"
+ * serializeCauseError(new Date("inválida")); // "Invalid Date"
+ *
+ * // Estruturas aninhadas
+ * serializeCauseError({ ids: [1, 2n], origin: null });
+ * // { ids: [1, "2"], origin: null }
+ *
+ * // Referência circular
+ * const a: Record<string, unknown> = { name: "a" };
+ * a.self = a;
+ * serializeCauseError(a);
+ * // { name: "a", self: "[Circular]" }
+ *
+ * // Mesmo objeto em dois lugares (sem ciclo): serializado nas duas vezes
+ * const shared = { x: 1 };
+ * serializeCauseError({ a: shared, b: shared });
+ * // { a: { x: 1 }, b: { x: 1 } }
+ *
+ * // Erros, com stack trace opcional
+ * serializeCauseError(new Error("falhou"), true);
+ * ```
+ */
+declare function serializeCauseError(cause: unknown, includeStack?: boolean, seen?: SeenReferences): unknown;
+//#endregion
+//#region src/functions/serialize-base-error.d.ts
+/**
+ * Representação serializável de um `BaseError` composta apenas por valores
+ * simples e apropriada para `JSON.stringify`, logs ou transmissão.
+ *
+ * As propriedades `cause`, `params` e `stack` são opcionais e só aparecem
+ * quando o erro as possui (ou no caso de `stack` quando solicitado).
+ */
+type SerializedBaseError = Readonly<{
+  /** Causa do erro já serializada com {@link serializeCauseError}. */
+  cause?: unknown;
+  /** Código do erro conforme o catálogo (ex.: `"USER_NOT_FOUND"`). */
+  code: string;
+  /** Mensagem do erro já com os placeholders interpolados. */
+  message: string;
+  /** Nome da classe do erro (ex.: `"BaseError"`). */
+  name: string;
+  /** Parâmetros usados para interpolar a mensagem já serializados. */
+  params?: Readonly<Record<string, unknown>>;
+  /** Stack trace do erro presente apenas se `includeStack` for `true`. */
+  stack?: string;
+}>;
+/**
+ * Serializa um `BaseError` para um objeto simples ({@link SerializedBaseError})
+ * apropriado para `JSON.stringify`, logs ou transmissão.
+ *
+ * O resultado sempre contém `code`, `message` e `name`. As demais
+ * propriedades são incluídas apenas quando aplicável:
+ * - `cause`: se o erro tiver causa (`error.cause !== undefined`) serializada
+ *   com {@link serializeCauseError};
+ * - `params`: se o erro tiver parâmetros (`error.params !== undefined`)
+ *   também serializados com {@link serializeCauseError};
+ * - `stack`: somente se `includeStack` for `true`.
+ *
+ * **Referências circulares:** o erro é registrado em `seen` durante a
+ * serialização e removido ao final (mesmo se ocorrer uma exceção). Assim se
+ * alguma `cause` ou `params` apontar de volta para este mesmo erro, o ponto
+ * de repetição é substituído por `"[Circular]"` em vez de causar recursão
+ * infinita. Por ser removido ao terminar, o mesmo erro pode aparecer em
+ * lugares distintos (sem ciclo) e ser serializado por completo em cada um.
+ *
+ * @param error - `BaseError` a ser serializado.
+ * @param includeStack - Se `true` inclui o stack trace no resultado e o
+ * repassa à serialização da causa e dos parâmetros. Por padrão, `false`.
+ * @param seen - Conjunto de referências em processo de serialização usado
+ * internamente na recursão para detectar ciclos. Em geral não deve ser
+ * informado; por padrão, um novo `WeakSet` vazio.
+ * @returns Objeto serializável que representa o erro.
+ *
+ * @example
+ * ```ts
+ * const error = new BaseError(ERROR_CODES.USER_NOT_FOUND, { id: 42 });
+ *
+ * serializeBaseError(error);
+ * // {
+ * //   code: "USER_NOT_FOUND",
+ * //   message: "Usuário 42 não encontrado",
+ * //   name: "BaseError",
+ * //   params: { id: 42 },
+ * // }
+ *
+ * // Com stack trace
+ * serializeBaseError(erro, true);
+ * // { ..., stack: "BaseError: Usuário 42 não encontrado\n    at ..." }
+ *
+ * // Com causa
+ * const withCause = new BaseError(ERROR_CODES.INVALID_TOKEN, undefined, {
+ *   cause: new Error("expirado"),
+ * });
+ * serializeBaseError(withCause);
+ * // { cause: { ... }, code: "INVALID_TOKEN", message: "Token inválido", name: "BaseError" }
+ * ```
+ */
+declare function serializeBaseError(error: BaseError, includeStack?: boolean, seen?: SeenReferences): SerializedBaseError;
+//#endregion
+//#region src/functions/serialize-native-error.d.ts
+/**
+ * Representação serializável de um `Error` nativo (ou de uma subclasse que
+ * não seja `BaseError`), composta apenas por valores simples e apropriada para
+ * `JSON.stringify`, logs ou transmissão.
+ *
+ * As propriedades `cause`, `errors` e `stack` são opcionais e só aparecem
+ * quando o erro as possui (ou no caso de `stack` quando solicitado).
+ */
+type SerializedNativeError = Readonly<{
+  /** Causa do erro já serializada com {@link serializeCauseError}. */
+  cause?: unknown;
+  /**
+   * Lista de erros agregados já serializados. Presente em erros como
+   * `AggregateError` que expõem uma propriedade `errors` do tipo array.
+   */
+  errors?: readonly unknown[];
+  /** Mensagem do erro. */
+  message: string;
+  /** Nome do erro (ex.: `"Error"`, `"TypeError"`, `"AggregateError"`). */
+  name: string;
+  /** Stack trace do erro presente apenas se `includeStack` for `true`. */
+  stack?: string;
+}>;
+/**
+ * Serializa um `Error` nativo para um objeto simples
+ * ({@link SerializedNativeError}) apropriado para `JSON.stringify`, logs ou
+ * transmissão.
+ *
+ * O resultado sempre contém `message` e `name`. As demais propriedades são
+ * incluídas apenas quando aplicável:
+ * - `cause`: se o erro tiver causa (`error.cause !== undefined`) serializada
+ *   com {@link serializeCauseError};
+ * - `errors`: se o erro tiver uma propriedade `errors` que seja um array
+ *   (como em `AggregateError`) com cada item serializado com
+ *   {@link serializeCauseError};
+ * - `stack`: somente se `includeStack` for `true`.
+ *
+ * **Referências circulares:** o erro é registrado em `seen` durante a
+ * serialização e removido ao final (mesmo se ocorrer uma exceção). Assim se
+ * `cause` ou algum item de `errors` apontar de volta para este mesmo erro, o
+ * ponto de repetição é substituído por `"[Circular]"` em vez de causar
+ * recursão infinita. Por ser removido ao terminar, o mesmo erro pode aparecer
+ * em lugares distintos (sem ciclo) e ser serializado por completo em cada um.
+ *
+ * **Limitações:** apenas `message`, `name`, `cause`, `errors` e `stack` são
+ * copiados. Propriedades adicionais definidas em subclasses (ex.: `code` ou
+ * `status`) não são incluídas.
+ *
+ * @param error - `Error` a ser serializado.
+ * @param includeStack - Se `true` inclui o stack trace no resultado e o
+ * repassa à serialização da causa e dos erros agregados. Por padrão, `false`.
+ * @param seen - Conjunto de referências em processo de serialização usado
+ * internamente na recursão para detectar ciclos. Em geral não deve ser
+ * informado; por padrão, um novo `WeakSet` vazio.
+ * @returns Objeto serializável que representa o erro.
+ *
+ * @example
+ * ```ts
+ * serializeNativeError(new TypeError("valor inválido"));
+ * // { message: "valor inválido", name: "TypeError" }
+ *
+ * // Com stack trace
+ * serializeNativeError(new Error("falhou"), true);
+ * // { message: "falhou", name: "Error", stack: "Error: falhou\n    at ..." }
+ *
+ * // Com causa
+ * serializeNativeError(new Error("falhou", { cause: "timeout" }));
+ * // { cause: "timeout", message: "falhou", name: "Error" }
+ *
+ * // Com erros agregados
+ * serializeNativeError(
+ *   new AggregateError([new Error("a"), new Error("b")], "vários erros"),
+ * );
+ * // {
+ * //   errors: [
+ * //     { message: "a", name: "Error" },
+ * //     { message: "b", name: "Error" },
+ * //   ],
+ * //   message: "vários erros",
+ * //   name: "AggregateError",
+ * // }
+ *
+ * // Referência circular
+ * const error = new Error("ciclo");
+ * error.cause = error;
+ * serializeNativeError(error);
+ * // { cause: "[Circular]", message: "ciclo", name: "Error" }
+ * ```
+ */
+declare function serializeNativeError(error: Error, includeStack?: boolean, seen?: SeenReferences): SerializedNativeError;
+//#endregion
+export { CIRCULAR_MARKER as a, BASE_ERROR_BRAND as c, BaseErrorOptions as d, BaseErrorOptionsArgs as f, serializeBaseError as i, isBaseError as l, serializeNativeError as n, SeenReferences as o, escapeRegExp as p, SerializedBaseError as r, serializeCauseError as s, SerializedNativeError as t, BaseError as u };
+//# sourceMappingURL=index-B4tdSdCF.d.mts.map