/** * vapor-chamber - the error code registry: every code the library returns or * reports, with its severity, its retry class and its fix. It holds no bus * state, so it sits in the foundation beside failure.ts, where the reporter * reads a code's fix in development. */ import type { BusSeverity } from './command-bus'; /** The errors page: a failure's RFC 9457 `type` and a report's docs link end in its condition. */ export declare const ERRORS_PAGE = "https://github.com/lucianofedericopereira/vapor-chamber/blob/main/docs/errors.md#"; /** * Error code definition - every BusError code has a structured entry. * Useful for generating documentation, i18n lookups, and LLM error handling. */ export type ErrorCodeEntry = { /** `owner:condition:subject`; the owner is the code's first part. */ code: string; /** The level a logger defaults to for this code; the logger decides. */ severity: BusSeverity; /** * Whether the code's condition is transient by the retry rule * (`retryClass`): `limited`, `timeout`, except a transport's own timeout, * which got no reply and may have landed. The async bus re-sends such a * failure only when the call it retries (a handler, a transport) produced * it: a plugin's refusal (`rateLimit:limited:action`) sits outside that * call and is never re-sent (tests/retryable-column.test.ts). An uncertain condition reads * false here and is re-sent only for an idempotent action or a keyed * command. An outcome of the rule, not a judgement per row * (tests/schema.test.ts). */ retryable: boolean; /** Broad failure category for filtering, telemetry, and LLM error handling. */ category: 'general' | 'network' | 'validation' | 'internal' | 'logic'; message: string; /** Human-readable fix suggestion for LLMs and developers. */ fix: string; }; /** * Complete registry of all BusError codes with their metadata. * This is the single source of truth for error documentation. * * @example * import { ERROR_CODE_REGISTRY } from 'vapor-chamber'; * // Lookup an error code * const entry = ERROR_CODE_REGISTRY.find(e => e.code === 'core:missing:handler'); * console.log(entry?.fix); // "Register a handler with bus.register(action, handler)" * * @example * // Generate an LLM system prompt with all error codes * const prompt = ERROR_CODE_REGISTRY * .map(e => `${e.code} (${e.severity}): ${e.message} -> Fix: ${e.fix}`) * .join('\n'); */ export declare const ERROR_CODE_REGISTRY: readonly ErrorCodeEntry[]; /** * Get the error registry entry for a BusError code. * * @example * if (result.error instanceof BusError) { * const entry = getErrorEntry(result.error.code); * console.log(entry?.fix); // actionable fix suggestion * } */ export declare function getErrorEntry(code: string): ErrorCodeEntry | undefined; /** * Is this BusError code a transient (retryable) failure? Consults the registry. * Returns undefined for codes not in ERROR_CODE_REGISTRY. * * @example * if (result.error instanceof BusError && isRetryableCode(result.error.code) === false) { * // permanent failure - don't re-dispatch * } */ export declare function isRetryableCode(code: string): boolean | undefined; /** * Describe all error codes as plain text - useful for LLM system prompts. * * @example * const systemPrompt = `When the bus returns an error, use this table:\n${describeErrorCodes()}`; */ export declare function describeErrorCodes(): string; //# sourceMappingURL=error-registry.d.ts.map