@zudojs/rpc 0.1.0 → 1.0.0

package/dist/rpc/dispatcher/rpcDispatcher.core.js

@@ -1,38 +1,129 @@
 import { createRPCContext } from "../context/rpcContext.type.js";
 import { createRPCResponse } from "../types/rpcResponse.type.js";
-import { RPCProcedureNotFoundError, RPCValidationError, } from "../errors/rpc.errors.js";
+import { RPCCancelledError } from "../errors/rpc.errors.js";
+import { DEFAULT_RPC_TIMEOUT } from "../constants/rpcConstants.core.js";
+import { parseInput, parseOutput } from "../validation/rpcValidation.core.js";
+import { readDeadline, throwIfDeadlineExceeded, } from "../reliability/deadline/rpcDeadline.helper.js";
+import { createTimeout } from "../reliability/timeout/rpcTimeout.helper.js";
 /**
  * Dispatches RPC requests to registered procedures.
+ *
+ * Every dispatch runs under a real `AbortController`, a bounded timeout,
+ * and — when the procedure declares schemas — input and output
+ * validation. Errors keep their identity: an `RPCError` thrown by a
+ * middleware or handler propagates unchanged so the server can map it to
+ * the right response code, and only genuinely unexpected errors are
+ * wrapped.
  */
 export class RPCDispatcher {
     registry;
     middleware;
-    constructor(registry, middleware) {
+    options;
+    constructor(registry, middleware, options = {}) {
         this.registry = registry;
         this.middleware = middleware;
+        this.options = options;
     }
     /**
      * Dispatches an RPC request.
      */
     async dispatch(request) {
         const procedure = this.registry.require(request.procedure);
-        const signal = new AbortController().signal;
-        const context = createRPCContext(request, signal);
+        const controller = new AbortController();
+        const context = createRPCContext(request, controller.signal);
+        const timeoutMs = this.resolveTimeout(request, procedure);
+        // A deadline already in the past is rejected before any work runs.
+        if (this.options.honourDeadline ?? true) {
+            const deadline = readDeadline(request.metadata);
+            if (deadline !== undefined) {
+                throwIfDeadlineExceeded(deadline, request.procedure);
+            }
+        }
+        const timeout = timeoutMs > 0 ? createTimeout(timeoutMs, request.procedure) : undefined;
         try {
-            const result = await this.middleware.execute(context, async () => {
-                return procedure.handler(request.payload, context);
-            });
+            const run = async () => {
+                const input = procedure.options?.input
+                    ? parseInput(procedure.options.input, request.payload, request.procedure)
+                    : request.payload;
+                const result = await this.middleware.execute(context, async () => {
+                    return procedure.handler(input, context);
+                });
+                return procedure.options?.output
+                    ? parseOutput(procedure.options.output, result, request.procedure)
+                    : result;
+            };
+            const invoke = () => this.applyInterceptors(context, run);
+            const result = timeout === undefined
+                ? await invoke()
+                : await Promise.race([
+                    invoke(),
+                    timeout.promise.catch((error) => {
+                        // Abort first so a cooperative handler stops working
+                        // instead of running on with its result discarded.
+                        if (!controller.signal.aborted) {
+                            controller.abort(error);
+                        }
+                        throw error;
+                    }),
+                ]);
             return createRPCResponse(request.id, result);
         }
-        catch (error) {
-            if (error instanceof RPCProcedureNotFoundError) {
-                throw error;
+        finally {
+            // Errors propagate unchanged. Rewriting them here is what turned
+            // an auth failure or a rate limit into a generic internal fault;
+            // the server owns the mapping from error type to response code.
+            timeout?.cancel();
+            if (!controller.signal.aborted) {
+                // Release anything still listening on the request signal.
+                controller.abort(new RPCCancelledError("Request completed.", request.procedure));
             }
-            if (error instanceof RPCValidationError) {
-                throw error;
+        }
+    }
+    /**
+     * Runs the interceptor chain around the dispatch.
+     *
+     * Each interceptor may call `next()` once; a second call throws rather
+     * than re-running the handler.
+     */
+    async applyInterceptors(context, run) {
+        const interceptors = this.options.interceptors;
+        if (!interceptors || interceptors.length === 0) {
+            return run();
+        }
+        const called = new Set();
+        const runAt = async (index) => {
+            if (called.has(index)) {
+                throw new Error(`RPC interceptor at index ${index - 1} called next() more than once.`);
+            }
+            called.add(index);
+            if (index >= interceptors.length) {
+                return run();
+            }
+            const interceptor = interceptors[index];
+            return interceptor.intercept(context, () => runAt(index + 1));
+        };
+        return runAt(0);
+    }
+    /**
+     * Resolves the timeout for a dispatch.
+     *
+     * A `deadline` in request metadata can only shorten the timeout, never
+     * extend it past what the procedure allows.
+     */
+    resolveTimeout(request, procedure) {
+        const configured = procedure.options?.timeout ??
+            this.options.defaultTimeout ??
+            DEFAULT_RPC_TIMEOUT;
+        if (configured <= 0) {
+            return 0;
+        }
+        if (this.options.honourDeadline ?? true) {
+            const deadline = readDeadline(request.metadata);
+            if (deadline !== undefined) {
+                return Math.max(1, Math.min(configured, deadline - Date.now()));
             }
-            throw new Error(`Handler for procedure "${request.procedure}" threw: ${String(error)}`);
         }
+        return configured;
     }
 }
 //# sourceMappingURL=rpcDispatcher.core.js.map

package/dist/rpc/middleware/rpcMiddleware.core.d.ts

@@ -9,8 +9,20 @@ export type RPCMiddleware = (context: RPCContext, next: () => Promise<unknown>)
 export declare class RPCMiddlewareStack {
     private readonly middleware;
     constructor(middleware?: RPCMiddleware[]);
+    /**
+     * Number of middleware in the stack.
+     */
+    get size(): number;
+    /**
+     * Returns a new stack with additional middleware appended.
+     */
+    with(...middleware: RPCMiddleware[]): RPCMiddlewareStack;
     /**
      * Executes the middleware stack around the given handler.
+     *
+     * Each middleware may call `next()` exactly once. A second call throws
+     * rather than silently re-entering the chain, which would run the
+     * handler — and every middleware below it — twice.
      */
     execute(context: RPCContext, handler: () => Promise<unknown>): Promise<unknown>;
 }

package/dist/rpc/middleware/rpcMiddleware.core.js

@@ -1,29 +1,52 @@
+import { MAX_MIDDLEWARE } from "../constants/rpcConstants.core.js";
 /**
  * Stack of RPC middleware.
  */
 export class RPCMiddlewareStack {
     middleware;
     constructor(middleware = []) {
+        if (middleware.length > MAX_MIDDLEWARE) {
+            throw new RangeError(`An RPC middleware stack may hold at most ${MAX_MIDDLEWARE} entries; received ${middleware.length}.`);
+        }
         this.middleware = Object.freeze([...middleware]);
     }
+    /**
+     * Number of middleware in the stack.
+     */
+    get size() {
+        return this.middleware.length;
+    }
+    /**
+     * Returns a new stack with additional middleware appended.
+     */
+    with(...middleware) {
+        return new RPCMiddlewareStack([...this.middleware, ...middleware]);
+    }
     /**
      * Executes the middleware stack around the given handler.
+     *
+     * Each middleware may call `next()` exactly once. A second call throws
+     * rather than silently re-entering the chain, which would run the
+     * handler — and every middleware below it — twice.
      */
     async execute(context, handler) {
         const stack = this.middleware;
-        let index = 0;
-        const runNext = async () => {
+        const called = new Set();
+        const runAt = async (index) => {
+            if (called.has(index)) {
+                throw new Error(`RPC middleware at index ${index - 1} called next() more than once.`);
+            }
+            called.add(index);
             if (index >= stack.length) {
                 return handler();
             }
             const mw = stack[index];
-            index += 1;
             if (!mw) {
-                return handler();
+                return runAt(index + 1);
             }
-            return mw(context, runNext);
+            return mw(context, () => runAt(index + 1));
         };
-        return runNext();
+        return runAt(0);
     }
 }
 //# sourceMappingURL=rpcMiddleware.core.js.map

package/dist/rpc/procedure/rpcProcedure.type.d.ts

@@ -1,5 +1,6 @@
 import type { RPCProcedureName } from "../types/rpcProcedureName.type.js";
 import type { RPCContext } from "../context/rpcContext.type.js";
+import type { RPCSchema } from "../validation/rpcValidation.core.js";
 /**
  * Handler for an RPC procedure.
  */
@@ -7,10 +8,31 @@ export type RPCHandler<TInput = unknown, TOutput = unknown> = (input: TInput, co
 /**
  * Options for an RPC procedure.
  */
-export interface RPCProcedureOptions {
+export interface RPCProcedureOptions<TInput = unknown, TOutput = unknown> {
+    /**
+     * Whether calling this procedure more than once is safe.
+     *
+     * Advisory: the server does not deduplicate or auto-retry on this
+     * flag. It is exposed through the registry so a caller's retry policy
+     * can consult it before replaying a failed call.
+     */
     readonly idempotent?: boolean;
+    /**
+     * Maximum time the handler may run, in milliseconds. Enforced by the
+     * dispatcher, which aborts the context signal when it elapses.
+     */
     readonly timeout?: number;
+    /** Human-readable description, surfaced by registry introspection. */
     readonly description?: string;
+    /**
+     * Schema the request payload is parsed against before the handler
+     * runs. Without one, the handler receives the raw untrusted payload.
+     */
+    readonly input?: RPCSchema<TInput>;
+    /**
+     * Schema the handler's result is checked against before it is sent.
+     */
+    readonly output?: RPCSchema<TOutput>;
 }
 /**
  * An RPC procedure definition.
@@ -18,10 +40,10 @@ export interface RPCProcedureOptions {
 export interface RPCProcedure<TInput = unknown, TOutput = unknown> {
     readonly name: RPCProcedureName;
     readonly handler: RPCHandler<TInput, TOutput>;
-    readonly options?: RPCProcedureOptions;
+    readonly options?: RPCProcedureOptions<TInput, TOutput>;
 }
 /**
  * Creates a new RPC procedure.
  */
-export declare function createRPCProcedure<TInput = unknown, TOutput = unknown>(name: RPCProcedureName, handler: RPCHandler<TInput, TOutput>, options?: RPCProcedureOptions): RPCProcedure<TInput, TOutput>;
+export declare function createRPCProcedure<TInput = unknown, TOutput = unknown>(name: RPCProcedureName, handler: RPCHandler<TInput, TOutput>, options?: RPCProcedureOptions<TInput, TOutput>): RPCProcedure<TInput, TOutput>;
 //# sourceMappingURL=rpcProcedure.type.d.ts.map

package/dist/rpc/procedure/rpcProcedure.type.js

@@ -1,7 +1,16 @@
+import { assertValidProcedureName } from "../validation/rpcValidation.core.js";
 /**
  * Creates a new RPC procedure.
  */
 export function createRPCProcedure(name, handler, options = {}) {
+    // Names are validated at definition time so a malformed name is a
+    // startup error rather than a request that can never be routed.
+    assertValidProcedureName(name);
+    if (options.timeout !== undefined) {
+        if (!Number.isFinite(options.timeout) || options.timeout <= 0) {
+            throw new TypeError(`Procedure "${name}" declares a non-positive timeout.`);
+        }
+    }
     return Object.freeze({
         name,
         handler,

package/dist/rpc/procedure/rpcProcedureRegistry.core.d.ts

@@ -11,7 +11,7 @@ export declare class RPCProcedureRegistry {
      *
      * @throws {RPCDuplicateProcedureError} if a procedure with the same name is already registered.
      */
-    register(procedure: RPCProcedure): void;
+    register<TInput = unknown, TOutput = unknown>(procedure: RPCProcedure<TInput, TOutput>): void;
     /**
      * Retrieves a procedure by name.
      */
@@ -28,6 +28,20 @@ export declare class RPCProcedureRegistry {
      * Returns all registered procedure names.
      */
     list(): readonly string[];
+    /**
+     * Describes every registered procedure.
+     *
+     * Surfaces the `description` and `idempotent` options, which are
+     * otherwise carried on the procedure and never readable — a caller's
+     * retry policy needs `idempotent` to decide whether replaying a failed
+     * call is safe.
+     */
+    describe(): readonly {
+        name: string;
+        description?: string;
+        idempotent: boolean;
+        timeout?: number;
+    }[];
     /**
      * Unregisters a procedure.
      */

package/dist/rpc/procedure/rpcProcedureRegistry.core.js

@@ -1,5 +1,6 @@
 import { RPCDuplicateProcedureError, RPCProcedureNotFoundError, } from "../errors/rpc.errors.js";
 import { MAX_PROCEDURES } from "../constants/rpcConstants.core.js";
+import { assertValidProcedureName } from "../validation/rpcValidation.core.js";
 /**
  * Registry for RPC procedures.
  *
@@ -14,12 +15,16 @@ export class RPCProcedureRegistry {
      */
     register(procedure) {
         if (this.procedures.size >= MAX_PROCEDURES) {
-            throw new Error(`Maximum number of procedures (${MAX_PROCEDURES}) exceeded.`);
+            throw new RangeError(`Maximum number of procedures (${MAX_PROCEDURES}) exceeded.`);
         }
+        assertValidProcedureName(procedure.name);
         const existing = this.procedures.get(procedure.name);
         if (existing !== undefined) {
             throw new RPCDuplicateProcedureError(procedure.name);
         }
+        // Stored erased. The dispatcher decodes the wire payload at runtime,
+        // so the registry holds procedures of mixed input types; the cast is
+        // the single point where that erasure is acknowledged.
         this.procedures.set(procedure.name, Object.freeze(procedure));
     }
     /**
@@ -50,6 +55,26 @@ export class RPCProcedureRegistry {
     list() {
         return Array.from(this.procedures.keys());
     }
+    /**
+     * Describes every registered procedure.
+     *
+     * Surfaces the `description` and `idempotent` options, which are
+     * otherwise carried on the procedure and never readable — a caller's
+     * retry policy needs `idempotent` to decide whether replaying a failed
+     * call is safe.
+     */
+    describe() {
+        return Array.from(this.procedures.values()).map((procedure) => ({
+            name: procedure.name,
+            ...(procedure.options?.description !== undefined
+                ? { description: procedure.options.description }
+                : {}),
+            idempotent: procedure.options?.idempotent ?? false,
+            ...(procedure.options?.timeout !== undefined
+                ? { timeout: procedure.options.timeout }
+                : {}),
+        }));
+    }
     /**
      * Unregisters a procedure.
      */

package/dist/rpc/procedure/rpcProcedureRouter.core.d.ts

@@ -8,7 +8,7 @@ export declare class RPCProcedureRouter {
     /**
      * Registers a procedure in this router.
      */
-    register(procedure: RPCProcedure): this;
+    register<TInput = unknown, TOutput = unknown>(procedure: RPCProcedure<TInput, TOutput>): this;
     /**
      * Retrieves a procedure by name.
      */

package/dist/rpc/procedure/rpcProcedureRouter.core.js

@@ -1,4 +1,5 @@
 import { RPCDuplicateProcedureError, RPCProcedureNotFoundError, } from "../errors/rpc.errors.js";
+import { assertValidProcedureName } from "../validation/rpcValidation.core.js";
 /**
  * Router for grouping RPC procedures by namespace.
  */
@@ -8,10 +9,14 @@ export class RPCProcedureRouter {
      * Registers a procedure in this router.
      */
     register(procedure) {
+        assertValidProcedureName(procedure.name);
         const existing = this.routes.get(procedure.name);
         if (existing !== undefined) {
             throw new RPCDuplicateProcedureError(procedure.name);
         }
+        // Stored erased. The dispatcher decodes the wire payload at runtime,
+        // so the registry holds procedures of mixed input types; the cast is
+        // the single point where that erasure is acknowledged.
         this.routes.set(procedure.name, Object.freeze(procedure));
         return this;
     }

package/dist/rpc/reliability/cancellation/rpcCancellation.helper.d.ts

@@ -3,12 +3,39 @@
  *
  * Cancellation utilities for RPC operations.
  */
+/**
+ * A signal paired with the means to abort it.
+ *
+ * An `AbortSignal` on its own cannot be aborted — only the controller
+ * that owns it can. Returning the pair keeps that capability reachable.
+ */
+export interface CancellableSignal {
+    readonly signal: AbortSignal;
+    /** Aborts the signal. Calling it more than once is a no-op. */
+    cancel(reason?: unknown): void;
+}
 /**
  * Creates an AbortSignal that can be triggered manually.
  */
-export declare function createCancellableSignal(): AbortSignal;
+export declare function createCancellableSignal(): CancellableSignal;
+/**
+ * Cancels a cancellable signal.
+ */
+export declare function cancelSignal(cancellable: CancellableSignal, reason?: unknown): void;
 /**
- * Cancels an AbortSignal by aborting its controller.
+ * Throws if the signal has been aborted.
+ *
+ * Use at cooperative cancellation points inside a handler.
+ */
+export declare function throwIfCancelled(signal: AbortSignal, procedureName?: string): void;
+/**
+ * Combines several signals into one that aborts with the first of them.
+ *
+ * The returned object must be disposed to detach its listeners; leaving
+ * them attached would keep every source signal referenced.
  */
-export declare function cancelSignal(signal: AbortSignal): void;
+export declare function combineSignals(...signals: readonly (AbortSignal | undefined)[]): {
+    readonly signal: AbortSignal;
+    dispose(): void;
+};
 //# sourceMappingURL=rpcCancellation.helper.d.ts.map

package/dist/rpc/reliability/cancellation/rpcCancellation.helper.js

@@ -3,19 +3,75 @@
  *
  * Cancellation utilities for RPC operations.
  */
+import { RPCCancelledError } from "../../errors/rpc.errors.js";
 /**
  * Creates an AbortSignal that can be triggered manually.
  */
 export function createCancellableSignal() {
     const controller = new AbortController();
-    return controller.signal;
+    return {
+        signal: controller.signal,
+        cancel(reason) {
+            if (controller.signal.aborted) {
+                return;
+            }
+            controller.abort(reason ?? new RPCCancelledError());
+        },
+    };
 }
 /**
- * Cancels an AbortSignal by aborting its controller.
+ * Cancels a cancellable signal.
  */
-export function cancelSignal(signal) {
+export function cancelSignal(cancellable, reason) {
+    cancellable.cancel(reason);
+}
+/**
+ * Throws if the signal has been aborted.
+ *
+ * Use at cooperative cancellation points inside a handler.
+ */
+export function throwIfCancelled(signal, procedureName) {
     if (!signal.aborted) {
-        signal.abort();
+        return;
+    }
+    const reason = signal.reason;
+    if (reason instanceof Error) {
+        throw reason;
+    }
+    throw new RPCCancelledError(typeof reason === "string" ? reason : undefined, procedureName);
+}
+/**
+ * Combines several signals into one that aborts with the first of them.
+ *
+ * The returned object must be disposed to detach its listeners; leaving
+ * them attached would keep every source signal referenced.
+ */
+export function combineSignals(...signals) {
+    const present = signals.filter((signal) => signal !== undefined);
+    const controller = new AbortController();
+    const detach = [];
+    const abort = (reason) => {
+        if (!controller.signal.aborted) {
+            controller.abort(reason);
+        }
+    };
+    for (const source of present) {
+        if (source.aborted) {
+            abort(source.reason);
+            break;
+        }
+        const listener = () => abort(source.reason);
+        source.addEventListener("abort", listener, { once: true });
+        detach.push(() => source.removeEventListener("abort", listener));
     }
+    return {
+        signal: controller.signal,
+        dispose() {
+            for (const remove of detach) {
+                remove();
+            }
+            detach.length = 0;
+        },
+    };
 }
 //# sourceMappingURL=rpcCancellation.helper.js.map

package/dist/rpc/reliability/deadline/rpcDeadline.helper.d.ts

@@ -13,6 +13,19 @@ export declare function getRemainingTime(deadline: number): number;
 export declare function isDeadlineExceeded(deadline: number): boolean;
 /**
  * Throws if the deadline has been exceeded.
+ *
+ * Throws the typed `RPCDeadlineExceededError` so callers and the server's
+ * error mapping can recognise it, rather than a bare `Error`.
+ */
+export declare function throwIfDeadlineExceeded(deadline: number, procedureName?: string): void;
+/**
+ * Reads a deadline from request metadata.
+ *
+ * Returns `undefined` when absent or not a usable epoch milliseconds
+ * value, so a malformed deadline is ignored rather than treated as
+ * already expired.
  */
-export declare function throwIfDeadlineExceeded(deadline: number): void;
+export declare function readDeadline(metadata: {
+    readonly deadline?: unknown;
+}): number | undefined;
 //# sourceMappingURL=rpcDeadline.helper.d.ts.map

package/dist/rpc/reliability/deadline/rpcDeadline.helper.js

@@ -3,6 +3,7 @@
  *
  * Deadline utilities for RPC operations.
  */
+import { RPCDeadlineExceededError } from "../../errors/rpc.errors.js";
 /**
  * Calculates the remaining time until a deadline.
  */
@@ -18,10 +19,30 @@ export function isDeadlineExceeded(deadline) {
 }
 /**
  * Throws if the deadline has been exceeded.
+ *
+ * Throws the typed `RPCDeadlineExceededError` so callers and the server's
+ * error mapping can recognise it, rather than a bare `Error`.
  */
-export function throwIfDeadlineExceeded(deadline) {
+export function throwIfDeadlineExceeded(deadline, procedureName) {
     if (isDeadlineExceeded(deadline)) {
-        throw new Error("Deadline exceeded.");
+        throw new RPCDeadlineExceededError(deadline, procedureName);
+    }
+}
+/**
+ * Reads a deadline from request metadata.
+ *
+ * Returns `undefined` when absent or not a usable epoch milliseconds
+ * value, so a malformed deadline is ignored rather than treated as
+ * already expired.
+ */
+export function readDeadline(metadata) {
+    const deadline = metadata.deadline;
+    if (typeof deadline !== "number" || !Number.isFinite(deadline)) {
+        return undefined;
+    }
+    if (deadline <= 0) {
+        return undefined;
     }
+    return deadline;
 }
 //# sourceMappingURL=rpcDeadline.helper.js.map

package/dist/rpc/reliability/index.d.ts

@@ -1,6 +1,7 @@
-export { createTimeout, withTimeout } from "./timeout/rpcTimeout.helper.js";
-export { getRemainingTime, isDeadlineExceeded, throwIfDeadlineExceeded, } from "./deadline/rpcDeadline.helper.js";
-export { createCancellableSignal, cancelSignal, } from "./cancellation/rpcCancellation.helper.js";
-export type { RPCBackoff, RPCRetryOptions } from "./retry/rpcRetry.helper.js";
+export { createTimeout, withTimeout, runWithTimeout, } from "./timeout/rpcTimeout.helper.js";
+export { getRemainingTime, isDeadlineExceeded, throwIfDeadlineExceeded, readDeadline, } from "./deadline/rpcDeadline.helper.js";
+export type { CancellableSignal } from "./cancellation/rpcCancellation.helper.js";
+export { createCancellableSignal, cancelSignal, throwIfCancelled, combineSignals, } from "./cancellation/rpcCancellation.helper.js";
+export type { RPCBackoff, RPCJitter, RPCRetryOptions, } from "./retry/rpcRetry.helper.js";
 export { DEFAULT_RETRY_OPTIONS, calculateRetryDelay, retry, } from "./retry/rpcRetry.helper.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/rpc/reliability/index.js

@@ -1,5 +1,5 @@
-export { createTimeout, withTimeout } from "./timeout/rpcTimeout.helper.js";
-export { getRemainingTime, isDeadlineExceeded, throwIfDeadlineExceeded, } from "./deadline/rpcDeadline.helper.js";
-export { createCancellableSignal, cancelSignal, } from "./cancellation/rpcCancellation.helper.js";
+export { createTimeout, withTimeout, runWithTimeout, } from "./timeout/rpcTimeout.helper.js";
+export { getRemainingTime, isDeadlineExceeded, throwIfDeadlineExceeded, readDeadline, } from "./deadline/rpcDeadline.helper.js";
+export { createCancellableSignal, cancelSignal, throwIfCancelled, combineSignals, } from "./cancellation/rpcCancellation.helper.js";
 export { DEFAULT_RETRY_OPTIONS, calculateRetryDelay, retry, } from "./retry/rpcRetry.helper.js";
 //# sourceMappingURL=index.js.map

package/dist/rpc/reliability/retry/rpcRetry.helper.d.ts

@@ -7,6 +7,10 @@
  * Retry backoff strategies.
  */
 export type RPCBackoff = "fixed" | "linear" | "exponential";
+/**
+ * Randomisation applied to a computed retry delay.
+ */
+export type RPCJitter = "none" | "full" | "equal";
 /**
  * Retry options.
  */
@@ -15,7 +19,17 @@ export interface RPCRetryOptions {
     readonly delay: number;
     readonly maxDelay?: number;
     readonly backoff?: RPCBackoff;
+    /**
+     * Randomisation applied to each delay. Defaults to `"full"`, which
+     * spreads retries over `[0, delay]`. Without jitter every client
+     * retrying the same failed dependency retries at the same instant.
+     */
+    readonly jitter?: RPCJitter;
     readonly retryIf?: (error: unknown) => boolean;
+    /** Aborts the retry sequence, including while waiting between tries. */
+    readonly signal?: AbortSignal;
+    /** Invoked before each delay, for logging and metrics. */
+    readonly onRetry?: (error: unknown, attempt: number, delay: number) => void;
 }
 /**
  * Default retry options.
@@ -23,10 +37,18 @@ export interface RPCRetryOptions {
 export declare const DEFAULT_RETRY_OPTIONS: RPCRetryOptions;
 /**
  * Calculates the delay for a retry attempt.
+ *
+ * The result is finite, non-negative, and no greater than a timer can
+ * represent. Jitter defaults to `"none"` here so the calculation stays
+ * predictable for callers that compose it; {@link retry} opts into
+ * `"full"` jitter by default.
  */
 export declare function calculateRetryDelay(attempt: number, options: RPCRetryOptions): number;
 /**
  * Retries an asynchronous operation.
+ *
+ * Jitter defaults to `"full"` so concurrent callers retrying the same
+ * failing dependency do not synchronise into a retry wave.
  */
 export declare function retry<T>(operation: () => Promise<T>, options: RPCRetryOptions): Promise<T>;
 //# sourceMappingURL=rpcRetry.helper.d.ts.map