@vastblast/capnweb 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.cts +235 -207
  2. package/dist/index.d.ts +235 -207
  3. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -1,212 +1,240 @@
1
1
  import { IncomingMessage, ServerResponse, OutgoingHttpHeaders, OutgoingHttpHeader } from 'node:http';
2
2
 
3
- // Copyright (c) 2025 Cloudflare, Inc.
4
- // Licensed under the MIT license found in the LICENSE.txt file or at:
5
- // https://opensource.org/license/mit
6
-
7
- // This file borrows heavily from `types/defines/rpc.d.ts` in workerd.
8
-
9
- // Branded types for identifying `WorkerEntrypoint`/`DurableObject`/`Target`s.
10
- // TypeScript uses *structural* typing meaning anything with the same shape as type `T` is a `T`.
11
- // For the classes exported by `cloudflare:workers` we want *nominal* typing (i.e. we only want to
12
- // accept `WorkerEntrypoint` from `cloudflare:workers`, not any other class with the same shape)
13
- declare const __RPC_STUB_BRAND: '__RPC_STUB_BRAND';
14
- declare const __RPC_TARGET_BRAND: '__RPC_TARGET_BRAND';
15
- interface RpcTargetBranded {
16
- [__RPC_TARGET_BRAND]: never;
17
- }
18
-
19
- type IsAny<T> = 0 extends (1 & T) ? true : false;
20
- type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
21
-
22
- // Types that can be used through `Stub`s.
23
- // `never[]` preserves compatibility with strongly-typed function signatures without introducing
24
- // `any` into inference.
25
- type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
26
-
27
- type TypedArray =
28
- | Uint8Array
29
- | Uint8ClampedArray
30
- | Uint16Array
31
- | Uint32Array
32
- | Int8Array
33
- | Int16Array
34
- | Int32Array
35
- | BigUint64Array
36
- | BigInt64Array
37
- | Float32Array
38
- | Float64Array;
39
-
40
- // This represents all the types that can be sent as-is over an RPC boundary
41
- type BaseType =
42
- | void
43
- | undefined
44
- | null
45
- | boolean
46
- | number
47
- | bigint
48
- | string
49
- | TypedArray
50
- | ArrayBuffer
51
- | DataView
52
- | Date
53
- | Error
54
- | RegExp
55
- | ReadableStream<Uint8Array>
56
- | WritableStream<any> // Chunk type can be any RPC-compatible type
57
- | Request
58
- | Response
59
- | Headers;
60
-
61
- // Base type for all RPC stubs, including common memory management methods.
62
- // `T` is used as a marker type for unwrapping `Stub`s later.
63
- interface StubBase<T = unknown> extends Disposable {
64
- [__RPC_STUB_BRAND]: T;
65
- dup(): this;
66
- onRpcBroken(callback: (error: any) => void): void;
67
- }
68
-
69
- // Types that can be passed over RPC.
70
- // The reason for using a generic type here is to build a serializable subset of structured
71
- // cloneable composite types. This allows types defined with the "interface" keyword to pass the
72
- // serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
73
- type RpcCompatible<T> =
74
- // Structured cloneables
75
- | BaseType
76
- // Structured cloneable composites
77
- | Map<
78
- T extends Map<infer U, unknown> ? RpcCompatible<U> : never,
79
- T extends Map<unknown, infer U> ? RpcCompatible<U> : never
80
- >
81
- | Set<T extends Set<infer U> ? RpcCompatible<U> : never>
82
- | Array<T extends Array<infer U> ? RpcCompatible<U> : never>
83
- | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
84
- | {
85
- [K in keyof T as K extends string | number ? K : never]: RpcCompatible<T[K]>;
86
- }
87
- | Promise<T extends Promise<infer U> ? RpcCompatible<U> : never>
88
- // Special types
89
- | Stub<Stubable>
90
- // Serialized as stubs, see `Stubify`
91
- | Stubable;
92
-
93
- type Stub<T extends RpcCompatible<T>> =
94
- T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
95
-
96
- // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
97
- // prettier-ignore
98
- type Stubify<T> =
99
- T extends Stubable ? Stub<T>
100
- : T extends Promise<infer U> ? Stubify<U>
101
- : T extends StubBase<any> ? T
102
- : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>>
103
- : T extends Set<infer V> ? Set<Stubify<V>>
104
- : T extends [] ? []
105
- : T extends [infer Head, ...infer Tail] ? [Stubify<Head>, ...Stubify<Tail>]
106
- : T extends readonly [] ? readonly []
107
- : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head>, ...Stubify<Tail>]
108
- : T extends Array<infer V> ? Array<Stubify<V>>
109
- : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>>
110
- : T extends BaseType ? T
111
- // When using "unknown" instead of "any", interfaces are not stubified.
112
- : T extends { [key: string | number]: any }
113
- ? {
114
- [K in keyof T as K extends string | number ? K : never]: Stubify<T[K]>;
115
- }
116
- : T;
117
-
118
- // Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
119
- // Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
120
- // `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
121
- // prettier-ignore
122
- type UnstubifyInner<T> =
123
- // Preserve local RpcTarget acceptance, but avoid needless `Stub | Value` unions when the stub
124
- // is already assignable to the value type (important for callback contextual typing).
125
- T extends StubBase<infer V> ? (T extends V ? UnstubifyInner<V> : (T | UnstubifyInner<V>))
126
- : T extends Promise<infer U> ? UnstubifyInner<U>
127
- : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>>
128
- : T extends Set<infer V> ? Set<Unstubify<V>>
129
- : T extends [] ? []
130
- : T extends [infer Head, ...infer Tail] ? [Unstubify<Head>, ...Unstubify<Tail>]
131
- : T extends readonly [] ? readonly []
132
- : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head>, ...Unstubify<Tail>]
133
- : T extends Array<infer V> ? Array<Unstubify<V>>
134
- : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>>
135
- : T extends BaseType ? T
136
- : T extends { [key: string | number]: unknown }
137
- ? {
138
- [K in keyof T as K extends string | number ? K : never]: Unstubify<T[K]>;
139
- }
140
- : T;
141
-
142
- // You can put promises anywhere in the params and they'll be resolved before delivery.
143
- // (This also covers RpcPromise, because it's defined as being a Promise.)
144
- type Unstubify<T> = UnstubifyInner<T> | Promise<UnstubifyInner<T>>;
145
-
146
- type UnstubifyAll<A extends readonly unknown[]> = { [I in keyof A]: Unstubify<A[I]> };
147
-
148
- // Utility type for adding `Disposable`s to `object` types only.
149
- // Note `unknown & T` is equivalent to `T`.
150
- type MaybeDisposable<T> = T extends object ? Disposable : unknown;
151
-
152
- // Type for method return or property on an RPC interface.
153
- // - Stubable types are replaced by stubs.
154
- // - RpcCompatible types are passed by value, with stubable types replaced by stubs
155
- // and a top-level `Disposer`.
156
- // Everything else can't be passed over RPC.
157
- // Technically, we use custom thenables here, but they quack like `Promise`s.
158
- // Intersecting with `(Maybe)Provider` allows pipelining.
159
- type UnknownResult = Promise<unknown> & Provider<unknown> & StubBase<unknown>;
160
-
161
- // prettier-ignore
162
- type Result<R> =
163
- IsAny<R> extends true ? UnknownResult
164
- : IsUnknown<R> extends true ? UnknownResult
165
- : R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<R>
166
- : R extends RpcCompatible<R> ? Promise<Stubify<R> & MaybeDisposable<R>> & Provider<R> & StubBase<R>
167
- : never;
168
-
169
- // Type for method or property on an RPC interface.
170
- // For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
171
- // Unwrapping `Stub`s allows calling with `Stubable` arguments.
172
- // For properties, rewrite types to be `Result`s.
173
- // In each case, unwrap `Promise`s.
174
- type MethodOrProperty<V> = V extends (...args: infer P) => infer R
175
- ? (...args: UnstubifyAll<P>) => (IsAny<R> extends true ? UnknownResult : Result<Awaited<R>>)
176
- : Result<Awaited<V>>;
177
-
178
- // Type for the callable part of an `Provider` if `T` is callable.
179
- // This is intersected with methods/properties.
180
- type MaybeCallableProvider<T> = T extends (...args: any[]) => any
181
- ? MethodOrProperty<T>
182
- : unknown;
183
-
184
- type TupleIndexKeys<T extends ReadonlyArray<unknown>> =
185
- Extract<keyof T, `${number}`>;
186
- type MapCallbackValue<T> =
187
- // `Omit` removes call signatures, so re-intersect callable provider behavior.
188
- T extends unknown ? Omit<Result<T>, keyof Promise<unknown>> & MaybeCallableProvider<T> : never;
189
- type ArrayProvider<E> = {
190
- [K in number]: MethodOrProperty<E>;
191
- } & {
192
- map<V>(callback: (elem: MapCallbackValue<E>) => V): Result<Array<V>>;
193
- };
194
- type TupleProvider<T extends ReadonlyArray<unknown>> = {
195
- [K in TupleIndexKeys<T>]: MethodOrProperty<T[K]>;
196
- } & ArrayProvider<T[number]>;
197
-
198
- // Base type for all other types providing RPC-like interfaces.
199
- // Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
200
- type Provider<T> = MaybeCallableProvider<T> &
201
- (T extends ReadonlyArray<unknown>
202
- ? number extends T["length"] ? ArrayProvider<T[number]> : TupleProvider<T>
203
- : {
204
- [K in Exclude<
205
- keyof T,
206
- symbol | keyof StubBase<never>
207
- >]: MethodOrProperty<T[K]>;
208
- } & {
209
- map<V>(callback: (value: MapCallbackValue<NonNullable<T>>) => V): Result<Array<V>>;
3
+ // Copyright (c) 2025 Cloudflare, Inc.
4
+ // Licensed under the MIT license found in the LICENSE.txt file or at:
5
+ // https://opensource.org/license/mit
6
+
7
+ // This file borrows heavily from `types/defines/rpc.d.ts` in workerd.
8
+
9
+ // Branded types for identifying `WorkerEntrypoint`/`DurableObject`/`Target`s.
10
+ // TypeScript uses *structural* typing meaning anything with the same shape as type `T` is a `T`.
11
+ // For the classes exported by `cloudflare:workers` we want *nominal* typing (i.e. we only want to
12
+ // accept `WorkerEntrypoint` from `cloudflare:workers`, not any other class with the same shape)
13
+ declare const __RPC_STUB_BRAND: '__RPC_STUB_BRAND';
14
+ declare const __RPC_TARGET_BRAND: '__RPC_TARGET_BRAND';
15
+ interface RpcTargetBranded {
16
+ [__RPC_TARGET_BRAND]: never;
17
+ }
18
+
19
+ type IsAny<T> = 0 extends (1 & T) ? true : false;
20
+ type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
21
+
22
+ // Types that can be used through `Stub`s.
23
+ // `never[]` preserves compatibility with strongly-typed function signatures without introducing
24
+ // `any` into inference.
25
+ type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
26
+
27
+ type TypedArray =
28
+ | Uint8Array
29
+ | Uint8ClampedArray
30
+ | Uint16Array
31
+ | Uint32Array
32
+ | Int8Array
33
+ | Int16Array
34
+ | Int32Array
35
+ | BigUint64Array
36
+ | BigInt64Array
37
+ | Float32Array
38
+ | Float64Array;
39
+
40
+ // This represents all the types that can be sent as-is over an RPC boundary
41
+ type BaseType =
42
+ | void
43
+ | undefined
44
+ | null
45
+ | boolean
46
+ | number
47
+ | bigint
48
+ | string
49
+ | TypedArray
50
+ | ArrayBuffer
51
+ | DataView
52
+ | Date
53
+ | Error
54
+ | RegExp
55
+ | ReadableStream<Uint8Array>
56
+ | WritableStream<any> // Chunk type can be any RPC-compatible type
57
+ | Request
58
+ | Response
59
+ | Headers;
60
+
61
+ // Base type for all RPC stubs, including common memory management methods.
62
+ // `T` is used as a marker type for unwrapping `Stub`s later.
63
+ interface StubBase<T = unknown> extends Disposable {
64
+ [__RPC_STUB_BRAND]: T;
65
+ dup(): this;
66
+ onRpcBroken(callback: (error: any) => void): void;
67
+ }
68
+
69
+ // Types that can be passed over RPC.
70
+ // The reason for using a generic type here is to build a serializable subset of structured
71
+ // cloneable composite types. This allows types defined with the "interface" keyword to pass the
72
+ // serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
73
+ type RpcCompatible<T> =
74
+ // Allow `unknown` as a leaf so records/interfaces with `unknown` fields remain compatible.
75
+ | (IsUnknown<T> extends true ? unknown : never)
76
+ // Structured cloneables
77
+ | BaseType
78
+ // Structured cloneable composites
79
+ | Map<
80
+ T extends Map<infer U, unknown> ? RpcCompatible<U> : never,
81
+ T extends Map<unknown, infer U> ? RpcCompatible<U> : never
82
+ >
83
+ | Set<T extends Set<infer U> ? RpcCompatible<U> : never>
84
+ | Array<T extends Array<infer U> ? RpcCompatible<U> : never>
85
+ | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
86
+ | {
87
+ [K in keyof T as K extends string | number ? K : never]: RpcCompatible<T[K]>;
88
+ }
89
+ | Promise<T extends Promise<infer U> ? RpcCompatible<U> : never>
90
+ // Special types
91
+ | Stub<Stubable>
92
+ // Serialized as stubs, see `Stubify`
93
+ | Stubable;
94
+
95
+ type Stub<T extends RpcCompatible<T>> =
96
+ T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
97
+
98
+ // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
99
+ // prettier-ignore
100
+ type Stubify<T> =
101
+ T extends Stubable ? Stub<T>
102
+ : T extends Promise<infer U> ? Stubify<U>
103
+ : T extends StubBase<any> ? T
104
+ : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>>
105
+ : T extends Set<infer V> ? Set<Stubify<V>>
106
+ : T extends [] ? []
107
+ : T extends [infer Head, ...infer Tail] ? [Stubify<Head>, ...Stubify<Tail>]
108
+ : T extends readonly [] ? readonly []
109
+ : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head>, ...Stubify<Tail>]
110
+ : T extends Array<infer V> ? Array<Stubify<V>>
111
+ : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>>
112
+ : T extends BaseType ? T
113
+ // When using "unknown" instead of "any", interfaces are not stubified.
114
+ : T extends { [key: string | number]: any }
115
+ ? {
116
+ [K in keyof T as K extends string | number ? K : never]: Stubify<T[K]>;
117
+ }
118
+ : T;
119
+
120
+ // Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
121
+ // Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
122
+ // `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
123
+ // prettier-ignore
124
+ type UnstubifyInner<T> =
125
+ // Preserve local RpcTarget acceptance, but avoid needless `Stub | Value` unions when the stub
126
+ // is already assignable to the value type (important for callback contextual typing).
127
+ T extends StubBase<infer V> ? (T extends V ? UnstubifyInner<V> : (T | UnstubifyInner<V>))
128
+ : T extends Promise<infer U> ? UnstubifyInner<U>
129
+ : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>>
130
+ : T extends Set<infer V> ? Set<Unstubify<V>>
131
+ : T extends [] ? []
132
+ : T extends [infer Head, ...infer Tail] ? [Unstubify<Head>, ...Unstubify<Tail>]
133
+ : T extends readonly [] ? readonly []
134
+ : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head>, ...Unstubify<Tail>]
135
+ : T extends Array<infer V> ? Array<Unstubify<V>>
136
+ : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>>
137
+ : T extends BaseType ? T
138
+ : T extends { [key: string | number]: unknown }
139
+ ? {
140
+ [K in keyof T as K extends string | number ? K : never]: Unstubify<T[K]>;
141
+ }
142
+ : T;
143
+
144
+ // You can put promises anywhere in the params and they'll be resolved before delivery.
145
+ // (This also covers RpcPromise, because it's defined as being a Promise.)
146
+ type Unstubify<T> = UnstubifyInner<T> | Promise<UnstubifyInner<T>>;
147
+
148
+ type UnstubifyAll<A extends readonly unknown[]> = { [I in keyof A]: Unstubify<A[I]> };
149
+
150
+ // Utility type for adding `Disposable`s to `object` types only.
151
+ // Note `unknown & T` is equivalent to `T`.
152
+ type MaybeDisposable<T> = T extends object ? Disposable : unknown;
153
+
154
+ // Type for method return or property on an RPC interface.
155
+ // - Stubable types are replaced by stubs.
156
+ // - RpcCompatible types are passed by value, with stubable types replaced by stubs
157
+ // and a top-level `Disposer`.
158
+ // Everything else can't be passed over RPC.
159
+ // Technically, we use custom thenables here, but they quack like `Promise`s.
160
+ // Intersecting with `(Maybe)Provider` allows pipelining.
161
+ type UnknownResult = Promise<unknown> & Provider<unknown> & StubBase<unknown>;
162
+
163
+ // prettier-ignore
164
+ type Result<R> =
165
+ IsAny<R> extends true ? UnknownResult
166
+ : IsUnknown<R> extends true ? UnknownResult
167
+ : R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<R>
168
+ : R extends RpcCompatible<R> ? Promise<Stubify<R> & MaybeDisposable<R>> & Provider<R> & StubBase<R>
169
+ : never;
170
+
171
+ // Type for method or property on an RPC interface.
172
+ // For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
173
+ // Unwrapping `Stub`s allows calling with `Stubable` arguments.
174
+ // For properties, rewrite types to be `Result`s.
175
+ // In each case, unwrap `Promise`s.
176
+ type MethodOrProperty<V> = V extends (...args: infer P) => infer R
177
+ ? (...args: UnstubifyAll<P>) => (IsAny<R> extends true ? UnknownResult : Result<Awaited<R>>)
178
+ : Result<Awaited<V>>;
179
+
180
+ // Type for the callable part of an `Provider` if `T` is callable.
181
+ // This is intersected with methods/properties.
182
+ type MaybeCallableProvider<T> = T extends (...args: any[]) => any
183
+ ? MethodOrProperty<T>
184
+ : unknown;
185
+
186
+ type TupleIndexKeys<T extends ReadonlyArray<unknown>> =
187
+ Extract<keyof T, `${number}`>;
188
+ type MapCallbackValue<T> =
189
+ // `Omit` removes call signatures, so re-intersect callable provider behavior.
190
+ T extends unknown ? Omit<Result<T>, keyof Promise<unknown>> & MaybeCallableProvider<T> : never;
191
+ type InvalidNativePromiseInMapResult<T, Seen = never> =
192
+ T extends unknown ? InvalidNativePromiseInMapResultImpl<T, Seen> : never;
193
+ type InvalidNativePromiseInMapResultImpl<T, Seen> =
194
+ [T] extends [Seen] ? never :
195
+ // RpcPromise is modeled as Promise & StubBase, so allow promise-like stub values.
196
+ T extends StubBase<any> ? never
197
+ // Native promises cannot be represented in map recordings.
198
+ : T extends Promise<unknown> ? T
199
+ : T extends Map<infer K, infer V>
200
+ ? InvalidNativePromiseInMapResult<K, Seen | T> | InvalidNativePromiseInMapResult<V, Seen | T>
201
+ : T extends Set<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T>
202
+ : T extends [] ? never
203
+ : T extends [infer Head, ...infer Tail]
204
+ ? InvalidNativePromiseInMapResult<Head, Seen | T>
205
+ | InvalidNativePromiseInMapResult<Tail[number], Seen | T>
206
+ : T extends readonly [] ? never
207
+ : T extends readonly [infer Head, ...infer Tail]
208
+ ? InvalidNativePromiseInMapResult<Head, Seen | T>
209
+ | InvalidNativePromiseInMapResult<Tail[number], Seen | T>
210
+ : T extends Array<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T>
211
+ : T extends ReadonlyArray<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T>
212
+ : T extends { [key: string | number]: unknown }
213
+ ? InvalidNativePromiseInMapResult<T[Extract<keyof T, string | number>], Seen | T>
214
+ : never;
215
+ type MapCallbackReturn<T> =
216
+ InvalidNativePromiseInMapResult<T> extends never ? T : never;
217
+ type ArrayProvider<E> = {
218
+ [K in number]: MethodOrProperty<E>;
219
+ } & {
220
+ map<V>(callback: (elem: MapCallbackValue<E>) => MapCallbackReturn<V>): Result<Array<V>>;
221
+ };
222
+ type TupleProvider<T extends ReadonlyArray<unknown>> = {
223
+ [K in TupleIndexKeys<T>]: MethodOrProperty<T[K]>;
224
+ } & ArrayProvider<T[number]>;
225
+
226
+ // Base type for all other types providing RPC-like interfaces.
227
+ // Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
228
+ type Provider<T> = MaybeCallableProvider<T> &
229
+ (T extends ReadonlyArray<unknown>
230
+ ? number extends T["length"] ? ArrayProvider<T[number]> : TupleProvider<T>
231
+ : {
232
+ [K in Exclude<
233
+ keyof T,
234
+ symbol | keyof StubBase<never>
235
+ >]: MethodOrProperty<T[K]>;
236
+ } & {
237
+ map<V>(callback: (value: MapCallbackValue<NonNullable<T>>) => MapCallbackReturn<V>): Result<Array<V>>;
210
238
  });
211
239
 
212
240
  /**
package/dist/index.d.ts CHANGED
@@ -1,212 +1,240 @@
1
1
  import { IncomingMessage, ServerResponse, OutgoingHttpHeaders, OutgoingHttpHeader } from 'node:http';
2
2
 
3
- // Copyright (c) 2025 Cloudflare, Inc.
4
- // Licensed under the MIT license found in the LICENSE.txt file or at:
5
- // https://opensource.org/license/mit
6
-
7
- // This file borrows heavily from `types/defines/rpc.d.ts` in workerd.
8
-
9
- // Branded types for identifying `WorkerEntrypoint`/`DurableObject`/`Target`s.
10
- // TypeScript uses *structural* typing meaning anything with the same shape as type `T` is a `T`.
11
- // For the classes exported by `cloudflare:workers` we want *nominal* typing (i.e. we only want to
12
- // accept `WorkerEntrypoint` from `cloudflare:workers`, not any other class with the same shape)
13
- declare const __RPC_STUB_BRAND: '__RPC_STUB_BRAND';
14
- declare const __RPC_TARGET_BRAND: '__RPC_TARGET_BRAND';
15
- interface RpcTargetBranded {
16
- [__RPC_TARGET_BRAND]: never;
17
- }
18
-
19
- type IsAny<T> = 0 extends (1 & T) ? true : false;
20
- type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
21
-
22
- // Types that can be used through `Stub`s.
23
- // `never[]` preserves compatibility with strongly-typed function signatures without introducing
24
- // `any` into inference.
25
- type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
26
-
27
- type TypedArray =
28
- | Uint8Array
29
- | Uint8ClampedArray
30
- | Uint16Array
31
- | Uint32Array
32
- | Int8Array
33
- | Int16Array
34
- | Int32Array
35
- | BigUint64Array
36
- | BigInt64Array
37
- | Float32Array
38
- | Float64Array;
39
-
40
- // This represents all the types that can be sent as-is over an RPC boundary
41
- type BaseType =
42
- | void
43
- | undefined
44
- | null
45
- | boolean
46
- | number
47
- | bigint
48
- | string
49
- | TypedArray
50
- | ArrayBuffer
51
- | DataView
52
- | Date
53
- | Error
54
- | RegExp
55
- | ReadableStream<Uint8Array>
56
- | WritableStream<any> // Chunk type can be any RPC-compatible type
57
- | Request
58
- | Response
59
- | Headers;
60
-
61
- // Base type for all RPC stubs, including common memory management methods.
62
- // `T` is used as a marker type for unwrapping `Stub`s later.
63
- interface StubBase<T = unknown> extends Disposable {
64
- [__RPC_STUB_BRAND]: T;
65
- dup(): this;
66
- onRpcBroken(callback: (error: any) => void): void;
67
- }
68
-
69
- // Types that can be passed over RPC.
70
- // The reason for using a generic type here is to build a serializable subset of structured
71
- // cloneable composite types. This allows types defined with the "interface" keyword to pass the
72
- // serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
73
- type RpcCompatible<T> =
74
- // Structured cloneables
75
- | BaseType
76
- // Structured cloneable composites
77
- | Map<
78
- T extends Map<infer U, unknown> ? RpcCompatible<U> : never,
79
- T extends Map<unknown, infer U> ? RpcCompatible<U> : never
80
- >
81
- | Set<T extends Set<infer U> ? RpcCompatible<U> : never>
82
- | Array<T extends Array<infer U> ? RpcCompatible<U> : never>
83
- | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
84
- | {
85
- [K in keyof T as K extends string | number ? K : never]: RpcCompatible<T[K]>;
86
- }
87
- | Promise<T extends Promise<infer U> ? RpcCompatible<U> : never>
88
- // Special types
89
- | Stub<Stubable>
90
- // Serialized as stubs, see `Stubify`
91
- | Stubable;
92
-
93
- type Stub<T extends RpcCompatible<T>> =
94
- T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
95
-
96
- // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
97
- // prettier-ignore
98
- type Stubify<T> =
99
- T extends Stubable ? Stub<T>
100
- : T extends Promise<infer U> ? Stubify<U>
101
- : T extends StubBase<any> ? T
102
- : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>>
103
- : T extends Set<infer V> ? Set<Stubify<V>>
104
- : T extends [] ? []
105
- : T extends [infer Head, ...infer Tail] ? [Stubify<Head>, ...Stubify<Tail>]
106
- : T extends readonly [] ? readonly []
107
- : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head>, ...Stubify<Tail>]
108
- : T extends Array<infer V> ? Array<Stubify<V>>
109
- : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>>
110
- : T extends BaseType ? T
111
- // When using "unknown" instead of "any", interfaces are not stubified.
112
- : T extends { [key: string | number]: any }
113
- ? {
114
- [K in keyof T as K extends string | number ? K : never]: Stubify<T[K]>;
115
- }
116
- : T;
117
-
118
- // Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
119
- // Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
120
- // `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
121
- // prettier-ignore
122
- type UnstubifyInner<T> =
123
- // Preserve local RpcTarget acceptance, but avoid needless `Stub | Value` unions when the stub
124
- // is already assignable to the value type (important for callback contextual typing).
125
- T extends StubBase<infer V> ? (T extends V ? UnstubifyInner<V> : (T | UnstubifyInner<V>))
126
- : T extends Promise<infer U> ? UnstubifyInner<U>
127
- : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>>
128
- : T extends Set<infer V> ? Set<Unstubify<V>>
129
- : T extends [] ? []
130
- : T extends [infer Head, ...infer Tail] ? [Unstubify<Head>, ...Unstubify<Tail>]
131
- : T extends readonly [] ? readonly []
132
- : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head>, ...Unstubify<Tail>]
133
- : T extends Array<infer V> ? Array<Unstubify<V>>
134
- : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>>
135
- : T extends BaseType ? T
136
- : T extends { [key: string | number]: unknown }
137
- ? {
138
- [K in keyof T as K extends string | number ? K : never]: Unstubify<T[K]>;
139
- }
140
- : T;
141
-
142
- // You can put promises anywhere in the params and they'll be resolved before delivery.
143
- // (This also covers RpcPromise, because it's defined as being a Promise.)
144
- type Unstubify<T> = UnstubifyInner<T> | Promise<UnstubifyInner<T>>;
145
-
146
- type UnstubifyAll<A extends readonly unknown[]> = { [I in keyof A]: Unstubify<A[I]> };
147
-
148
- // Utility type for adding `Disposable`s to `object` types only.
149
- // Note `unknown & T` is equivalent to `T`.
150
- type MaybeDisposable<T> = T extends object ? Disposable : unknown;
151
-
152
- // Type for method return or property on an RPC interface.
153
- // - Stubable types are replaced by stubs.
154
- // - RpcCompatible types are passed by value, with stubable types replaced by stubs
155
- // and a top-level `Disposer`.
156
- // Everything else can't be passed over RPC.
157
- // Technically, we use custom thenables here, but they quack like `Promise`s.
158
- // Intersecting with `(Maybe)Provider` allows pipelining.
159
- type UnknownResult = Promise<unknown> & Provider<unknown> & StubBase<unknown>;
160
-
161
- // prettier-ignore
162
- type Result<R> =
163
- IsAny<R> extends true ? UnknownResult
164
- : IsUnknown<R> extends true ? UnknownResult
165
- : R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<R>
166
- : R extends RpcCompatible<R> ? Promise<Stubify<R> & MaybeDisposable<R>> & Provider<R> & StubBase<R>
167
- : never;
168
-
169
- // Type for method or property on an RPC interface.
170
- // For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
171
- // Unwrapping `Stub`s allows calling with `Stubable` arguments.
172
- // For properties, rewrite types to be `Result`s.
173
- // In each case, unwrap `Promise`s.
174
- type MethodOrProperty<V> = V extends (...args: infer P) => infer R
175
- ? (...args: UnstubifyAll<P>) => (IsAny<R> extends true ? UnknownResult : Result<Awaited<R>>)
176
- : Result<Awaited<V>>;
177
-
178
- // Type for the callable part of an `Provider` if `T` is callable.
179
- // This is intersected with methods/properties.
180
- type MaybeCallableProvider<T> = T extends (...args: any[]) => any
181
- ? MethodOrProperty<T>
182
- : unknown;
183
-
184
- type TupleIndexKeys<T extends ReadonlyArray<unknown>> =
185
- Extract<keyof T, `${number}`>;
186
- type MapCallbackValue<T> =
187
- // `Omit` removes call signatures, so re-intersect callable provider behavior.
188
- T extends unknown ? Omit<Result<T>, keyof Promise<unknown>> & MaybeCallableProvider<T> : never;
189
- type ArrayProvider<E> = {
190
- [K in number]: MethodOrProperty<E>;
191
- } & {
192
- map<V>(callback: (elem: MapCallbackValue<E>) => V): Result<Array<V>>;
193
- };
194
- type TupleProvider<T extends ReadonlyArray<unknown>> = {
195
- [K in TupleIndexKeys<T>]: MethodOrProperty<T[K]>;
196
- } & ArrayProvider<T[number]>;
197
-
198
- // Base type for all other types providing RPC-like interfaces.
199
- // Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
200
- type Provider<T> = MaybeCallableProvider<T> &
201
- (T extends ReadonlyArray<unknown>
202
- ? number extends T["length"] ? ArrayProvider<T[number]> : TupleProvider<T>
203
- : {
204
- [K in Exclude<
205
- keyof T,
206
- symbol | keyof StubBase<never>
207
- >]: MethodOrProperty<T[K]>;
208
- } & {
209
- map<V>(callback: (value: MapCallbackValue<NonNullable<T>>) => V): Result<Array<V>>;
3
+ // Copyright (c) 2025 Cloudflare, Inc.
4
+ // Licensed under the MIT license found in the LICENSE.txt file or at:
5
+ // https://opensource.org/license/mit
6
+
7
+ // This file borrows heavily from `types/defines/rpc.d.ts` in workerd.
8
+
9
+ // Branded types for identifying `WorkerEntrypoint`/`DurableObject`/`Target`s.
10
+ // TypeScript uses *structural* typing meaning anything with the same shape as type `T` is a `T`.
11
+ // For the classes exported by `cloudflare:workers` we want *nominal* typing (i.e. we only want to
12
+ // accept `WorkerEntrypoint` from `cloudflare:workers`, not any other class with the same shape)
13
+ declare const __RPC_STUB_BRAND: '__RPC_STUB_BRAND';
14
+ declare const __RPC_TARGET_BRAND: '__RPC_TARGET_BRAND';
15
+ interface RpcTargetBranded {
16
+ [__RPC_TARGET_BRAND]: never;
17
+ }
18
+
19
+ type IsAny<T> = 0 extends (1 & T) ? true : false;
20
+ type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
21
+
22
+ // Types that can be used through `Stub`s.
23
+ // `never[]` preserves compatibility with strongly-typed function signatures without introducing
24
+ // `any` into inference.
25
+ type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
26
+
27
+ type TypedArray =
28
+ | Uint8Array
29
+ | Uint8ClampedArray
30
+ | Uint16Array
31
+ | Uint32Array
32
+ | Int8Array
33
+ | Int16Array
34
+ | Int32Array
35
+ | BigUint64Array
36
+ | BigInt64Array
37
+ | Float32Array
38
+ | Float64Array;
39
+
40
+ // This represents all the types that can be sent as-is over an RPC boundary
41
+ type BaseType =
42
+ | void
43
+ | undefined
44
+ | null
45
+ | boolean
46
+ | number
47
+ | bigint
48
+ | string
49
+ | TypedArray
50
+ | ArrayBuffer
51
+ | DataView
52
+ | Date
53
+ | Error
54
+ | RegExp
55
+ | ReadableStream<Uint8Array>
56
+ | WritableStream<any> // Chunk type can be any RPC-compatible type
57
+ | Request
58
+ | Response
59
+ | Headers;
60
+
61
+ // Base type for all RPC stubs, including common memory management methods.
62
+ // `T` is used as a marker type for unwrapping `Stub`s later.
63
+ interface StubBase<T = unknown> extends Disposable {
64
+ [__RPC_STUB_BRAND]: T;
65
+ dup(): this;
66
+ onRpcBroken(callback: (error: any) => void): void;
67
+ }
68
+
69
+ // Types that can be passed over RPC.
70
+ // The reason for using a generic type here is to build a serializable subset of structured
71
+ // cloneable composite types. This allows types defined with the "interface" keyword to pass the
72
+ // serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
73
+ type RpcCompatible<T> =
74
+ // Allow `unknown` as a leaf so records/interfaces with `unknown` fields remain compatible.
75
+ | (IsUnknown<T> extends true ? unknown : never)
76
+ // Structured cloneables
77
+ | BaseType
78
+ // Structured cloneable composites
79
+ | Map<
80
+ T extends Map<infer U, unknown> ? RpcCompatible<U> : never,
81
+ T extends Map<unknown, infer U> ? RpcCompatible<U> : never
82
+ >
83
+ | Set<T extends Set<infer U> ? RpcCompatible<U> : never>
84
+ | Array<T extends Array<infer U> ? RpcCompatible<U> : never>
85
+ | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
86
+ | {
87
+ [K in keyof T as K extends string | number ? K : never]: RpcCompatible<T[K]>;
88
+ }
89
+ | Promise<T extends Promise<infer U> ? RpcCompatible<U> : never>
90
+ // Special types
91
+ | Stub<Stubable>
92
+ // Serialized as stubs, see `Stubify`
93
+ | Stubable;
94
+
95
+ type Stub<T extends RpcCompatible<T>> =
96
+ T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
97
+
98
+ // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
99
+ // prettier-ignore
100
+ type Stubify<T> =
101
+ T extends Stubable ? Stub<T>
102
+ : T extends Promise<infer U> ? Stubify<U>
103
+ : T extends StubBase<any> ? T
104
+ : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>>
105
+ : T extends Set<infer V> ? Set<Stubify<V>>
106
+ : T extends [] ? []
107
+ : T extends [infer Head, ...infer Tail] ? [Stubify<Head>, ...Stubify<Tail>]
108
+ : T extends readonly [] ? readonly []
109
+ : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head>, ...Stubify<Tail>]
110
+ : T extends Array<infer V> ? Array<Stubify<V>>
111
+ : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>>
112
+ : T extends BaseType ? T
113
+ // When using "unknown" instead of "any", interfaces are not stubified.
114
+ : T extends { [key: string | number]: any }
115
+ ? {
116
+ [K in keyof T as K extends string | number ? K : never]: Stubify<T[K]>;
117
+ }
118
+ : T;
119
+
120
+ // Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
121
+ // Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
122
+ // `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
123
+ // prettier-ignore
124
+ type UnstubifyInner<T> =
125
+ // Preserve local RpcTarget acceptance, but avoid needless `Stub | Value` unions when the stub
126
+ // is already assignable to the value type (important for callback contextual typing).
127
+ T extends StubBase<infer V> ? (T extends V ? UnstubifyInner<V> : (T | UnstubifyInner<V>))
128
+ : T extends Promise<infer U> ? UnstubifyInner<U>
129
+ : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>>
130
+ : T extends Set<infer V> ? Set<Unstubify<V>>
131
+ : T extends [] ? []
132
+ : T extends [infer Head, ...infer Tail] ? [Unstubify<Head>, ...Unstubify<Tail>]
133
+ : T extends readonly [] ? readonly []
134
+ : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head>, ...Unstubify<Tail>]
135
+ : T extends Array<infer V> ? Array<Unstubify<V>>
136
+ : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>>
137
+ : T extends BaseType ? T
138
+ : T extends { [key: string | number]: unknown }
139
+ ? {
140
+ [K in keyof T as K extends string | number ? K : never]: Unstubify<T[K]>;
141
+ }
142
+ : T;
143
+
144
+ // You can put promises anywhere in the params and they'll be resolved before delivery.
145
+ // (This also covers RpcPromise, because it's defined as being a Promise.)
146
+ type Unstubify<T> = UnstubifyInner<T> | Promise<UnstubifyInner<T>>;
147
+
148
+ type UnstubifyAll<A extends readonly unknown[]> = { [I in keyof A]: Unstubify<A[I]> };
149
+
150
+ // Utility type for adding `Disposable`s to `object` types only.
151
+ // Note `unknown & T` is equivalent to `T`.
152
+ type MaybeDisposable<T> = T extends object ? Disposable : unknown;
153
+
154
+ // Type for method return or property on an RPC interface.
155
+ // - Stubable types are replaced by stubs.
156
+ // - RpcCompatible types are passed by value, with stubable types replaced by stubs
157
+ // and a top-level `Disposer`.
158
+ // Everything else can't be passed over RPC.
159
+ // Technically, we use custom thenables here, but they quack like `Promise`s.
160
+ // Intersecting with `(Maybe)Provider` allows pipelining.
161
+ type UnknownResult = Promise<unknown> & Provider<unknown> & StubBase<unknown>;
162
+
163
+ // prettier-ignore
164
+ type Result<R> =
165
+ IsAny<R> extends true ? UnknownResult
166
+ : IsUnknown<R> extends true ? UnknownResult
167
+ : R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<R>
168
+ : R extends RpcCompatible<R> ? Promise<Stubify<R> & MaybeDisposable<R>> & Provider<R> & StubBase<R>
169
+ : never;
170
+
171
+ // Type for method or property on an RPC interface.
172
+ // For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
173
+ // Unwrapping `Stub`s allows calling with `Stubable` arguments.
174
+ // For properties, rewrite types to be `Result`s.
175
+ // In each case, unwrap `Promise`s.
176
+ type MethodOrProperty<V> = V extends (...args: infer P) => infer R
177
+ ? (...args: UnstubifyAll<P>) => (IsAny<R> extends true ? UnknownResult : Result<Awaited<R>>)
178
+ : Result<Awaited<V>>;
179
+
180
+ // Type for the callable part of an `Provider` if `T` is callable.
181
+ // This is intersected with methods/properties.
182
+ type MaybeCallableProvider<T> = T extends (...args: any[]) => any
183
+ ? MethodOrProperty<T>
184
+ : unknown;
185
+
186
+ type TupleIndexKeys<T extends ReadonlyArray<unknown>> =
187
+ Extract<keyof T, `${number}`>;
188
+ type MapCallbackValue<T> =
189
+ // `Omit` removes call signatures, so re-intersect callable provider behavior.
190
+ T extends unknown ? Omit<Result<T>, keyof Promise<unknown>> & MaybeCallableProvider<T> : never;
191
+ type InvalidNativePromiseInMapResult<T, Seen = never> =
192
+ T extends unknown ? InvalidNativePromiseInMapResultImpl<T, Seen> : never;
193
+ type InvalidNativePromiseInMapResultImpl<T, Seen> =
194
+ [T] extends [Seen] ? never :
195
+ // RpcPromise is modeled as Promise & StubBase, so allow promise-like stub values.
196
+ T extends StubBase<any> ? never
197
+ // Native promises cannot be represented in map recordings.
198
+ : T extends Promise<unknown> ? T
199
+ : T extends Map<infer K, infer V>
200
+ ? InvalidNativePromiseInMapResult<K, Seen | T> | InvalidNativePromiseInMapResult<V, Seen | T>
201
+ : T extends Set<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T>
202
+ : T extends [] ? never
203
+ : T extends [infer Head, ...infer Tail]
204
+ ? InvalidNativePromiseInMapResult<Head, Seen | T>
205
+ | InvalidNativePromiseInMapResult<Tail[number], Seen | T>
206
+ : T extends readonly [] ? never
207
+ : T extends readonly [infer Head, ...infer Tail]
208
+ ? InvalidNativePromiseInMapResult<Head, Seen | T>
209
+ | InvalidNativePromiseInMapResult<Tail[number], Seen | T>
210
+ : T extends Array<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T>
211
+ : T extends ReadonlyArray<infer V> ? InvalidNativePromiseInMapResult<V, Seen | T>
212
+ : T extends { [key: string | number]: unknown }
213
+ ? InvalidNativePromiseInMapResult<T[Extract<keyof T, string | number>], Seen | T>
214
+ : never;
215
+ type MapCallbackReturn<T> =
216
+ InvalidNativePromiseInMapResult<T> extends never ? T : never;
217
+ type ArrayProvider<E> = {
218
+ [K in number]: MethodOrProperty<E>;
219
+ } & {
220
+ map<V>(callback: (elem: MapCallbackValue<E>) => MapCallbackReturn<V>): Result<Array<V>>;
221
+ };
222
+ type TupleProvider<T extends ReadonlyArray<unknown>> = {
223
+ [K in TupleIndexKeys<T>]: MethodOrProperty<T[K]>;
224
+ } & ArrayProvider<T[number]>;
225
+
226
+ // Base type for all other types providing RPC-like interfaces.
227
+ // Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
228
+ type Provider<T> = MaybeCallableProvider<T> &
229
+ (T extends ReadonlyArray<unknown>
230
+ ? number extends T["length"] ? ArrayProvider<T[number]> : TupleProvider<T>
231
+ : {
232
+ [K in Exclude<
233
+ keyof T,
234
+ symbol | keyof StubBase<never>
235
+ >]: MethodOrProperty<T[K]>;
236
+ } & {
237
+ map<V>(callback: (value: MapCallbackValue<NonNullable<T>>) => MapCallbackReturn<V>): Result<Array<V>>;
210
238
  });
211
239
 
212
240
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vastblast/capnweb",
3
- "version": "0.5.0",
3
+ "version": "0.5.2",
4
4
  "description": "JavaScript/TypeScript-native RPC library with Promise Pipelining",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",