@orpc/shared 2.0.0-beta.3 → 2.0.0-beta.31

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { Promisable } from 'type-fest';
-export { IsEqual, PartialDeep, Promisable, Writable } from 'type-fest';
+import { Arrayable, Promisable } from 'type-fest';
+export { Arrayable, IsEqual, PartialDeep, Promisable, Writable } from 'type-fest';
 import { Tracer, TraceAPI, ContextAPI, PropagationAPI, SpanOptions, Context, Span, AttributeValue, Exception } from '@opentelemetry/api';
 import { AsyncIteratorClass } from '@standardserver/shared';
-export { AbortError, AsyncCleanupFn, AsyncIteratorClass, AsyncIteratorClassNextFn, SequentialIdGenerator, getOrBind, isAsyncIteratorObject, isTypescriptObject, parseEmptyableJSON, sleep, stringifyJSON, toArray } from '@standardserver/shared';
+export { AbortError, AsyncCleanupFn, AsyncIteratorClass, AsyncIteratorClassNextFn, SequentialIdGenerator, getOrBind, isAsyncIteratorObject, isTypescriptObject, parseEmptyableJSON, sequential, sleep, stringifyJSON, toArray } from '@standardserver/shared';
 
 type MaybeOptionalOptions<TOptions> = object extends TOptions ? [options?: TOptions] : [options: TOptions];
 declare function resolveMaybeOptionalOptions<T>(rest: MaybeOptionalOptions<T>): T;
@@ -14,13 +14,13 @@ declare function splitInHalf<T>(arr: readonly T[]): [T[], T[]];
  *
  * Prefers the newer `.bytes` method when available as it more efficient but not widely supported yet.
  */
-declare function loadBytes(source: Pick<Blob, 'arrayBuffer' | 'bytes'>): Promise<Uint8Array<ArrayBuffer>>;
+declare function loadBytes(source: Pick<Blob, 'arrayBuffer' | 'bytes'>): ReturnType<Blob['bytes']>;
 /**
  * Normalize text or binary-like inputs to either:
  * - the original string value, or
  * - a Uint8Array view over the source bytes.
  */
-declare function toStringOrBytes(source: string | ArrayBuffer | Blob | Exclude<ConstructorParameters<typeof Blob>[0], undefined>[0][] | Pick<Uint8Array<ArrayBuffer>, 'buffer' | 'byteOffset' | 'byteLength'>): Promise<string | Uint8Array<ArrayBuffer>>;
+declare function toStringOrBytes(source: Arrayable<string | ArrayBuffer | Pick<Uint8Array<ArrayBuffer>, 'buffer' | 'byteOffset' | 'byteLength'>>): string | Awaited<ReturnType<Blob['bytes']>>;
 
 declare function isDeepEqual(a: unknown, b: unknown): boolean;
 
@@ -41,6 +41,23 @@ declare function normalizeHttpPath(path: string): `/${string}`;
 declare function mergeHttpPath(a: `/${string}`, b: `/${string}`): `/${string}`;
 declare function matchesHttpPathPrefix(url: `/${string}`, prefix: `/${string}`): boolean;
 declare function matchesHttpPath(url: `/${string}`, path: `/${string}`): boolean;
+/**
+ * Parse Accept-Encoding into each coding's q-value, where `0` means the coding is explicitly
+ * unacceptable. The `*` wildcard is kept under its own key, so a caller can honour it while
+ * still letting a specific coding take precedence over it.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9110.html#name-accept-encoding
+ */
+declare function parseAcceptEncodingQualities(header: string | undefined): Map<string, number>;
+/**
+ * Add `accept-encoding` to a Vary header value. The encoding is chosen from the request, so a
+ * shared cache must key on it or it will hand a compressed body to a client that cannot decode it.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9110.html#name-vary
+ */
+declare function varyByAcceptEncoding(vary: string | undefined): string;
+declare function isNoTransformCacheControl(cacheControl: string | undefined): boolean;
+declare function isCompressibleContentType(contentType: string | null | undefined): boolean;
 
 /**
  * Compares two sequential IDs.
@@ -90,7 +107,10 @@ declare function onSuccess<T, TOptions extends {
     next: () => any;
 }, TRest extends any[]>(callback: NoInfer<(result: Awaited<ReturnType<TOptions['next']>>, options: TOptions, ...rest: TRest) => Promisable<void>>): (options: TOptions, ...rest: TRest) => T | Promise<Awaited<ReturnType<TOptions['next']>>>;
 /**
- * Can used for interceptors or middlewares
+ * Creates an interceptor or middleware that invokes a callback whenever an error
+ * is thrown. The error is rethrown after the callback completes.
+ *
+ * @see {@link https://orpc.dev/docs/adapters/fetch-api | Fetch API Adapter}
  */
 declare function onError<T, TOptions extends {
     next: () => any;
@@ -102,6 +122,30 @@ type OnFinishState<TResult, TError> = [error: TError, data: undefined, isSuccess
 declare function onFinish<T, TOptions extends {
     next: () => any;
 }, TRest extends any[]>(callback: NoInfer<(state: OnFinishState<Awaited<ReturnType<TOptions['next']>>, ReturnType<TOptions['next']> extends PromiseWithError<any, infer E> ? E : ThrowableError>, options: TOptions, ...rest: TRest) => Promisable<void>>): (options: TOptions, ...rest: TRest) => T | Promise<Awaited<ReturnType<TOptions['next']>>>;
+/**
+ * Creates a middleware or interceptor that invokes a callback when the returned async
+ * iterator object throws an error while being consumed.
+ *
+ * This does not replace the `onError`. `onError` only fires on the
+ * initial call (before the interceptor returns the iterator), whereas this
+ * callback only fires while consuming the iterator. Use both together to
+ * catch all possible errors.
+ */
+declare function onAsyncIteratorObjectError<T, TOptions extends {
+    next: () => any;
+}, TRest extends any[]>(callback: NoInfer<(error: ThrowableError | (ReturnType<TOptions['next']> extends PromiseWithError<any, infer E> ? E : ThrowableError), options: TOptions, ...rest: TRest) => Promisable<void>>): (options: TOptions, ...rest: TRest) => T | Promise<Awaited<ReturnType<TOptions['next']>>>;
+/**
+ * Creates an interceptor that invokes a callback when the returned readable
+ * stream errors while being consumed.
+ *
+ * This does not replace the `onError`. `onError` only fires on the
+ * initial call (before the interceptor returns the stream), whereas this
+ * callback only fires while consuming the stream. Use both together to catch
+ * all possible errors.
+ */
+declare function onReadableStreamError<T, TOptions extends {
+    next: () => any;
+}, TRest extends any[]>(callback: NoInfer<(error: ThrowableError | (ReturnType<TOptions['next']> extends PromiseWithError<any, infer E> ? E : ThrowableError), options: TOptions, ...rest: TRest) => Promisable<void>>): (options: TOptions, ...rest: TRest) => T | Promise<Awaited<ReturnType<TOptions['next']>>>;
 declare function intercept<TOptions extends InterceptableOptions, TResult>(interceptors: undefined | Interceptor<TOptions, TResult>[], options: NoInfer<TOptions>, main: NoInfer<(options: TOptions) => TResult>): TResult;
 
 /**
@@ -147,8 +191,8 @@ interface WrapAsyncIteratorOptions<TYield, TReturn, TMappedYield, TMappedReturn>
      */
     runWith?: <T>(run: () => Promise<T>) => Promise<T>;
     mapResult?: (result: IteratorResult<TYield, TReturn>) => Promisable<IteratorResult<TMappedYield, TMappedReturn>>;
-    mapError?: (error: unknown) => Promisable<unknown>;
-    onError?: (error: unknown) => Promisable<void>;
+    mapError?: (error: ThrowableError) => Promisable<ThrowableError>;
+    onError?: (error: ThrowableError) => Promisable<void>;
     /**
      * Execute after the stream finishes or is cancelled.
      */
@@ -157,6 +201,40 @@ interface WrapAsyncIteratorOptions<TYield, TReturn, TMappedYield, TMappedReturn>
 declare function wrapAsyncIterator<TYield, TReturn, TMappedYield = TYield, TMappedReturn = TReturn>(iterator: AsyncIterator<TYield, TReturn>, { runWith, mapResult, mapError, onError, onFinish }: WrapAsyncIteratorOptions<TYield, TReturn, TMappedYield, TMappedReturn>): NoInfer<AsyncIteratorClass<TMappedYield, TMappedReturn>>;
 declare function traceAsyncIterator<T, TReturn, TNext>(options: StartSpanOptions | string, iterator: AsyncIterator<T, TReturn, TNext>): AsyncIteratorClass<T, TReturn, TNext>;
 declare function replicateAsyncIterator<T, TReturn, TNext>(source: AsyncIterator<T, TReturn, TNext>, count: number): (AsyncIteratorClass<T, TReturn, TNext>)[];
+interface ConsumeAsyncIteratorOptions<T, TReturn, TError> {
+    /**
+     * Called on each event
+     */
+    onEvent: (event: T) => void;
+    /**
+     * Called once error happens
+     */
+    onError?: (error: TError) => void;
+    /**
+     * Called once AsyncIteratorObject is done
+     *
+     * @remarks
+     * **Note**: If iterator is canceled, `undefined` can be passed on success
+     */
+    onSuccess?: (value: TReturn | undefined) => void;
+    /**
+     * Called once after onError or onSuccess
+     *
+     * @remarks
+     * **Note**: If iterator is canceled, `undefined` can be passed on success
+     */
+    onFinish?: (state: [error: TError, data: undefined, isSuccess: false] | [error: null, data: TReturn | undefined, isSuccess: true]) => void;
+}
+/**
+ * Consumes an AsyncIteratorObject with lifecycle callbacks.
+ *
+ * @remarks
+ * **Warning**: If no `onError` or `onFinish` is provided, errors are thrown into the unhandled rejection channel.
+ *
+ * @returns An unsubscribe callback that stops consuming and cleans up the iterator.
+ * @see {@link https://orpc.dev/docs/client/async-iterator-object#using-consumeasynciterator | AsyncIteratorObject in Client - Using consumeAsyncIterator}
+ */
+declare function consumeAsyncIterator<T, TReturn, TError = ThrowableError>(iterator: AsyncIterator<T, TReturn> | PromiseWithError<AsyncIterator<T, TReturn>, TError>, options: ConsumeAsyncIteratorOptions<T, TReturn, TError | ThrowableError>): () => Promise<void>;
 
 type Segment = string | number;
 declare function findDeepMatches(check: (value: unknown) => boolean, payload: unknown, segments?: Segment[], maps?: Segment[][], values?: unknown[]): {
@@ -168,16 +246,27 @@ declare function findDeepMatches(check: (value: unknown) => boolean, payload: un
  *
  */
 declare function getConstructor(value: unknown): Function | null | undefined;
+declare function getConstructors(value: unknown): Generator<Function>;
 /**
  * Checks whether a value is a plain object, including objects created with
  * `Object.create(null)`.
  */
 declare function isPlainObject(value: unknown): value is Record<PropertyKey, unknown>;
+/**
+ * Returns `object[key]` only when it is an own property, so keys like
+ * `toString` do not resolve through the prototype chain.
+ */
+declare function getOwn<T extends object>(object: T, key: PropertyKey): T[keyof T] | undefined;
 declare function get(object: unknown, path: readonly PropertyKey[]): unknown;
 /**
  * Sets a value at the given path, creating plain objects for intermediate keys as needed.
  */
 declare function set(root: object, path: [PropertyKey, ...PropertyKey[]] | [...PropertyKey[], PropertyKey], value: unknown): void;
+/**
+ * Merges two values by copying the second over the first, repeating the merge one level deeper for
+ * nested plain objects. Anything that is not a pair of plain objects is replaced by the second one.
+ */
+declare function mergeTwoLevels(first: unknown, second: unknown): unknown;
 declare function omit<T extends object, K extends keyof T>(obj: T, keys: readonly K[]): Omit<T, K>;
 declare function clone<T>(value: T): T;
 declare function isPropertyKey(value: unknown): value is PropertyKey;
@@ -191,7 +280,9 @@ declare const NullProtoObj: ({
  * Methods are collected from both the object itself and its prototype chain
  * (excluding `Object.prototype` and the `constructor` property).
  */
-declare function bindMethods<T extends object>(obj: T): Pick<T, {
+declare function bindMethods<T extends object>(obj: T, options?: {
+    unbound?: (keyof T)[];
+}): Pick<T, {
     [K in keyof T]: T[K] extends AnyFunction ? K : never;
 }[keyof T]>;
 
@@ -257,6 +348,11 @@ declare class AsyncIdQueue<T> {
  * Returns a signal that aborts only after all provided signals are aborted.
  */
 declare function allAbortSignal(signals: readonly (AbortSignal | undefined)[]): AbortSignal | undefined;
+/**
+ * Returns a signal that aborts as soon as any of the provided signals aborts,
+ * with the same abort reason.
+ */
+declare function anyAbortSignal(signals: readonly (AbortSignal | undefined)[]): AbortSignal | undefined;
 declare function runWithSignal<T>(signal: AbortSignal | undefined, fn: () => Promise<T>): Promise<T>;
 
 declare function replicateReadableStream<T>(stream: ReadableStream<T>, count: number): ReadableStream<T>[];
@@ -265,7 +361,7 @@ type ReadableStreamReadResult<T> = {
     value: T;
 } | {
     done: true;
-    value: undefined | T;
+    value?: undefined | T;
 };
 interface WrapReadableStreamOptions<T, TMapped> {
     /**
@@ -275,8 +371,8 @@ interface WrapReadableStreamOptions<T, TMapped> {
      */
     runWith?: <T>(run: () => Promise<T>) => Promise<T>;
     mapResult?: (result: ReadableStreamReadResult<T>) => Promisable<ReadableStreamReadResult<TMapped>>;
-    mapError?: (error: unknown) => Promisable<unknown>;
-    onError?: (error: unknown) => Promisable<void>;
+    mapError?: (error: ThrowableError) => Promisable<ThrowableError>;
+    onError?: (error: ThrowableError) => Promisable<void>;
     /**
      * Guaranteed to execute exactly once after the stream finishes or is cancelled.
      */
@@ -285,9 +381,11 @@ interface WrapReadableStreamOptions<T, TMapped> {
 declare function wrapReadableStream<T, TMapped = T>(stream: ReadableStream<T>, { runWith, mapResult, mapError, onError, onFinish }: WrapReadableStreamOptions<T, TMapped>): NoInfer<ReadableStream<TMapped>>;
 declare function traceReadableStream<T>(options: StartSpanOptions | string, stream: ReadableStream<T>): ReadableStream<T>;
 /**
- * Converts a `ReadableStream` into an `AsyncIteratorClass`.
+ * Converts a {@link ReadableStream} into an {@link AsyncIteratorClass}.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/ai-sdk | AI SDK Integration}
  */
-declare function streamToAsyncIteratorClass<T>(stream: ReadableStream<T>, { signal }?: {
+declare function streamToAsyncIteratorObject<T>(stream: ReadableStream<T>, { signal }?: {
     signal?: undefined | AbortSignal;
 }): AsyncIteratorClass<T>;
 /**
@@ -297,10 +395,12 @@ declare function asyncIteratorToStream<T>(iterator: AsyncIterator<T>): ReadableS
 /**
  * Converts an `AsyncIterator` into a `ReadableStream`, ensuring that
  * all emitted object values are *unproxied* before enqueuing.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/ai-sdk | AI SDK Integration}
  */
 declare function asyncIteratorToUnproxiedDataStream<T>(iterator: AsyncIterator<T>): ReadableStream<T>;
 
 declare function tryDecodeURIComponent(value: string): string;
 
-export { AsyncIdQueue, NullProtoObj, ORPC_NAME, allAbortSignal, asyncIteratorToStream, asyncIteratorToUnproxiedDataStream, bindMethods, clone, compareSequentialIds, defer, findDeepMatches, get, getConstructor, getOpenTelemetryConfig, intercept, isAbortError, isDeepEqual, isPlainObject, isPropertyKey, loadBytes, matchesHttpPath, matchesHttpPathPrefix, mergeHttpPath, normalizeHttpPath, omit, onError, onFinish, onStart, onSuccess, once, override, pathToHttpPath, promiseWithResolvers, recordSpanError, replicateAsyncIterator, replicateReadableStream, resolveMaybeOptionalOptions, runInSpanContext, runWithSignal, runWithSpan, set, setOpenTelemetryConfig, setSpanAttributeIfDefined, sortPlugins, splitInHalf, startSpan, streamToAsyncIteratorClass, toOtelException, toSpanAttributeValue, toStringOrBytes, traceAsyncIterator, traceReadableStream, tryDecodeURIComponent, tryOrUndefined, value, wrapAsyncIterator, wrapReadableStream };
-export type { AnyFunction, AsyncIdQueueCloseOptions, InterceptableOptions, Interceptor, InterceptorOptions, IntersectPick, MaybeOptionalOptions, OnFinishState, OpenTelemetryConfig, OrderablePlugin, PromiseWithError, Public, ReadableStreamReadResult, Registry, RunWithSpanOptions, Segment, StartSpanOptions, ThrowableError, Value, WrapAsyncIteratorOptions, WrapReadableStreamOptions };
+export { AsyncIdQueue, NullProtoObj, ORPC_NAME, allAbortSignal, anyAbortSignal, asyncIteratorToStream, asyncIteratorToUnproxiedDataStream, bindMethods, clone, compareSequentialIds, consumeAsyncIterator, defer, findDeepMatches, get, getConstructor, getConstructors, getOpenTelemetryConfig, getOwn, intercept, isAbortError, isCompressibleContentType, isDeepEqual, isNoTransformCacheControl, isPlainObject, isPropertyKey, loadBytes, matchesHttpPath, matchesHttpPathPrefix, mergeHttpPath, mergeTwoLevels, normalizeHttpPath, omit, onAsyncIteratorObjectError, onError, onFinish, onReadableStreamError, onStart, onSuccess, once, override, parseAcceptEncodingQualities, pathToHttpPath, promiseWithResolvers, recordSpanError, replicateAsyncIterator, replicateReadableStream, resolveMaybeOptionalOptions, runInSpanContext, runWithSignal, runWithSpan, set, setOpenTelemetryConfig, setSpanAttributeIfDefined, sortPlugins, splitInHalf, startSpan, streamToAsyncIteratorObject, toOtelException, toSpanAttributeValue, toStringOrBytes, traceAsyncIterator, traceReadableStream, tryDecodeURIComponent, tryOrUndefined, value, varyByAcceptEncoding, wrapAsyncIterator, wrapReadableStream };
+export type { AnyFunction, AsyncIdQueueCloseOptions, ConsumeAsyncIteratorOptions, InterceptableOptions, Interceptor, InterceptorOptions, IntersectPick, MaybeOptionalOptions, OnFinishState, OpenTelemetryConfig, OrderablePlugin, PromiseWithError, Public, ReadableStreamReadResult, Registry, RunWithSpanOptions, Segment, StartSpanOptions, ThrowableError, Value, WrapAsyncIteratorOptions, WrapReadableStreamOptions };