/** * What went wrong, from a closed vocabulary the library owns (docs/contract.md 3). The * retry policy and a logger read it; a receiver that has never seen a code * still knows its condition. `unauthenticated` and `conflict` are the two * distinctions gRPC's canonical codes draw that `refused` and `already` hid * (sign in, then retry; the state changed underneath); the 1:1 table against * gRPC is docs/contract.md 3. */ export type Condition = 'missing' | 'already' | 'conflict' | 'invalid' | 'refused' | 'unauthenticated' | 'limited' | 'timeout' | 'lost' | 'aborted' | 'exceeded' | 'failed' | 'unexpected' | 'unknown'; /** What a site passes: `condition:subject`. The owner is the wiring's (docs/contract.md 5). */ export type FailCode = `${Condition}:${string}`; /** * A whole code, `owner:condition:subject`: who raised it (set by the wiring, * never by the site), what went wrong, and what it is about. * * @example * if (result.error instanceof BusError) { * switch (result.error.code) { * case 'core:missing:handler': // register a handler * case 'authGuard:unauthenticated:action': // a rule refused it * case 'circuitBreaker:limited:action': // the circuit is open * } * } */ export type BusErrorCode = `${string}:${Condition}:${string}`; export type FailOptions = { action?: string; context?: Record; cause?: unknown; }; /** A failure factory bound to its owner. A party only ever holds its own. */ export type Fail = (code: FailCode, message: string, opts?: FailOptions) => BusError; /** * BusError - a failure the library, a plugin or a transport raised. * * Extends native Error so it works everywhere errors work (catch, result.error). * `code` is `owner:condition:subject`; `ownerOf()` and `conditionOf()` read its * parts. Severity is not on it: whoever logs a failure decides how loud it is * (the catalogue's `severity` is the suggested level). * * @example * const result = bus.dispatch('missing', {}); * if (!result.ok && result.error instanceof BusError) { * console.log(result.error.code); // 'core:missing:handler' * console.log(conditionOf(result.error)); // 'missing' * console.log(result.error.action); // 'missing' * } */ export declare class BusError extends Error { #private; /** The action name involved (if applicable). */ readonly action?: string; /** Every value the message carries, and whatever else a reader inspects. */ readonly context?: Record; constructor(code: FailCode, message: string, opts?: FailOptions); /** `owner:condition:subject`, read-only. */ get code(): BusErrorCode; /** * The failure as an RFC 9457 problem, with the members it needs * (docs/contract.md rule 3): `type`, `detail`, and `code`, `action` and the context as * extensions. `type` names the condition, a URI that resolves to its section * of docs/errors.md, because an RFC client identifies a problem by `type` * and ignores extensions it does not know (RFC 9457 3.1.1, 3.2); the exact * identity stays `code`. A backend's problem keeps the `type` it sent (its * own identity, read into `context` by the transports). No `title`: optional * in the RFC, and the summaries live in ERROR_CODE_REGISTRY, not in the * core. The transports' reader reads this shape back, so a failure crossing * a worker, a channel or storage has one shape both ways. * tests/problem-type.test.ts. */ toJSON(): Record; } /** @internal - a failure factory for `owner`. The bus hands each party its own. */ export declare const _failures: (owner: string) => Fail; /** The party that raised `e`, or `undefined` when `e` is not a BusError. */ export declare const ownerOf: (e: unknown) => string | undefined; /** A failure's condition, or `undefined` for anything the library did not raise. */ export declare const conditionOf: (e: unknown) => Condition | undefined; /** * The condition a status declares (the status table, docs/contract.md 4), saying only * what RFC 9110 says of it, plus 419 (Laravel's expired CSRF token). Every * reader of a backend's answer maps a status through it, here beside the * failure so the http client reads it without the bus. * 401 and 419 are `unauthenticated` (a session or token to renew, then the * same request); 403 is `refused` (final). 409 Conflict and 412 Precondition * Failed are `conflict` (the target's state is not the one the request * assumed), not `already`. */ export declare function conditionOfStatus(status: number): Condition; /** * @internal - a party's own `failed` (a plugin that threw): a bug, which a * re-send would repeat and which says nothing about the other side. A * backend's (`remote`) is not one; neither is a raw throw from a handler. */ export declare const _isBug: (e: unknown) => boolean; /** * @internal - the caller's cancel: a failure named `AbortError`, or the * command's own abort reason itself. The second is the platform's rule: * `throwIfAborted()` and Fetch reject with `signal.reason`, and the bus * returns an Error reason as itself. Identity, so a real failure that lands * after an abort still counts. tests/abort-custom-reason.test.ts. */ export declare const _isCancel: (e: unknown, signal?: AbortSignal) => boolean; /** * The one retry rule's reading of a failure (docs/contract.md 4), for the bus and the * http client alike: `transient` (held back, or a 408: the server never got * the whole request) may be sent again for any request; `uncertain` (the * first attempt may have landed: no reply, a gateway's 502 or 504, an * off-protocol answer, a backend's own failure) only for one that is * identified, safe to send twice; `final` (a verdict, an abort, a bound, a * party's bug) never. A declared wait is read by the caller: it sets when, * never whether (RFC 9110 10.2.3). Log s35.131, s35.162. */ export declare function retryClass(e: unknown, condition?: Condition | undefined): 'transient' | 'uncertain' | 'final'; /** @internal - attempts in total, the first included: the async bus's default `maxAttempts`, the http client's own. */ export declare const _RETRY_ATTEMPTS = 3; /** @internal - the retry's base and cap in ms: the async bus's default `baseDelay` and `maxDelay`, the http client's own. */ export declare const _RETRY_BASE_MS = 200; export declare const _RETRY_MAX_MS = 20000; /** * @internal - the one retry schedule's wait before re-send `n` (0 for the * first): full jitter, uniform under `base * 2^n`, capped at `max`, so * clients that failed together do not come back together (docs/retry.md). * The async bus's retry and the http client both wait it * (tests/http-retry-schedule.test.ts). */ export declare function _backoff(n: number, base?: number, max?: number): number; /** * @internal - a failure the retry rule did not re-send because nothing * identifies its request (no idempotency key, not declared idempotent, not * an idempotent method). Called only while retries were on and attempts * left. It acts when the failure got no reply or `declared` a wait, and * otherwise does nothing. No reply: marked `outcome: 'unknown'`, since it * may have landed. A declared wait on a verdict: not marked, the condition * already says not applied. DEV warns once per subject (`action`, or * `action` as a method with `url`) and cause. Log s35.162. */ export declare function _heldBack(e: unknown, declared: unknown, action: string, url?: string): void; //# sourceMappingURL=failure.d.ts.map