@orpc/server 2.0.0-beta.43 → 2.0.0-beta.45

package/dist/plugins/index.d.ts

@@ -1,14 +1,15 @@
 import { Value, Promisable, ThrowableError } from '@orpc/shared';
-import { StandardLazyRequest, StandardHeaders, StandardMethod, StandardResponse } from '@standard-server/core';
+import { StandardLazyRequest, StandardResponse, StandardHeaders, StandardMethod } from '@standard-server/core';
 import { Context } from '../index.js';
 import { StandardHandlerPlugin, StandardHandlerRoutingInterceptorOptions, StandardHandlerOptions, StandardHandlerInterceptorOptions } from '../adapters/standard/index.js';
-export { R as RequestLimitHandlerPlugin, a as RequestLimitHandlerPluginOptions } from '../shared/server.COfbQ0D8.js';
+export { R as RequestLimitHandlerPlugin, a as RequestLimitHandlerPluginOptions } from '../shared/server.CI0qiBzm.js';
+export { BATCH_HEADER, DEFAULT_BATCH_MAX_SIZE } from '@orpc/client/plugins';
 import '@orpc/client';
 import '@orpc/contract';
 
 /**
- * Content type for batch responses that use the length-prefixed binary framing
- * (streaming mode, and buffered mode when any sub-response contains binary).
+ * Content type for batch responses that use the length-prefixed binary framing,
+ * which they do when any sub-response contains binary or is a stream.
  *
  * Decoding is driven by the `standard-server` body hint, not this header,
  * so it only serves to describe the payload to logs, proxies, and dev tools.
@@ -16,40 +17,51 @@ import '@orpc/contract';
 declare const BATCH_CONTENT_TYPE = "application/vnd.orpc.batch";
 interface BatchHandlerPluginOptions<T extends Context> {
     /**
-     * The max size of the batch allowed.
+     * The max size of the batch allowed. Larger batches are rejected with a `413`,
+     * so keep the client Batch Link Plugin's `maxSize` at or below it.
      *
-     * @default 10
+     * @default DEFAULT_BATCH_MAX_SIZE (10)
+     * @see {@link https://orpc.dev/docs/plugins/batch#max-size | Batch Plugin - Max Size}
      */
-    maxSize?: Value<Promisable<number>, [options: StandardHandlerRoutingInterceptorOptions<T>]>;
+    maxSize?: Value<Promisable<number>, [options: StandardHandlerRoutingInterceptorOptions<T>]> | undefined;
     /**
      * Map each subrequest in the batch before it is processed.
      *
      * @default merges the batch request headers into the subrequest, giving them priority over
      * the subrequest headers, and removes the `orpc-batch` header to prevent nested batching
      */
-    mapSubrequest?: (subrequest: StandardLazyRequest, batchOptions: StandardHandlerRoutingInterceptorOptions<T>) => StandardLazyRequest;
+    mapSubrequest?: ((subrequest: StandardLazyRequest, batchOptions: StandardHandlerRoutingInterceptorOptions<T>) => StandardLazyRequest) | undefined;
+    /**
+     * Map each sub-response in the batch before it is sent.
+     *
+     * @default removes the headers the batch response already has with the same value, which the client
+     * merges back, and `set-cookie`, which the browser ignores there and JavaScript could read
+     */
+    mapSubresponse?: ((subresponse: StandardResponse, partialBatchResponse: Pick<StandardResponse, 'status' | 'headers'>, batchOptions: StandardHandlerRoutingInterceptorOptions<T>) => StandardResponse) | undefined;
     /**
      * Success batch response status code.
      *
      * @default 207
      */
-    successStatus?: Value<Promisable<number>, [batchOptions: StandardHandlerRoutingInterceptorOptions<T>]>;
+    successStatus?: Value<Promisable<number>, [batchOptions: StandardHandlerRoutingInterceptorOptions<T>]> | undefined;
     /**
      * Success batch response headers.
      *
+     * The batch response also gets the cookies its sub-responses set, and the headers they all share.
+     * Headers set here win, and setting one to `undefined` keeps it off, except `set-cookie` and `vary`, which merge.
+     *
      * @default {}
      */
-    headers?: Value<Promisable<StandardHeaders>, [batchOptions: StandardHandlerRoutingInterceptorOptions<T>]>;
+    headers?: Value<Promisable<StandardHeaders>, [batchOptions: StandardHandlerRoutingInterceptorOptions<T>]> | undefined;
     /**
-     * Keep-alive settings for streaming batch responses.
+     * Keep-alive settings for batch responses that stream.
      *
      * 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 | {
+    keepAlive?: {
         /**
          * If true, a keep-alive frame is sent periodically while the stream is idle.
          *
@@ -61,14 +73,17 @@ interface BatchHandlerPluginOptions<T extends Context> {
          *
          * @default 15000
          */
-        interval?: number;
-    };
+        interval?: number | undefined;
+    } | undefined;
 }
 /**
  * Handles batch requests sent by the client Batch Link Plugin, splitting each
- * batch into sub-requests and streaming their responses back together.
+ * batch into sub-requests and sending their responses back together.
  *
  * @remarks
+ * The batch starts the response once every sub-response is ready, so it carries the cookies sub-requests
+ * set and the headers every sub-response shares. It streams when a sub-response is a stream.
+ *
  * **Note**: HTTP/2 and later already multiplex requests over a single connection, which often makes this plugin unnecessary.
  *
  * @see {@link https://orpc.dev/docs/plugins/batch | Batch Plugin}
@@ -82,6 +97,7 @@ declare class BatchHandlerPlugin<T extends Context> implements StandardHandlerPl
     after: string[];
     private readonly maxSize;
     private readonly mapSubrequest;
+    private readonly mapSubresponse;
     private readonly successStatus;
     private readonly headers;
     private readonly keepAliveEnabled;
@@ -95,39 +111,45 @@ interface CORSHandlerPluginOptions<T extends Context> {
      * Configures the `Access-Control-Allow-Origin` header.
      * Can be a string, an array of allowed origins, or a function (optionally async) that returns the allowed origin(s).
      *
+     * A function must only return origins it has validated: returning the incoming origin
+     * unchecked allows every origin.
+     *
      * @default '*'
      */
-    origin?: Value<Promisable<string | readonly string[] | null | undefined>, [origin: string, options: StandardHandlerRoutingInterceptorOptions<T>]>;
+    origin?: Value<Promisable<string | readonly string[] | null | undefined>, [origin: string, options: StandardHandlerRoutingInterceptorOptions<T>]> | undefined;
     /**
      * Configures the `Timing-Allow-Origin` header.
      * Can be a string, an array of allowed origins, or a function (optionally async) that returns the allowed origin(s).
      */
-    timingOrigin?: Value<Promisable<string | readonly string[] | null | undefined>, [origin: string, options: StandardHandlerRoutingInterceptorOptions<T>]>;
+    timingOrigin?: Value<Promisable<string | readonly string[] | null | undefined>, [origin: string, options: StandardHandlerRoutingInterceptorOptions<T>]> | undefined;
     /**
      * Configures the `Access-Control-Allow-Methods` header for preflight requests.
      *
      * @default ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH', 'QUERY']
      */
-    allowMethods?: readonly string[];
+    allowMethods?: readonly string[] | undefined;
     /**
      * Configures the `Access-Control-Allow-Headers` header for preflight requests.
      * Falls back to the request's `Access-Control-Request-Headers` if not set.
      * When set, it replaces that fallback, so include every non-safelisted header
      * clients send, such as `Content-Type`.
      */
-    allowHeaders?: readonly string[];
+    allowHeaders?: readonly string[] | undefined;
     /**
      * Configures the `Access-Control-Max-Age` header (in seconds) for preflight requests.
      */
-    maxAge?: number;
+    maxAge?: number | undefined;
     /**
      * Configures the `Access-Control-Allow-Credentials` header.
+     *
+     * When enabled, `origin` must allow trusted origins only: every allowed origin can send
+     * authenticated requests as your users and read the responses.
      */
-    credentials?: boolean;
+    credentials?: boolean | undefined;
     /**
      * Configures the `Access-Control-Expose-Headers` header.
      */
-    exposeHeaders?: readonly string[];
+    exposeHeaders?: readonly string[] | undefined;
 }
 /**
  * Configures the [CORS Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
@@ -177,7 +199,7 @@ interface MethodOverrideHandlerPluginOptions {
      *
      * @default 'method'
      */
-    param?: string;
+    param?: string | undefined;
     /**
      * The methods a POST request may be overridden to.
      *
@@ -186,7 +208,7 @@ interface MethodOverrideHandlerPluginOptions {
      *
      * @default ['PUT', 'PATCH', 'DELETE']
      */
-    methods?: readonly StandardMethod[];
+    methods?: readonly StandardMethod[] | undefined;
 }
 /**
  * Overrides the HTTP method of a POST request based on a query parameter,
@@ -207,31 +229,6 @@ declare class MethodOverrideHandlerPlugin<T extends Context> implements Standard
     init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
 }
 
-/**
- * Rejects requests whose decoded input contains prototype-polluting keys: an own
- * `__proto__` key, or an own `constructor` key holding a `prototype` key. oRPC's own
- * decoding never assigns through the prototype chain, so this plugin exists to stop such
- * keys from reaching application code that merges, clones, or path-sets input with a
- * library vulnerable to prototype pollution. An `AsyncIteratorObject` input is checked
- * value by value as it arrives, and a polluting value fails that iteration instead.
- *
- * @see {@link https://orpc.dev/docs/plugins/prototype-pollution-protection | Prototype Pollution Protection Plugin}
- */
-declare class PrototypePollutionProtectionHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
-    name: string;
-    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
-    private rejectPollutingInput;
-    /**
-     * Walks the containers the built-in codecs can produce: arrays, maps, sets, and plain
-     * objects, including null-prototype ones. Arrays get the same key checks as plain objects,
-     * since structured clone, as used over MessagePort, keeps named keys like `__proto__` on
-     * them. Other objects, such as files and dates, carry no attacker-authored keys and are
-     * left alone. The walk is iterative, so input nested deeper than the call stack allows
-     * still gets the intended verdict instead of a `RangeError`.
-     */
-    private containsPollutingKey;
-}
-
 /**
  * Decompresses incoming request bodies based on the Content-Encoding header,
  * supporting gzip, deflate, and deflate-raw.
@@ -277,7 +274,7 @@ interface ResponseCompressionHandlerPluginOptions<T extends Context> {
      *
      * @default ['gzip', 'deflate']
      */
-    encodings?: readonly ('gzip' | 'deflate' | 'deflate-raw')[];
+    encodings?: readonly ('gzip' | 'deflate' | 'deflate-raw')[] | undefined;
     /**
      * The minimum response size in bytes required to trigger compression.
      * Responses smaller than this threshold will not be compressed to avoid overhead.
@@ -285,7 +282,7 @@ interface ResponseCompressionHandlerPluginOptions<T extends Context> {
      *
      * @default 1024 (1KB)
      */
-    threshold?: number;
+    threshold?: number | undefined;
     /**
      * Determines whether a response with the given Content-Type should be compressed.
      * Only consulted for binary transfers (streams, files, and file form-data parts).
@@ -293,7 +290,7 @@ interface ResponseCompressionHandlerPluginOptions<T extends Context> {
      *
      * @default isCompressibleContentType (covers common text-based formats)
      */
-    isCompressibleContentType?: (contentType: string | null | undefined, options: StandardHandlerRoutingInterceptorOptions<T>) => boolean;
+    isCompressibleContentType?: ((contentType: string | null | undefined, options: StandardHandlerRoutingInterceptorOptions<T>) => boolean) | undefined;
 }
 /**
  * Compresses response bodies based on the client's Accept-Encoding header.
@@ -384,6 +381,18 @@ declare class RethrowHandlerPlugin<T extends Context> implements StandardHandler
     init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
 }
 
+/**
+ * Keeps the request signal and a streaming output (async iterator object or readable stream) in sync:
+ * cancelling the output aborts the signal with an `AbortError`,
+ * and aborting the signal ends the output with the abort reason and cancels it.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/signal-sync | Signal Sync Plugin}
+ */
+declare class SignalSyncHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
+}
+
 interface TimeoutHandlerPluginOptions<T extends Context> {
     /**
      * Timeout in milliseconds before the request signal is aborted.
@@ -402,7 +411,7 @@ interface TimeoutHandlerPluginOptions<T extends Context> {
      *
      * @default undefined (streaming responses run without limit)
      */
-    streamingTimeout?: Value<number | null | undefined, [options: StandardHandlerInterceptorOptions<T>]>;
+    streamingTimeout?: Value<number | null | undefined, [options: StandardHandlerInterceptorOptions<T>]> | undefined;
 }
 /**
  * The Timeout Handler Plugin aborts the request signal with an `AbortError`
@@ -419,5 +428,5 @@ declare class TimeoutHandlerPlugin<T extends Context> implements StandardHandler
     init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
 }
 
-export { BATCH_CONTENT_TYPE, BatchHandlerPlugin, CORSHandlerPlugin, CORSHandlerPlugin as CORSPlugin, GetMethodCsrfProtectionHandlerPlugin, MethodOverrideHandlerPlugin, PrototypePollutionProtectionHandlerPlugin, RequestCompressionHandlerPlugin, RequestHeadersHandlerPlugin, RequestHeadersHandlerPlugin as RequestHeadersPlugin, ResponseCompressionHandlerPlugin, ResponseHeadersHandlerPlugin, ResponseHeadersHandlerPlugin as ResponseHeadersPlugin, RethrowHandlerPlugin, TimeoutHandlerPlugin, negotiateResponseCompressionEncoding, toCompressedHeaders };
+export { BATCH_CONTENT_TYPE, BatchHandlerPlugin, CORSHandlerPlugin, CORSHandlerPlugin as CORSPlugin, GetMethodCsrfProtectionHandlerPlugin, MethodOverrideHandlerPlugin, RequestCompressionHandlerPlugin, RequestHeadersHandlerPlugin, RequestHeadersHandlerPlugin as RequestHeadersPlugin, ResponseCompressionHandlerPlugin, ResponseHeadersHandlerPlugin, ResponseHeadersHandlerPlugin as ResponseHeadersPlugin, RethrowHandlerPlugin, SignalSyncHandlerPlugin, TimeoutHandlerPlugin, negotiateResponseCompressionEncoding, toCompressedHeaders };
 export type { BatchHandlerPluginOptions, CORSHandlerPluginOptions, MethodOverrideHandlerPluginOptions, RequestHeadersHandlerPluginContext, RequestHeadersHandlerPluginContext as RequestHeadersPluginContext, ResponseCompressionHandlerPluginOptions, ResponseHeadersHandlerPluginContext, ResponseHeadersHandlerPluginContext as ResponseHeadersPluginContext, RethrowHandlerPluginOptions, TimeoutHandlerPluginOptions };