@vastblast/capnweb 0.4.2 → 0.5.0

package/dist/index.d.cts

@@ -1,226 +1,212 @@
 import { IncomingMessage, ServerResponse, OutgoingHttpHeaders, OutgoingHttpHeader } from 'node:http';
 
-// Copyright (c) 2025 Cloudflare, Inc.
-// Licensed under the MIT license found in the LICENSE.txt file or at:
-//     https://opensource.org/license/mit
-
-// This file borrows heavily from `types/defines/rpc.d.ts` in workerd.
-
-// Branded types for identifying `WorkerEntrypoint`/`DurableObject`/`Target`s.
-// TypeScript uses *structural* typing meaning anything with the same shape as type `T` is a `T`.
-// For the classes exported by `cloudflare:workers` we want *nominal* typing (i.e. we only want to
-// accept `WorkerEntrypoint` from `cloudflare:workers`, not any other class with the same shape)
-declare const __RPC_STUB_BRAND: '__RPC_STUB_BRAND';
-declare const __RPC_TARGET_BRAND: '__RPC_TARGET_BRAND';
-interface RpcTargetBranded {
-  [__RPC_TARGET_BRAND]: never;
-}
-
-// Recursive type transforms are bounded to avoid runaway instantiation.
-type RpcDepth = [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1];
-type NextDepth<D extends unknown[]> = D extends [unknown, ...infer Rest] ? Rest : [];
-type IsAny<T> = 0 extends (1 & T) ? true : false;
-type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
-
-// Types that can be used through `Stub`s.
-// `never[]` preserves compatibility with strongly-typed function signatures without introducing
-// `any` into inference.
-type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
-
-type TypedArray =
-  | Uint8Array
-  | Uint8ClampedArray
-  | Uint16Array
-  | Uint32Array
-  | Int8Array
-  | Int16Array
-  | Int32Array
-  | BigUint64Array
-  | BigInt64Array
-  | Float32Array
-  | Float64Array;
-
-// This represents all the types that can be sent as-is over an RPC boundary.
-type BaseType =
-  | void
-  | undefined
-  | null
-  | boolean
-  | number
-  | bigint
-  | string
-  | TypedArray
-  | ArrayBuffer
-  | DataView
-  | Date
-  | Error
-  | RegExp
-  | ReadableStream<Uint8Array>
-  | WritableStream<any>  // Chunk type can be any RPC-compatible type
-  | Request
-  | Response
-  | Headers;
-
-// Base type for all RPC stubs, including common memory management methods.
-// `T` is used as a marker type for unwrapping `Stub`s later.
-interface StubBase<T = unknown> extends Disposable {
-  [__RPC_STUB_BRAND]: T;
-  dup(): this;
-  onRpcBroken(callback: (error: any) => void): void;
-}
-
-// Types that can be passed over RPC.
-// The reason for using a generic type here is to build a serializable subset of structured
-// cloneable composite types. This allows types defined with the "interface" keyword to pass the
-// serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
-type RpcCompatible<T, D extends unknown[] = RpcDepth> =
-  D extends []
-    ? unknown
-    :
-      // Structured cloneables
-      | BaseType
-      // Structured cloneable composites
-      | Map<
-          T extends Map<infer U, unknown> ? RpcCompatible<U, NextDepth<D>> : never,
-          T extends Map<unknown, infer U> ? RpcCompatible<U, NextDepth<D>> : never
-        >
-      | Set<T extends Set<infer U> ? RpcCompatible<U, NextDepth<D>> : never>
-      | Array<T extends Array<infer U> ? RpcCompatible<U, NextDepth<D>> : never>
-      | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U, NextDepth<D>> : never>
-      | {
-          [K in keyof T as K extends string | number ? K : never]:
-            RpcCompatible<T[K], NextDepth<D>>;
-        }
-      | Promise<T extends Promise<infer U> ? RpcCompatible<U, NextDepth<D>> : never>
-      // Special types
-      | Stub<Stubable>
-      // Serialized as stubs, see `Stubify`
-      | Stubable;
-
-type Stub<T extends RpcCompatible<T>> =
-  T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
-
-// Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
-// prettier-ignore
-type Stubify<T, D extends unknown[] = RpcDepth> =
-  D extends [] ? T
-  : T extends Stubable ? Stub<T>
-  : T extends Promise<infer U> ? Stubify<U, NextDepth<D>>
-  : T extends StubBase<any> ? T
-  : T extends Map<infer K, infer V> ? Map<Stubify<K, NextDepth<D>>, Stubify<V, NextDepth<D>>>
-  : T extends Set<infer V> ? Set<Stubify<V, NextDepth<D>>>
-  : T extends [] ? []
-  : T extends [infer Head, ...infer Tail] ? [Stubify<Head, NextDepth<D>>, ...Stubify<Tail, NextDepth<D>>]
-  : T extends readonly [] ? readonly []
-  : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head, NextDepth<D>>, ...Stubify<Tail, NextDepth<D>>]
-  : T extends Array<infer V> ? Array<Stubify<V, NextDepth<D>>>
-  : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V, NextDepth<D>>>
-  : T extends BaseType ? T
-  // When using "unknown" instead of "any", interfaces are not stubified.
-  : T extends { [key: string | number]: any }
-    ? {
-        [K in keyof T as K extends string | number ? K : never]:
-          Stubify<T[K], NextDepth<D>>;
-      }
-  : T;
-
-// Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
-// Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
-// `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
-// prettier-ignore
-type UnstubifyInner<T, D extends unknown[] = RpcDepth> =
-  D extends [] ? T
-  // Preserve local RpcTarget acceptance, but avoid needless `Stub | Value` unions when the stub
-  // is already assignable to the value type (important for callback contextual typing).
-  : T extends StubBase<infer V> ? (T extends V ? UnstubifyInner<V, NextDepth<D>> : (T | UnstubifyInner<V, NextDepth<D>>))
-  : T extends Promise<infer U> ? UnstubifyInner<U, NextDepth<D>>
-  : T extends Map<infer K, infer V> ? Map<Unstubify<K, NextDepth<D>>, Unstubify<V, NextDepth<D>>>
-  : T extends Set<infer V> ? Set<Unstubify<V, NextDepth<D>>>
-  : T extends [] ? []
-  : T extends [infer Head, ...infer Tail] ? [Unstubify<Head, NextDepth<D>>, ...Unstubify<Tail, NextDepth<D>>]
-  : T extends readonly [] ? readonly []
-  : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head, NextDepth<D>>, ...Unstubify<Tail, NextDepth<D>>]
-  : T extends Array<infer V> ? Array<Unstubify<V, NextDepth<D>>>
-  : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V, NextDepth<D>>>
-  : T extends BaseType ? T
-  : T extends { [key: string | number]: unknown }
-    ? {
-        [K in keyof T as K extends string | number ? K : never]:
-          Unstubify<T[K], NextDepth<D>>;
-      }
-  : T;
-
-// You can put promises anywhere in the params and they'll be resolved before delivery.
-// (This also covers RpcPromise, because it's defined as being a Promise.)
-type Unstubify<T, D extends unknown[] = RpcDepth> =
-  UnstubifyInner<T, D> | Promise<UnstubifyInner<T, D>>;
-
-type UnstubifyAll<A extends readonly unknown[], D extends unknown[] = RpcDepth> = {
-  [I in keyof A]: Unstubify<A[I], D>;
-};
-
-// Utility type for adding `Disposable`s to `object` types only.
-// Note `unknown & T` is equivalent to `T`.
-type MaybeDisposable<T> = T extends object ? Disposable : unknown;
-
-// Type for method return or property on an RPC interface.
-// - Stubable types are replaced by stubs.
-// - RpcCompatible types are passed by value, with stubable types replaced by stubs
-//   and a top-level `Disposer`.
-// Everything else can't be passed over RPC.
-// Technically, we use custom thenables here, but they quack like `Promise`s.
-// Intersecting with `(Maybe)Provider` allows pipelining.
-// prettier-ignore
-type UnknownResult<D extends unknown[]> = D extends []
-  ? Promise<unknown> & StubBase<unknown>
-  : Promise<unknown> & Provider<unknown, D> & StubBase<unknown>;
-
-// prettier-ignore
-type Result<R, D extends unknown[] = RpcDepth> =
-  D extends [] ? UnknownResult<D>
-  : IsAny<R> extends true ? UnknownResult<D>
-  : IsUnknown<R> extends true ? UnknownResult<D>
-  : R extends Stubable ? Promise<Stub<R>> & Provider<R, D> & StubBase<R>
-  : R extends RpcCompatible<R, D> ? Promise<Stubify<R, D> & MaybeDisposable<R>> & Provider<R, D> & StubBase<R>
-  : never;
-
-type HasAnyFunctionParts<P extends readonly unknown[], R> =
-  IsAny<R> extends true ? true : IsAny<P[number]>;
-
-// Type for method or property on an RPC interface.
-// For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
-// Unwrapping `Stub`s allows calling with `Stubable` arguments.
-// For properties, rewrite types to be `Result`s.
-// In each case, unwrap `Promise`s.
-type MethodOrProperty<V, D extends unknown[] = RpcDepth> = V extends (...args: infer P) => infer R
-  ? HasAnyFunctionParts<P, R> extends true
-    ? (...args: unknown[]) => UnknownResult<NextDepth<D>>
-    : (...args: UnstubifyAll<P, NextDepth<D>>) => Result<Awaited<R>, NextDepth<D>>
-  : Result<Awaited<V>, NextDepth<D>>;
-
-// Type for the callable part of a `Provider` if `T` is callable.
-// This is intersected with methods/properties.
-type MaybeCallableProvider<T, D extends unknown[] = RpcDepth> = T extends (...args: any[]) => any
-  ? MethodOrProperty<T, D>
-  : unknown;
-
-// Base type for all other types providing RPC-like interfaces.
-// Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
-type Provider<T, D extends unknown[] = RpcDepth> = MaybeCallableProvider<T, D> &
-  (T extends Array<infer U>
-    ? {
-        [key: number]: MethodOrProperty<U, D>;
-      } & {
-        map<V>(callback: (elem: Result<U, NextDepth<D>>) => V): Result<Array<V>, NextDepth<D>>;
-      }
-    : {
-        [K in Exclude<
-          keyof T,
-          symbol | keyof StubBase<never>
-        >]: MethodOrProperty<T[K], D>;
-      } & {
-        map<V>(callback: (value: Result<NonNullable<T>, NextDepth<D>>) => V):
-          Result<Array<V>, NextDepth<D>>;
+// Copyright (c) 2025 Cloudflare, Inc.
+// Licensed under the MIT license found in the LICENSE.txt file or at:
+//     https://opensource.org/license/mit
+
+// This file borrows heavily from `types/defines/rpc.d.ts` in workerd.
+
+// Branded types for identifying `WorkerEntrypoint`/`DurableObject`/`Target`s.
+// TypeScript uses *structural* typing meaning anything with the same shape as type `T` is a `T`.
+// For the classes exported by `cloudflare:workers` we want *nominal* typing (i.e. we only want to
+// accept `WorkerEntrypoint` from `cloudflare:workers`, not any other class with the same shape)
+declare const __RPC_STUB_BRAND: '__RPC_STUB_BRAND';
+declare const __RPC_TARGET_BRAND: '__RPC_TARGET_BRAND';
+interface RpcTargetBranded {
+  [__RPC_TARGET_BRAND]: never;
+}
+
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
+
+// Types that can be used through `Stub`s.
+// `never[]` preserves compatibility with strongly-typed function signatures without introducing
+// `any` into inference.
+type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
+
+type TypedArray =
+  | Uint8Array
+  | Uint8ClampedArray
+  | Uint16Array
+  | Uint32Array
+  | Int8Array
+  | Int16Array
+  | Int32Array
+  | BigUint64Array
+  | BigInt64Array
+  | Float32Array
+  | Float64Array;
+
+// This represents all the types that can be sent as-is over an RPC boundary
+type BaseType =
+  | void
+  | undefined
+  | null
+  | boolean
+  | number
+  | bigint
+  | string
+  | TypedArray
+  | ArrayBuffer
+  | DataView
+  | Date
+  | Error
+  | RegExp
+  | ReadableStream<Uint8Array>
+  | WritableStream<any>  // Chunk type can be any RPC-compatible type
+  | Request
+  | Response
+  | Headers;
+
+// Base type for all RPC stubs, including common memory management methods.
+// `T` is used as a marker type for unwrapping `Stub`s later.
+interface StubBase<T = unknown> extends Disposable {
+  [__RPC_STUB_BRAND]: T;
+  dup(): this;
+  onRpcBroken(callback: (error: any) => void): void;
+}
+
+// Types that can be passed over RPC.
+// The reason for using a generic type here is to build a serializable subset of structured
+// cloneable composite types. This allows types defined with the "interface" keyword to pass the
+// serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
+type RpcCompatible<T> =
+  // Structured cloneables
+  | BaseType
+  // Structured cloneable composites
+  | Map<
+      T extends Map<infer U, unknown> ? RpcCompatible<U> : never,
+      T extends Map<unknown, infer U> ? RpcCompatible<U> : never
+    >
+  | Set<T extends Set<infer U> ? RpcCompatible<U> : never>
+  | Array<T extends Array<infer U> ? RpcCompatible<U> : never>
+  | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
+  | {
+      [K in keyof T as K extends string | number ? K : never]: RpcCompatible<T[K]>;
+    }
+  | Promise<T extends Promise<infer U> ? RpcCompatible<U> : never>
+  // Special types
+  | Stub<Stubable>
+  // Serialized as stubs, see `Stubify`
+  | Stubable;
+
+type Stub<T extends RpcCompatible<T>> =
+  T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
+
+// Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
+// prettier-ignore
+type Stubify<T> =
+  T extends Stubable ? Stub<T>
+  : T extends Promise<infer U> ? Stubify<U>
+  : T extends StubBase<any> ? T
+  : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>>
+  : T extends Set<infer V> ? Set<Stubify<V>>
+  : T extends [] ? []
+  : T extends [infer Head, ...infer Tail] ? [Stubify<Head>, ...Stubify<Tail>]
+  : T extends readonly [] ? readonly []
+  : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head>, ...Stubify<Tail>]
+  : T extends Array<infer V> ? Array<Stubify<V>>
+  : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>>
+  : T extends BaseType ? T
+  // When using "unknown" instead of "any", interfaces are not stubified.
+  : T extends { [key: string | number]: any }
+    ? {
+        [K in keyof T as K extends string | number ? K : never]: Stubify<T[K]>;
+      }
+  : T;
+
+// Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
+// Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
+// `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
+// prettier-ignore
+type UnstubifyInner<T> =
+  // Preserve local RpcTarget acceptance, but avoid needless `Stub | Value` unions when the stub
+  // is already assignable to the value type (important for callback contextual typing).
+  T extends StubBase<infer V> ? (T extends V ? UnstubifyInner<V> : (T | UnstubifyInner<V>))
+  : T extends Promise<infer U> ? UnstubifyInner<U>
+  : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>>
+  : T extends Set<infer V> ? Set<Unstubify<V>>
+  : T extends [] ? []
+  : T extends [infer Head, ...infer Tail] ? [Unstubify<Head>, ...Unstubify<Tail>]
+  : T extends readonly [] ? readonly []
+  : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head>, ...Unstubify<Tail>]
+  : T extends Array<infer V> ? Array<Unstubify<V>>
+  : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>>
+  : T extends BaseType ? T
+  : T extends { [key: string | number]: unknown }
+    ? {
+        [K in keyof T as K extends string | number ? K : never]: Unstubify<T[K]>;
+      }
+  : T;
+
+// You can put promises anywhere in the params and they'll be resolved before delivery.
+// (This also covers RpcPromise, because it's defined as being a Promise.)
+type Unstubify<T> = UnstubifyInner<T> | Promise<UnstubifyInner<T>>;
+
+type UnstubifyAll<A extends readonly unknown[]> = { [I in keyof A]: Unstubify<A[I]> };
+
+// Utility type for adding `Disposable`s to `object` types only.
+// Note `unknown & T` is equivalent to `T`.
+type MaybeDisposable<T> = T extends object ? Disposable : unknown;
+
+// Type for method return or property on an RPC interface.
+// - Stubable types are replaced by stubs.
+// - RpcCompatible types are passed by value, with stubable types replaced by stubs
+//   and a top-level `Disposer`.
+// Everything else can't be passed over RPC.
+// Technically, we use custom thenables here, but they quack like `Promise`s.
+// Intersecting with `(Maybe)Provider` allows pipelining.
+type UnknownResult = Promise<unknown> & Provider<unknown> & StubBase<unknown>;
+
+// prettier-ignore
+type Result<R> =
+  IsAny<R> extends true ? UnknownResult
+  : IsUnknown<R> extends true ? UnknownResult
+  : R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<R>
+  : R extends RpcCompatible<R> ? Promise<Stubify<R> & MaybeDisposable<R>> & Provider<R> & StubBase<R>
+  : never;
+
+// Type for method or property on an RPC interface.
+// For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
+// Unwrapping `Stub`s allows calling with `Stubable` arguments.
+// For properties, rewrite types to be `Result`s.
+// In each case, unwrap `Promise`s.
+type MethodOrProperty<V> = V extends (...args: infer P) => infer R
+  ? (...args: UnstubifyAll<P>) => (IsAny<R> extends true ? UnknownResult : Result<Awaited<R>>)
+  : Result<Awaited<V>>;
+
+// Type for the callable part of an `Provider` if `T` is callable.
+// This is intersected with methods/properties.
+type MaybeCallableProvider<T> = T extends (...args: any[]) => any
+  ? MethodOrProperty<T>
+  : unknown;
+
+type TupleIndexKeys<T extends ReadonlyArray<unknown>> =
+  Extract<keyof T, `${number}`>;
+type MapCallbackValue<T> =
+  // `Omit` removes call signatures, so re-intersect callable provider behavior.
+  T extends unknown ? Omit<Result<T>, keyof Promise<unknown>> & MaybeCallableProvider<T> : never;
+type ArrayProvider<E> = {
+  [K in number]: MethodOrProperty<E>;
+} & {
+  map<V>(callback: (elem: MapCallbackValue<E>) => V): Result<Array<V>>;
+};
+type TupleProvider<T extends ReadonlyArray<unknown>> = {
+  [K in TupleIndexKeys<T>]: MethodOrProperty<T[K]>;
+} & ArrayProvider<T[number]>;
+
+// Base type for all other types providing RPC-like interfaces.
+// Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
+type Provider<T> = MaybeCallableProvider<T> &
+  (T extends ReadonlyArray<unknown>
+    ? number extends T["length"] ? ArrayProvider<T[number]> : TupleProvider<T>
+    : {
+        [K in Exclude<
+          keyof T,
+          symbol | keyof StubBase<never>
+        >]: MethodOrProperty<T[K]>;
+      } & {
+        map<V>(callback: (value: MapCallbackValue<NonNullable<T>>) => V): Result<Array<V>>;
       });
 
 /**