@orpc/server 1.14.10 → 1.14.11

package/dist/plugins/index.d.ts

@@ -1,204 +1,297 @@
 import { Value, Promisable, ThrowableError } from '@orpc/shared';
-import { StandardRequest, StandardHeaders } from '@orpc/standard-server';
-import { BatchResponseBodyItem } from '@orpc/standard-server/batch';
-import { C as Context, d as ProcedureClientInterceptorOptions } from '../shared/server.qKsRrdxW.js';
-import { d as StandardHandlerInterceptorOptions, g as StandardHandlerPlugin, e as StandardHandlerOptions } from '../shared/server.7cEtMB30.js';
-import { Meta, ORPCError as ORPCError$1 } from '@orpc/contract';
-import { ORPCError } from '@orpc/client';
+import { StandardLazyRequest, StandardHeaders } from '@standardserver/core';
+import { C as Context } from '../shared/server.CcR4kgje.js';
+import { e as StandardHandlerPlugin, f as StandardHandlerRoutingInterceptorOptions, a as StandardHandlerOptions, g as StandardHandlerInterceptorOptions } from '../shared/server.BhsVw7m7.js';
+import '@orpc/client';
+import '@orpc/contract';
 
-interface BatchHandlerOptions<T extends Context> {
+interface BatchHandlerPluginOptions<T extends Context> {
     /**
      * The max size of the batch allowed.
      *
      * @default 10
      */
-    maxSize?: Value<Promisable<number>, [StandardHandlerInterceptorOptions<T>]>;
+    maxSize?: Value<Promisable<number>, [options: StandardHandlerRoutingInterceptorOptions<T>]>;
     /**
-     * Map the request before processing it.
+     * Map each subrequest in the batch before it is processed.
      *
-     * @default merged back batch request headers into the request
+     * @default merges the batch request headers into the subrequest and remove `orpc-batch` header to prevent nested batching
      */
-    mapRequestItem?(request: StandardRequest, batchOptions: StandardHandlerInterceptorOptions<T>): StandardRequest;
+    mapSubrequest?: (subrequest: StandardLazyRequest, batchOptions: StandardHandlerRoutingInterceptorOptions<T>) => StandardLazyRequest;
     /**
      * Success batch response status code.
      *
      * @default 207
      */
-    successStatus?: Value<Promisable<number>, [responses: Promise<BatchResponseBodyItem>[], batchOptions: StandardHandlerInterceptorOptions<T>]>;
+    successStatus?: Value<Promisable<number>, [batchOptions: StandardHandlerRoutingInterceptorOptions<T>]>;
     /**
-     * success batch response headers.
+     * Success batch response headers.
      *
      * @default {}
      */
-    headers?: Value<Promisable<StandardHeaders>, [responses: Promise<BatchResponseBodyItem>[], batchOptions: StandardHandlerInterceptorOptions<T>]>;
+    headers?: Value<Promisable<StandardHeaders>, [batchOptions: StandardHandlerRoutingInterceptorOptions<T>]>;
+    /**
+     * Keep-alive settings for streaming batch responses.
+     *
+     * When enabled, a zero-length length-prefixed frame is sent periodically while the
+     * stream is idle (no message sent for `interval` ms). Clients ignore these frames.
+     * Only applies to streaming mode.
+     *
+     * @default { enabled: true, interval: 15000 }
+     */
+    keepAlive?: undefined | {
+        /**
+         * If true, a keep-alive frame is sent periodically while the stream is idle.
+         *
+         * @default true
+         */
+        enabled: boolean;
+        /**
+         * Interval (in milliseconds) between keep-alive frames after the last message.
+         *
+         * @default 15000
+         */
+        interval?: number;
+    };
 }
-/**
- * The Batch Requests Plugin allows you to combine multiple requests and responses into a single batch,
- * reducing the overhead of sending each one separately.
- *
- * @see {@link https://orpc.dev/docs/plugins/batch-requests Batch Requests Plugin Docs}
- */
 declare class BatchHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
+    /**
+     * Run batch interceptors before OpenTelemetry interceptors
+     * so each subrequest gets its own span instead of sharing one batch-level span.
+     */
+    after: string[];
     private readonly maxSize;
-    private readonly mapRequestItem;
+    private readonly mapSubrequest;
     private readonly successStatus;
     private readonly headers;
-    order: number;
-    constructor(options?: BatchHandlerOptions<T>);
-    init(options: StandardHandlerOptions<T>): void;
+    private readonly keepAliveEnabled;
+    private readonly keepAliveInterval;
+    constructor(options?: BatchHandlerPluginOptions<T>);
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
 }
 
-interface CORSOptions<T extends Context> {
-    origin?: Value<Promisable<string | readonly string[] | null | undefined>, [origin: string, options: StandardHandlerInterceptorOptions<T>]>;
-    timingOrigin?: Value<Promisable<string | readonly string[] | null | undefined>, [origin: string, options: StandardHandlerInterceptorOptions<T>]>;
+interface CORSHandlerPluginOptions<T extends Context> {
+    /**
+     * Configures the `Access-Control-Allow-Origin` header.
+     * Can be a string, an array of allowed origins, or a function that returns the allowed origin(s).
+     *
+     * @default (origin) => origin
+     */
+    origin?: Value<Promisable<string | readonly string[] | null | undefined>, [origin: string, options: StandardHandlerRoutingInterceptorOptions<T>]>;
+    /**
+     * Configures the `Timing-Allow-Origin` header.
+     * Can be a string, an array of allowed origins, or a function that returns the allowed origin(s).
+     *
+     * @default undefined
+     */
+    timingOrigin?: Value<Promisable<string | readonly string[] | null | undefined>, [origin: string, options: StandardHandlerRoutingInterceptorOptions<T>]>;
+    /**
+     * Configures the `Access-Control-Allow-Methods` header for preflight requests.
+     *
+     * @default ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH']
+     */
     allowMethods?: readonly string[];
+    /**
+     * Configures the `Access-Control-Allow-Headers` header for preflight requests.
+     * Falls back to the request's `Access-Control-Request-Headers` if not set.
+     *
+     * @default undefined
+     */
     allowHeaders?: readonly string[];
+    /**
+     * Configures the `Access-Control-Max-Age` header (in seconds) for preflight requests.
+     *
+     * @default undefined
+     */
     maxAge?: number;
+    /**
+     * Configures the `Access-Control-Allow-Credentials` header.
+     *
+     * @default undefined
+     */
     credentials?: boolean;
+    /**
+     * Configures the `Access-Control-Expose-Headers` header.
+     *
+     * @default undefined
+     */
     exposeHeaders?: readonly string[];
 }
 /**
- * CORSPlugin is a plugin for oRPC that allows you to configure CORS for your API.
+ * CORSHandlerPlugin is a plugin for oRPC that allows you to configure CORS for your API.
  *
  * @see {@link https://orpc.dev/docs/plugins/cors CORS Plugin Docs}
  */
-declare class CORSPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+declare class CORSHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
     private readonly options;
-    order: number;
-    constructor(options?: CORSOptions<T>);
-    init(options: StandardHandlerOptions<T>): void;
+    name: string;
+    /**
+     * - Do not create spans for CORS preflight requests.
+     * - Run CORS interceptors before batch interceptors so headers are applied to
+     *  the actual response rather than sub-responses.
+     */
+    after: string[];
+    constructor(options?: CORSHandlerPluginOptions<T>);
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
 }
 
-interface RequestHeadersPluginContext {
-    reqHeaders?: Headers;
-}
 /**
- * The Request Headers Plugin injects a `reqHeaders` instance into the context,
- * allowing access to request headers in oRPC.
+ * Adds basic Cross-Site Request Forgery (CSRF) protection to your oRPC application.
+ * When a request includes cookies, it helps ensure the request originates from JavaScript
+ * (for example, fetch/XHR) rather than from standard HTML forms or direct browser navigation.
  *
- * @see {@link https://orpc.dev/docs/plugins/request-headers Request Headers Plugin Docs}
+ * @info This plugin is enabled by default for `RPCHandler` over HTTP.
  */
-declare class RequestHeadersPlugin<T extends RequestHeadersPluginContext> implements StandardHandlerPlugin<T> {
-    init(options: StandardHandlerOptions<T>): void;
+declare class CSRFGuardHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
 }
 
-interface ResponseHeadersPluginContext {
-    resHeaders?: Headers;
+declare class RequestCompressionHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
+    /**
+     * Should decompress the original batch request body instead of sub-requests.
+     */
+    after: string[];
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
+}
+
+interface RequestHeadersHandlerPluginContext {
+    /**
+     * Request headers as a Headers instance. This is injected by the Request Headers Plugin.
+     */
+    reqHeaders?: Headers | undefined;
 }
 /**
- * The Response Headers Plugin allows you to set response headers in oRPC.
- * It injects a resHeaders instance into the context, enabling you to modify response headers easily.
+ * The Request Headers Plugin injects a `reqHeaders` instance into the context,
+ * allowing access to request headers in oRPC.
  *
- * @see {@link https://orpc.dev/docs/plugins/response-headers Response Headers Plugin Docs}
+ * @see {@link https://orpc.dev/docs/plugins/request-headers Request Headers Plugin Docs}
  */
-declare class ResponseHeadersPlugin<T extends ResponseHeadersPluginContext> implements StandardHandlerPlugin<T> {
-    init(options: StandardHandlerOptions<T>): void;
+declare class RequestHeadersHandlerPlugin<T extends RequestHeadersHandlerPluginContext> implements StandardHandlerPlugin<T> {
+    name: string;
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
 }
 
-interface experimental_RethrowHandlerPluginOptions<T extends Context> {
+interface RequestLimitHandlerPluginOptions {
     /**
-     * Decide which errors should be rethrown.
-     *
-     * @example
-     * ```ts
-     * const rethrowPlugin = new RethrowHandlerPlugin({
-     *   filter: (error) => {
-     *     // Rethrow all non-ORPCError errors
-     *     return !(error instanceof ORPCError)
-     *   }
-     * })
-     * ```
+     * The maximum allowed request body size in bytes.
      */
-    filter: Value<boolean, [error: ThrowableError, options: StandardHandlerInterceptorOptions<T>]>;
+    maxBodySize: number;
 }
 /**
- * The plugin allows you to catch and rethrow specific errors that occur during request handling.
- * This is particularly useful when your framework has its own error handling mechanism
- * (e.g., global exception filters in NestJS, error middleware in Express)
- * and you want certain errors to be processed by that mechanism instead of being handled by the
- * oRPC error handling flow.
+ * Rejects requests whose body exceeds `maxBodySize`.
  *
- * @see {@link https://orpc.dev/docs/plugins/rethrow-handler Rethrow Handler Plugin Docs}
+ * When used with the request compression plugin, the limit applies to the
+ * decompressed payload rather than the compressed wire size.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/request-limit Request Limit Plugin Docs}
  */
-declare class experimental_RethrowHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
-    private readonly filter;
-    CONTEXT_SYMBOL: symbol;
-    constructor(options: experimental_RethrowHandlerPluginOptions<T>);
-    init(options: StandardHandlerOptions<T>): void;
+declare class RequestLimitHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
+    /**
+     * Should limit the original batch request body instead of sub-requests.
+     */
+    after: string[];
+    /**
+     * Should limit the final body size instead of the compressed one.
+     */
+    before: string[];
+    private readonly maxBodySize;
+    constructor(options: RequestLimitHandlerPluginOptions);
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
 }
 
-interface SimpleCsrfProtectionHandlerPluginOptions<T extends Context> {
+interface ResponseCompressionHandlerPluginOptions<_T extends Context> {
     /**
-     * The name of the header to check.
+     * The compression schemes to use for response compression.
+     * Schemes are prioritized by their order in this array and
+     * only applied if the client supports them (via Accept-Encoding).
      *
-     * @default 'x-csrf-token'
+     * @default ['gzip', 'deflate']
      */
-    headerName?: Value<Promisable<string>, [options: StandardHandlerInterceptorOptions<T>]>;
+    encodings?: readonly ('gzip' | 'deflate' | 'deflate-raw')[];
     /**
-     * The value of the header to check.
-     *
-     * @default 'orpc'
+     * The minimum response size in bytes required to trigger compression.
+     * Responses smaller than this threshold will not be compressed to avoid overhead.
+     * If the response size cannot be determined, compression will still be applied.
      *
+     * @default 1024 (1KB)
      */
-    headerValue?: Value<Promisable<string>, [options: StandardHandlerInterceptorOptions<T>]>;
+    threshold?: number;
+}
+/**
+ * Compresses response bodies based on the client's Accept-Encoding header.
+ * Works at the standard handler level, so it supports all adapters.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/response-compression Response Compression Plugin Docs}
+ */
+declare class ResponseCompressionHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
     /**
-     * Exclude a procedure from the plugin.
-     *
-     * @default false
-     *
+     * Compression should be done after batching, to compress the final response.
+     * Compression should also be done after response headers are set, to access final headers like Content-Type and Cache-Control.
      */
-    exclude?: Value<Promisable<boolean>, [options: ProcedureClientInterceptorOptions<T, Record<never, never>, Meta>]>;
+    after: string[];
+    private readonly encodings;
+    private readonly threshold;
+    constructor(options?: ResponseCompressionHandlerPluginOptions<T>);
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
+}
+
+interface ResponseHeadersHandlerPluginContext {
     /**
-     * The error thrown when the CSRF token is invalid.
-     *
-     * @default new ORPCError('CSRF_TOKEN_MISMATCH', {
-     *   status: 403,
-     *   message: 'Invalid CSRF token',
-     * })
+     * Response headers as a Headers instance. This is injected by the Response Headers Plugin.
+     * When set before the response is sent, these headers will be included in the response. If not set, no additional headers will be added.
      */
-    error?: InstanceType<typeof ORPCError>;
+    resHeaders?: Headers | undefined;
 }
 /**
- * This plugin adds basic Cross-Site Request Forgery (CSRF) protection to your oRPC application.
- * It helps ensure that requests to your procedures originate from JavaScript code,
- * not from other sources like standard HTML forms or direct browser navigation.
+ * The Response Headers Plugin allows you to set response headers in oRPC.
+ * It injects a resHeaders instance into the context, enabling you to modify response headers easily.
  *
- * @see {@link https://orpc.dev/docs/plugins/simple-csrf-protection Simple CSRF Protection Plugin Docs}
+ * @see {@link https://orpc.dev/docs/plugins/response-headers Response Headers Plugin Docs}
  */
-declare class SimpleCsrfProtectionHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
-    private readonly headerName;
-    private readonly headerValue;
-    private readonly exclude;
-    private readonly error;
-    constructor(options?: SimpleCsrfProtectionHandlerPluginOptions<T>);
-    order: number;
-    init(options: StandardHandlerOptions<T>): void;
+declare class ResponseHeadersHandlerPlugin<T extends ResponseHeadersHandlerPluginContext> implements StandardHandlerPlugin<T> {
+    name: string;
+    /**
+     * Interceptors should run after batch interceptors so headers are applied to each sub-response.
+     */
+    before: string[];
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
 }
 
-interface StrictGetMethodPluginOptions {
+interface RethrowHandlerPluginOptions<T extends Context> {
     /**
-     * The error thrown when a GET request is made to a procedure that doesn't allow GET.
+     * Decide which errors should be rethrown.
      *
-     * @default new ORPCError('METHOD_NOT_SUPPORTED')
+     * @example
+     * ```ts
+     * const rethrowPlugin = new RethrowHandlerPlugin({
+     *   filter: (error) => {
+     *     // Rethrow all non-ORPCError errors
+     *     return !(error instanceof ORPCError)
+     *   }
+     * })
+     * ```
      */
-    error?: InstanceType<typeof ORPCError$1>;
+    filter: (error: ThrowableError, options: StandardHandlerInterceptorOptions<T>) => boolean;
 }
 /**
- * This plugin enhances security by ensuring only procedures explicitly marked to accept GET requests
- * can be called using the HTTP GET method for RPC Protocol. This helps prevent certain types of
- * Cross-Site Request Forgery (CSRF) attacks.
+ * The plugin can bypass oRPC's built-in error handling
+ * and rethrow matching errors directly to your framework's error handling mechanism
+ * (e.g., NestJS exception filters, Express error middleware).
  *
- * @see {@link https://orpc.dev/docs/plugins/strict-get-method Strict Get Method Plugin Docs}
+ * @see {@link https://orpc.dev/docs/plugins/rethrow Rethrow Plugin Documentation}
  */
-declare class StrictGetMethodPlugin<T extends Context> implements StandardHandlerPlugin<T> {
-    private readonly error;
-    /**
-     * make sure execute before batch plugin to get real method
-     */
-    order: number;
-    constructor(options?: StrictGetMethodPluginOptions);
-    init(options: StandardHandlerOptions<T>): void;
+declare class RethrowHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
+    private readonly filter;
+    private readonly CONTEXT_SYMBOL;
+    constructor(options: RethrowHandlerPluginOptions<T>);
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
 }
 
-export { BatchHandlerPlugin, CORSPlugin, RequestHeadersPlugin, ResponseHeadersPlugin, SimpleCsrfProtectionHandlerPlugin, StrictGetMethodPlugin, experimental_RethrowHandlerPlugin };
-export type { BatchHandlerOptions, CORSOptions, RequestHeadersPluginContext, ResponseHeadersPluginContext, SimpleCsrfProtectionHandlerPluginOptions, StrictGetMethodPluginOptions, experimental_RethrowHandlerPluginOptions };
+export { BatchHandlerPlugin, CORSHandlerPlugin, CSRFGuardHandlerPlugin, RequestCompressionHandlerPlugin, RequestHeadersHandlerPlugin, RequestLimitHandlerPlugin, ResponseCompressionHandlerPlugin, ResponseHeadersHandlerPlugin, RethrowHandlerPlugin };
+export type { BatchHandlerPluginOptions, CORSHandlerPluginOptions, RequestHeadersHandlerPluginContext, RequestLimitHandlerPluginOptions, ResponseCompressionHandlerPluginOptions, ResponseHeadersHandlerPluginContext, RethrowHandlerPluginOptions };