@vastblast/capnweb 0.4.1 → 0.4.3

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 (15) hide show
  1. package/LICENSE.txt +0 -0
  2. package/README.md +0 -0
  3. package/dist/index-workers.cjs +0 -0
  4. package/dist/index-workers.cjs.map +0 -0
  5. package/dist/index-workers.d.cts +0 -0
  6. package/dist/index-workers.d.ts +0 -0
  7. package/dist/index-workers.js +0 -0
  8. package/dist/index-workers.js.map +0 -0
  9. package/dist/index.cjs +0 -0
  10. package/dist/index.cjs.map +0 -0
  11. package/dist/index.d.cts +202 -179
  12. package/dist/index.d.ts +202 -179
  13. package/dist/index.js +0 -0
  14. package/dist/index.js.map +0 -0
  15. package/package.json +2 -1
package/LICENSE.txt CHANGED
File without changes
package/README.md CHANGED
File without changes
package/dist/index-workers.cjs CHANGED
File without changes
package/dist/index-workers.cjs.map CHANGED
File without changes
package/dist/index-workers.d.cts CHANGED
File without changes
package/dist/index-workers.d.ts CHANGED
File without changes
package/dist/index-workers.js CHANGED
File without changes
package/dist/index-workers.js.map CHANGED
File without changes
package/dist/index.cjs CHANGED
File without changes
package/dist/index.cjs.map CHANGED
File without changes
package/dist/index.d.cts CHANGED
@@ -1,184 +1,207 @@
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
- // Types that can be used through `Stub`s
20
- type Stubable = RpcTargetBranded | ((...args: any[]) => any);
21
-
22
- // Types that can be passed over RPC
23
- // The reason for using a generic type here is to build a serializable subset of structured
24
- // cloneable composite types. This allows types defined with the "interface" keyword to pass the
25
- // serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
26
- type RpcCompatible<T> =
27
- // Structured cloneables
28
- | BaseType
29
- // Structured cloneable composites
30
- | Map<
31
- T extends Map<infer U, unknown> ? RpcCompatible<U> : never,
32
- T extends Map<unknown, infer U> ? RpcCompatible<U> : never
33
- >
34
- | Set<T extends Set<infer U> ? RpcCompatible<U> : never>
35
- | Array<T extends Array<infer U> ? RpcCompatible<U> : never>
36
- | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
37
- | {
38
- [K in keyof T as K extends string | number ? K : never]: RpcCompatible<T[K]>;
39
- }
40
- | Promise<T extends Promise<infer U> ? RpcCompatible<U> : never>
41
- // Special types
42
- | Stub<Stubable>
43
- // Serialized as stubs, see `Stubify`
44
- | Stubable;
45
-
46
- // Base type for all RPC stubs, including common memory management methods.
47
- // `T` is used as a marker type for unwrapping `Stub`s later.
48
- interface StubBase<T extends RpcCompatible<T>> extends Disposable {
49
- [__RPC_STUB_BRAND]: T;
50
- dup(): this;
51
- onRpcBroken(callback: (error: any) => void): void;
52
- }
53
- type Stub<T extends RpcCompatible<T>> =
54
- T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
55
-
56
- type TypedArray =
57
- | Uint8Array
58
- | Uint8ClampedArray
59
- | Uint16Array
60
- | Uint32Array
61
- | Int8Array
62
- | Int16Array
63
- | Int32Array
64
- | BigUint64Array
65
- | BigInt64Array
66
- | Float32Array
67
- | Float64Array;
68
-
69
- // This represents all the types that can be sent as-is over an RPC boundary
70
- type BaseType =
71
- | void
72
- | undefined
73
- | null
74
- | boolean
75
- | number
76
- | bigint
77
- | string
78
- | TypedArray
79
- | ArrayBuffer
80
- | DataView
81
- | Date
82
- | Error
83
- | RegExp
84
- | ReadableStream<Uint8Array>
85
- | WritableStream<any> // Chunk type can be any RPC-compatible type
86
- | Request
87
- | Response
88
- | Headers;
89
- // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
90
- // prettier-ignore
91
- type Stubify<T> =
92
- T extends Stubable ? Stub<T>
93
- : T extends Promise<infer U> ? Stubify<U>
94
- : T extends StubBase<any> ? T
95
- : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>>
96
- : T extends Set<infer V> ? Set<Stubify<V>>
97
- : T extends [] ? []
98
- : T extends [infer Head, ...infer Tail] ? [Stubify<Head>, ...Stubify<Tail>]
99
- : T extends readonly [] ? readonly []
100
- : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head>, ...Stubify<Tail>]
101
- : T extends Array<infer V> ? Array<Stubify<V>>
102
- : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>>
103
- : T extends BaseType ? T
104
- // When using "unknown" instead of "any", interfaces are not stubified.
105
- : T extends { [key: string | number]: any } ? { [K in keyof T]: Stubify<T[K]> }
106
- : T;
107
-
108
- // Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
109
- // Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
110
- // `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
111
- // prettier-ignore
112
- type UnstubifyInner<T> =
113
- // Keep local RpcTarget acceptance, but avoid `Stub | Value` unions when the stub
114
- // is already assignable to the value type (needed for callback contextual typing).
115
- T extends StubBase<infer V> ? (T extends V ? V : (T | V))
116
- : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>>
117
- : T extends Set<infer V> ? Set<Unstubify<V>>
118
- : T extends [] ? []
119
- : T extends [infer Head, ...infer Tail] ? [Unstubify<Head>, ...Unstubify<Tail>]
120
- : T extends readonly [] ? readonly []
121
- : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head>, ...Unstubify<Tail>]
122
- : T extends Array<infer V> ? Array<Unstubify<V>>
123
- : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>>
124
- : T extends BaseType ? T
125
- : T extends { [key: string | number]: unknown } ? { [K in keyof T]: Unstubify<T[K]> }
126
- : T;
127
-
128
- // You can put promises anywhere in the params and they'll be resolved before delivery.
129
- // (This also covers RpcPromise, because it's defined as being a Promise.)
130
- type Unstubify<T> = UnstubifyInner<T> | Promise<UnstubifyInner<T>>
131
-
132
- type UnstubifyAll<A extends any[]> = { [I in keyof A]: Unstubify<A[I]> };
133
-
134
- // Utility type for adding `Disposable`s to `object` types only.
135
- // Note `unknown & T` is equivalent to `T`.
136
- type MaybeDisposable<T> = T extends object ? Disposable : unknown;
137
-
138
- // Type for method return or property on an RPC interface.
139
- // - Stubable types are replaced by stubs.
140
- // - RpcCompatible types are passed by value, with stubable types replaced by stubs
141
- // and a top-level `Disposer`.
142
- // Everything else can't be passed over RPC.
143
- // Technically, we use custom thenables here, but they quack like `Promise`s.
144
- // Intersecting with `(Maybe)Provider` allows pipelining.
145
- // prettier-ignore
146
- type Result<R> =
147
- R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<R>
148
- : R extends RpcCompatible<R> ? Promise<Stubify<R> & MaybeDisposable<R>> & Provider<R> & StubBase<R>
149
- : never;
150
-
151
- // Type for method or property on an RPC interface.
152
- // For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
153
- // Unwrapping `Stub`s allows calling with `Stubable` arguments.
154
- // For properties, rewrite types to be `Result`s.
155
- // In each case, unwrap `Promise`s.
156
- type MethodOrProperty<V> = V extends (...args: infer P) => infer R
157
- ? (...args: UnstubifyAll<P>) => Result<Awaited<R>>
158
- : Result<Awaited<V>>;
159
-
160
- // Type for the callable part of an `Provider` if `T` is callable.
161
- // This is intersected with methods/properties.
162
- type MaybeCallableProvider<T> = T extends (...args: any[]) => any
163
- ? MethodOrProperty<T>
164
- : unknown;
165
-
166
- // Base type for all other types providing RPC-like interfaces.
167
- // Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
168
- type Provider<T> = MaybeCallableProvider<T> &
169
- (T extends Array<infer U>
170
- ? {
171
- [key: number]: MethodOrProperty<U>;
172
- } & {
173
- map<V>(callback: (elem: U) => V): Result<Array<V>>;
174
- }
175
- : {
176
- [K in Exclude<
177
- keyof T,
178
- symbol | keyof StubBase<never>
179
- >]: MethodOrProperty<T[K]>;
180
- } & {
181
- map<V>(callback: (value: 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
+ // 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 HasAnyFunctionParts<P extends readonly unknown[], R> =
170
+ IsAny<R> extends true ? true : IsAny<P[number]>;
171
+
172
+ // Type for method or property on an RPC interface.
173
+ // For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
174
+ // Unwrapping `Stub`s allows calling with `Stubable` arguments.
175
+ // For properties, rewrite types to be `Result`s.
176
+ // In each case, unwrap `Promise`s.
177
+ type MethodOrProperty<V> = V extends (...args: infer P) => infer R
178
+ ? HasAnyFunctionParts<P, R> extends true
179
+ ? (...args: unknown[]) => UnknownResult
180
+ : (...args: UnstubifyAll<P>) => Result<Awaited<R>>
181
+ : Result<Awaited<V>>;
182
+
183
+ // Type for the callable part of a `Provider` if `T` is callable.
184
+ // This is intersected with methods/properties.
185
+ type MaybeCallableProvider<T> = T extends (...args: any[]) => any
186
+ ? MethodOrProperty<T>
187
+ : unknown;
188
+
189
+ // Base type for all other types providing RPC-like interfaces.
190
+ // Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
191
+ type Provider<T> = MaybeCallableProvider<T> &
192
+ (T extends Array<infer U>
193
+ ? {
194
+ [key: number]: MethodOrProperty<U>;
195
+ } & {
196
+ map<V>(callback: (elem: Result<U>) => V): Result<Array<V>>;
197
+ }
198
+ : {
199
+ [K in Exclude<
200
+ keyof T,
201
+ symbol | keyof StubBase<never>
202
+ >]: MethodOrProperty<T[K]>;
203
+ } & {
204
+ map<V>(callback: (value: Result<NonNullable<T>>) => V): Result<Array<V>>;
182
205
  });
183
206
 
184
207
  /**
package/dist/index.d.ts CHANGED
@@ -1,184 +1,207 @@
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
- // Types that can be used through `Stub`s
20
- type Stubable = RpcTargetBranded | ((...args: any[]) => any);
21
-
22
- // Types that can be passed over RPC
23
- // The reason for using a generic type here is to build a serializable subset of structured
24
- // cloneable composite types. This allows types defined with the "interface" keyword to pass the
25
- // serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
26
- type RpcCompatible<T> =
27
- // Structured cloneables
28
- | BaseType
29
- // Structured cloneable composites
30
- | Map<
31
- T extends Map<infer U, unknown> ? RpcCompatible<U> : never,
32
- T extends Map<unknown, infer U> ? RpcCompatible<U> : never
33
- >
34
- | Set<T extends Set<infer U> ? RpcCompatible<U> : never>
35
- | Array<T extends Array<infer U> ? RpcCompatible<U> : never>
36
- | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never>
37
- | {
38
- [K in keyof T as K extends string | number ? K : never]: RpcCompatible<T[K]>;
39
- }
40
- | Promise<T extends Promise<infer U> ? RpcCompatible<U> : never>
41
- // Special types
42
- | Stub<Stubable>
43
- // Serialized as stubs, see `Stubify`
44
- | Stubable;
45
-
46
- // Base type for all RPC stubs, including common memory management methods.
47
- // `T` is used as a marker type for unwrapping `Stub`s later.
48
- interface StubBase<T extends RpcCompatible<T>> extends Disposable {
49
- [__RPC_STUB_BRAND]: T;
50
- dup(): this;
51
- onRpcBroken(callback: (error: any) => void): void;
52
- }
53
- type Stub<T extends RpcCompatible<T>> =
54
- T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
55
-
56
- type TypedArray =
57
- | Uint8Array
58
- | Uint8ClampedArray
59
- | Uint16Array
60
- | Uint32Array
61
- | Int8Array
62
- | Int16Array
63
- | Int32Array
64
- | BigUint64Array
65
- | BigInt64Array
66
- | Float32Array
67
- | Float64Array;
68
-
69
- // This represents all the types that can be sent as-is over an RPC boundary
70
- type BaseType =
71
- | void
72
- | undefined
73
- | null
74
- | boolean
75
- | number
76
- | bigint
77
- | string
78
- | TypedArray
79
- | ArrayBuffer
80
- | DataView
81
- | Date
82
- | Error
83
- | RegExp
84
- | ReadableStream<Uint8Array>
85
- | WritableStream<any> // Chunk type can be any RPC-compatible type
86
- | Request
87
- | Response
88
- | Headers;
89
- // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
90
- // prettier-ignore
91
- type Stubify<T> =
92
- T extends Stubable ? Stub<T>
93
- : T extends Promise<infer U> ? Stubify<U>
94
- : T extends StubBase<any> ? T
95
- : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>>
96
- : T extends Set<infer V> ? Set<Stubify<V>>
97
- : T extends [] ? []
98
- : T extends [infer Head, ...infer Tail] ? [Stubify<Head>, ...Stubify<Tail>]
99
- : T extends readonly [] ? readonly []
100
- : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head>, ...Stubify<Tail>]
101
- : T extends Array<infer V> ? Array<Stubify<V>>
102
- : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>>
103
- : T extends BaseType ? T
104
- // When using "unknown" instead of "any", interfaces are not stubified.
105
- : T extends { [key: string | number]: any } ? { [K in keyof T]: Stubify<T[K]> }
106
- : T;
107
-
108
- // Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
109
- // Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
110
- // `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
111
- // prettier-ignore
112
- type UnstubifyInner<T> =
113
- // Keep local RpcTarget acceptance, but avoid `Stub | Value` unions when the stub
114
- // is already assignable to the value type (needed for callback contextual typing).
115
- T extends StubBase<infer V> ? (T extends V ? V : (T | V))
116
- : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>>
117
- : T extends Set<infer V> ? Set<Unstubify<V>>
118
- : T extends [] ? []
119
- : T extends [infer Head, ...infer Tail] ? [Unstubify<Head>, ...Unstubify<Tail>]
120
- : T extends readonly [] ? readonly []
121
- : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head>, ...Unstubify<Tail>]
122
- : T extends Array<infer V> ? Array<Unstubify<V>>
123
- : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>>
124
- : T extends BaseType ? T
125
- : T extends { [key: string | number]: unknown } ? { [K in keyof T]: Unstubify<T[K]> }
126
- : T;
127
-
128
- // You can put promises anywhere in the params and they'll be resolved before delivery.
129
- // (This also covers RpcPromise, because it's defined as being a Promise.)
130
- type Unstubify<T> = UnstubifyInner<T> | Promise<UnstubifyInner<T>>
131
-
132
- type UnstubifyAll<A extends any[]> = { [I in keyof A]: Unstubify<A[I]> };
133
-
134
- // Utility type for adding `Disposable`s to `object` types only.
135
- // Note `unknown & T` is equivalent to `T`.
136
- type MaybeDisposable<T> = T extends object ? Disposable : unknown;
137
-
138
- // Type for method return or property on an RPC interface.
139
- // - Stubable types are replaced by stubs.
140
- // - RpcCompatible types are passed by value, with stubable types replaced by stubs
141
- // and a top-level `Disposer`.
142
- // Everything else can't be passed over RPC.
143
- // Technically, we use custom thenables here, but they quack like `Promise`s.
144
- // Intersecting with `(Maybe)Provider` allows pipelining.
145
- // prettier-ignore
146
- type Result<R> =
147
- R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<R>
148
- : R extends RpcCompatible<R> ? Promise<Stubify<R> & MaybeDisposable<R>> & Provider<R> & StubBase<R>
149
- : never;
150
-
151
- // Type for method or property on an RPC interface.
152
- // For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
153
- // Unwrapping `Stub`s allows calling with `Stubable` arguments.
154
- // For properties, rewrite types to be `Result`s.
155
- // In each case, unwrap `Promise`s.
156
- type MethodOrProperty<V> = V extends (...args: infer P) => infer R
157
- ? (...args: UnstubifyAll<P>) => Result<Awaited<R>>
158
- : Result<Awaited<V>>;
159
-
160
- // Type for the callable part of an `Provider` if `T` is callable.
161
- // This is intersected with methods/properties.
162
- type MaybeCallableProvider<T> = T extends (...args: any[]) => any
163
- ? MethodOrProperty<T>
164
- : unknown;
165
-
166
- // Base type for all other types providing RPC-like interfaces.
167
- // Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
168
- type Provider<T> = MaybeCallableProvider<T> &
169
- (T extends Array<infer U>
170
- ? {
171
- [key: number]: MethodOrProperty<U>;
172
- } & {
173
- map<V>(callback: (elem: U) => V): Result<Array<V>>;
174
- }
175
- : {
176
- [K in Exclude<
177
- keyof T,
178
- symbol | keyof StubBase<never>
179
- >]: MethodOrProperty<T[K]>;
180
- } & {
181
- map<V>(callback: (value: 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
+ // 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 HasAnyFunctionParts<P extends readonly unknown[], R> =
170
+ IsAny<R> extends true ? true : IsAny<P[number]>;
171
+
172
+ // Type for method or property on an RPC interface.
173
+ // For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
174
+ // Unwrapping `Stub`s allows calling with `Stubable` arguments.
175
+ // For properties, rewrite types to be `Result`s.
176
+ // In each case, unwrap `Promise`s.
177
+ type MethodOrProperty<V> = V extends (...args: infer P) => infer R
178
+ ? HasAnyFunctionParts<P, R> extends true
179
+ ? (...args: unknown[]) => UnknownResult
180
+ : (...args: UnstubifyAll<P>) => Result<Awaited<R>>
181
+ : Result<Awaited<V>>;
182
+
183
+ // Type for the callable part of a `Provider` if `T` is callable.
184
+ // This is intersected with methods/properties.
185
+ type MaybeCallableProvider<T> = T extends (...args: any[]) => any
186
+ ? MethodOrProperty<T>
187
+ : unknown;
188
+
189
+ // Base type for all other types providing RPC-like interfaces.
190
+ // Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
191
+ type Provider<T> = MaybeCallableProvider<T> &
192
+ (T extends Array<infer U>
193
+ ? {
194
+ [key: number]: MethodOrProperty<U>;
195
+ } & {
196
+ map<V>(callback: (elem: Result<U>) => V): Result<Array<V>>;
197
+ }
198
+ : {
199
+ [K in Exclude<
200
+ keyof T,
201
+ symbol | keyof StubBase<never>
202
+ >]: MethodOrProperty<T[K]>;
203
+ } & {
204
+ map<V>(callback: (value: Result<NonNullable<T>>) => V): Result<Array<V>>;
182
205
  });
183
206
 
184
207
  /**
package/dist/index.js CHANGED
File without changes
package/dist/index.js.map CHANGED
File without changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vastblast/capnweb",
3
- "version": "0.4.1",
3
+ "version": "0.4.3",
4
4
  "description": "JavaScript/TypeScript-native RPC library with Promise Pipelining",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -30,6 +30,7 @@
30
30
  "build": "tsup --format esm,cjs",
31
31
  "build:watch": "tsup --watch --format esm,cjs",
32
32
  "test": "vitest run",
33
+ "test:types": "tsc -p type-tests/tsconfig.json --noEmit",
33
34
  "test:watch": "vitest",
34
35
  "prepublishOnly": "npm run build"
35
36
  },