capnweb 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -12,18 +12,26 @@ import { IncomingMessage, ServerResponse, OutgoingHttpHeaders, OutgoingHttpHeade
 // 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';
+// Distinguishes mapper placeholders from regular values so param unwrapping can accept them.
+declare const __RPC_MAP_VALUE_BRAND: unique symbol;
 interface RpcTargetBranded {
   [__RPC_TARGET_BRAND]: never;
 }
 
 // Types that can be used through `Stub`s
-type Stubable = RpcTargetBranded | ((...args: any[]) => any);
+// `never[]` preserves compatibility with strongly-typed function signatures without introducing
+// `any` into inference.
+type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
+
+type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
 
 // 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> =
+  // Allow `unknown` as a leaf so records/interfaces with `unknown` fields remain compatible.
+  | (IsUnknown<T> extends true ? unknown : never)
   // Structured cloneables
   | BaseType
   // Structured cloneable composites
@@ -35,7 +43,7 @@ type RpcCompatible<T> =
   | Array<T extends Array<infer U> ? RpcCompatible<U> : never>
   | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
   | {
-      [K in keyof T]: K extends number | string ? RpcCompatible<T[K]> : 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
@@ -45,7 +53,7 @@ type RpcCompatible<T> =
 
 // 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 extends RpcCompatible<T>> extends Disposable {
+interface StubBase<T = unknown> extends Disposable {
   [__RPC_STUB_BRAND]: T;
   dup(): this;
   onRpcBroken(callback: (error: any) => void): void;
@@ -82,7 +90,7 @@ type BaseType =
   | Error
   | RegExp
   | ReadableStream<Uint8Array>
-  | WritableStream<Uint8Array>
+  | WritableStream<any>  // Chunk type can be any RPC-compatible type
   | Request
   | Response
   | Headers;
@@ -102,7 +110,7 @@ type Stubify<T> =
   : 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]: Stubify<T[K]> }
+  : 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.
@@ -110,7 +118,10 @@ type Stubify<T> =
 // `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
 // prettier-ignore
 type UnstubifyInner<T> =
-  T extends StubBase<infer V> ? (T | V)  // can provide either stub or local RpcTarget
+  // 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 [] ? []
@@ -120,14 +131,30 @@ type UnstubifyInner<T> =
   : 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]: Unstubify<T[K]> }
+  : 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>>
+// Map placeholders are also allowed so primitive map callback inputs can be forwarded directly
+// into RPC params.
+//
+// Keep raw non-stub members so generic assignability still works when UnstubifyInner<T> is deferred.
+// Remove stub members from mixed unions so callback params don’t get both stub and unstubbed signatures.
+// Marker carried by map() callback inputs. This lets primitive placeholders flow through params.
+type Unstubify<T> =
+  | NonStubMembers<T>
+  | UnstubifyInner<T>
+  | Promise<UnstubifyInner<T>>
+  | MapValuePlaceholder<UnstubifyInner<T>>;
+
+type UnstubifyAll<A extends readonly unknown[]> = { [I in keyof A]: Unstubify<A[I]> };
+
+interface MapValuePlaceholder<T> {
+  [__RPC_MAP_VALUE_BRAND]: T;
+}
 
-type UnstubifyAll<A extends any[]> = { [I in keyof A]: Unstubify<A[I]> };
+type NonStubMembers<T> = Exclude<T, StubBase<any>>;
 
 // Utility type for adding `Disposable`s to `object` types only.
 // Note `unknown & T` is equivalent to `T`.
@@ -142,17 +169,22 @@ type MaybeDisposable<T> = T extends object ? Disposable : unknown;
 // Intersecting with `(Maybe)Provider` allows pipelining.
 // prettier-ignore
 type Result<R> =
-  R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<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 IsAny<T> = 0 extends (1 & T) ? true : false;
+type UnknownResult = Promise<unknown> & Provider<unknown> & StubBase<unknown>;
+
 // 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>) => Result<Awaited<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.
@@ -161,24 +193,78 @@ 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> &
+        MapValuePlaceholder<T>
+    : never;
+type InvalidNativePromiseInMapResult<T, Seen = never> =
+  T extends unknown ? InvalidNativePromiseInMapResultImpl<T, Seen> : never;
+type InvalidNativePromiseInMapResultImpl<T, Seen> =
+  [T] extends [Seen] ? never
+  // RpcPromise is modeled as Promise & StubBase, so allow promise-like stub values.
+  : T extends StubBase<any> ? never
+  // Native thenables cannot be represented in map recordings, even when typed as PromiseLike.
+  : T extends PromiseLike<unknown> ? T
+  : T extends Map<infer K, infer V>
+    ? InvalidNativePromiseInMapResult<K, Seen | T> |
+        InvalidNativePromiseInMapResult<V, Seen | T>
+  : T extends Set<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T>
+  : T extends readonly [] ? never
+  : T extends readonly [infer Head, ...infer Tail]
+    ? InvalidNativePromiseInMapResult<Head, Seen | T> |
+        InvalidNativePromiseInMapResult<Tail[number], Seen | T>
+  : T extends ReadonlyArray<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T>
+  : T extends { [key: string | number]: unknown }
+    ? InvalidNativePromiseInMapResult<
+        T[Extract<keyof T, string | number>],
+        Seen | T
+      >
+  : never;
+type MapCallbackReturn<T> =
+  InvalidNativePromiseInMapResult<T> extends never ? T : never;
+type ArrayProvider<E> = {
+  [K in number]: MethodOrProperty<E>;
+} & {
+  map<V>(callback: (elem: MapCallbackValue<E>) => MapCallbackReturn<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 Array<infer U>
-    ? {
-        [key: number]: MethodOrProperty<U>;
-      } & {
-        map<V>(callback: (elem: U) => V): Result<Array<V>>;
-      }
+  (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: NonNullable<T>) => V): Result<Array<V>>;
+        map<V>(
+          callback: (value: MapCallbackValue<NonNullable<T>>) => MapCallbackReturn<V>
+        ): Result<Array<V>>;
       });
 
+declare global {
+    interface Uint8Array {
+        toBase64?(options?: {
+            alphabet?: "base64" | "base64url";
+            omitPadding?: boolean;
+        }): string;
+    }
+    interface Uint8ArrayConstructor {
+        fromBase64?(text: string, options?: {
+            alphabet?: "base64" | "base64url";
+            lastChunkHandling?: "loose" | "strict" | "stop-before-partial";
+        }): Uint8Array;
+    }
+}
 /**
  * Serialize a value, using Cap'n Web's underlying serialization. This won't be able to serialize
  * RPC stubs, but it will support basic data types.

package/dist/index.d.ts

@@ -12,18 +12,26 @@ import { IncomingMessage, ServerResponse, OutgoingHttpHeaders, OutgoingHttpHeade
 // 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';
+// Distinguishes mapper placeholders from regular values so param unwrapping can accept them.
+declare const __RPC_MAP_VALUE_BRAND: unique symbol;
 interface RpcTargetBranded {
   [__RPC_TARGET_BRAND]: never;
 }
 
 // Types that can be used through `Stub`s
-type Stubable = RpcTargetBranded | ((...args: any[]) => any);
+// `never[]` preserves compatibility with strongly-typed function signatures without introducing
+// `any` into inference.
+type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
+
+type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
 
 // 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> =
+  // Allow `unknown` as a leaf so records/interfaces with `unknown` fields remain compatible.
+  | (IsUnknown<T> extends true ? unknown : never)
   // Structured cloneables
   | BaseType
   // Structured cloneable composites
@@ -35,7 +43,7 @@ type RpcCompatible<T> =
   | Array<T extends Array<infer U> ? RpcCompatible<U> : never>
   | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
   | {
-      [K in keyof T]: K extends number | string ? RpcCompatible<T[K]> : 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
@@ -45,7 +53,7 @@ type RpcCompatible<T> =
 
 // 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 extends RpcCompatible<T>> extends Disposable {
+interface StubBase<T = unknown> extends Disposable {
   [__RPC_STUB_BRAND]: T;
   dup(): this;
   onRpcBroken(callback: (error: any) => void): void;
@@ -82,7 +90,7 @@ type BaseType =
   | Error
   | RegExp
   | ReadableStream<Uint8Array>
-  | WritableStream<Uint8Array>
+  | WritableStream<any>  // Chunk type can be any RPC-compatible type
   | Request
   | Response
   | Headers;
@@ -102,7 +110,7 @@ type Stubify<T> =
   : 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]: Stubify<T[K]> }
+  : 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.
@@ -110,7 +118,10 @@ type Stubify<T> =
 // `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
 // prettier-ignore
 type UnstubifyInner<T> =
-  T extends StubBase<infer V> ? (T | V)  // can provide either stub or local RpcTarget
+  // 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 [] ? []
@@ -120,14 +131,30 @@ type UnstubifyInner<T> =
   : 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]: Unstubify<T[K]> }
+  : 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>>
+// Map placeholders are also allowed so primitive map callback inputs can be forwarded directly
+// into RPC params.
+//
+// Keep raw non-stub members so generic assignability still works when UnstubifyInner<T> is deferred.
+// Remove stub members from mixed unions so callback params don’t get both stub and unstubbed signatures.
+// Marker carried by map() callback inputs. This lets primitive placeholders flow through params.
+type Unstubify<T> =
+  | NonStubMembers<T>
+  | UnstubifyInner<T>
+  | Promise<UnstubifyInner<T>>
+  | MapValuePlaceholder<UnstubifyInner<T>>;
+
+type UnstubifyAll<A extends readonly unknown[]> = { [I in keyof A]: Unstubify<A[I]> };
+
+interface MapValuePlaceholder<T> {
+  [__RPC_MAP_VALUE_BRAND]: T;
+}
 
-type UnstubifyAll<A extends any[]> = { [I in keyof A]: Unstubify<A[I]> };
+type NonStubMembers<T> = Exclude<T, StubBase<any>>;
 
 // Utility type for adding `Disposable`s to `object` types only.
 // Note `unknown & T` is equivalent to `T`.
@@ -142,17 +169,22 @@ type MaybeDisposable<T> = T extends object ? Disposable : unknown;
 // Intersecting with `(Maybe)Provider` allows pipelining.
 // prettier-ignore
 type Result<R> =
-  R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<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 IsAny<T> = 0 extends (1 & T) ? true : false;
+type UnknownResult = Promise<unknown> & Provider<unknown> & StubBase<unknown>;
+
 // 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>) => Result<Awaited<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.
@@ -161,24 +193,78 @@ 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> &
+        MapValuePlaceholder<T>
+    : never;
+type InvalidNativePromiseInMapResult<T, Seen = never> =
+  T extends unknown ? InvalidNativePromiseInMapResultImpl<T, Seen> : never;
+type InvalidNativePromiseInMapResultImpl<T, Seen> =
+  [T] extends [Seen] ? never
+  // RpcPromise is modeled as Promise & StubBase, so allow promise-like stub values.
+  : T extends StubBase<any> ? never
+  // Native thenables cannot be represented in map recordings, even when typed as PromiseLike.
+  : T extends PromiseLike<unknown> ? T
+  : T extends Map<infer K, infer V>
+    ? InvalidNativePromiseInMapResult<K, Seen | T> |
+        InvalidNativePromiseInMapResult<V, Seen | T>
+  : T extends Set<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T>
+  : T extends readonly [] ? never
+  : T extends readonly [infer Head, ...infer Tail]
+    ? InvalidNativePromiseInMapResult<Head, Seen | T> |
+        InvalidNativePromiseInMapResult<Tail[number], Seen | T>
+  : T extends ReadonlyArray<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T>
+  : T extends { [key: string | number]: unknown }
+    ? InvalidNativePromiseInMapResult<
+        T[Extract<keyof T, string | number>],
+        Seen | T
+      >
+  : never;
+type MapCallbackReturn<T> =
+  InvalidNativePromiseInMapResult<T> extends never ? T : never;
+type ArrayProvider<E> = {
+  [K in number]: MethodOrProperty<E>;
+} & {
+  map<V>(callback: (elem: MapCallbackValue<E>) => MapCallbackReturn<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 Array<infer U>
-    ? {
-        [key: number]: MethodOrProperty<U>;
-      } & {
-        map<V>(callback: (elem: U) => V): Result<Array<V>>;
-      }
+  (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: NonNullable<T>) => V): Result<Array<V>>;
+        map<V>(
+          callback: (value: MapCallbackValue<NonNullable<T>>) => MapCallbackReturn<V>
+        ): Result<Array<V>>;
       });
 
+declare global {
+    interface Uint8Array {
+        toBase64?(options?: {
+            alphabet?: "base64" | "base64url";
+            omitPadding?: boolean;
+        }): string;
+    }
+    interface Uint8ArrayConstructor {
+        fromBase64?(text: string, options?: {
+            alphabet?: "base64" | "base64url";
+            lastChunkHandling?: "loose" | "strict" | "stop-before-partial";
+        }): Uint8Array;
+    }
+}
 /**
  * Serialize a value, using Cap'n Web's underlying serialization. This won't be able to serialize
  * RPC stubs, but it will support basic data types.