capnweb 0.0.0-e0d2f1d → 0.0.0-e3a41a3

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.
package/dist/index.d.cts CHANGED
@@ -1,138 +1,106 @@
1
- import { IncomingMessage, ServerResponse, OutgoingHttpHeaders, OutgoingHttpHeader } from 'node:http';
1
+ import { IncomingMessage, OutgoingHttpHeader, OutgoingHttpHeaders, ServerResponse } from "node:http";
2
2
 
3
+ //#region src/types.d.ts
3
4
  // Copyright (c) 2025 Cloudflare, Inc.
4
5
  // Licensed under the MIT license found in the LICENSE.txt file or at:
5
6
  // https://opensource.org/license/mit
6
-
7
7
  // This file borrows heavily from `types/defines/rpc.d.ts` in workerd.
8
-
9
8
  // Branded types for identifying `WorkerEntrypoint`/`DurableObject`/`Target`s.
10
9
  // TypeScript uses *structural* typing meaning anything with the same shape as type `T` is a `T`.
11
10
  // For the classes exported by `cloudflare:workers` we want *nominal* typing (i.e. we only want to
12
11
  // accept `WorkerEntrypoint` from `cloudflare:workers`, not any other class with the same shape)
13
12
  declare const __RPC_STUB_BRAND: '__RPC_STUB_BRAND';
14
13
  declare const __RPC_TARGET_BRAND: '__RPC_TARGET_BRAND';
14
+ // Distinguishes mapper placeholders from regular values so param unwrapping can accept them.
15
+ declare const __RPC_MAP_VALUE_BRAND: unique symbol;
15
16
  interface RpcTargetBranded {
16
17
  [__RPC_TARGET_BRAND]: never;
17
18
  }
18
-
19
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
20
+ // `never[]` preserves compatibility with strongly-typed function signatures without introducing
21
+ // `any` into inference.
22
+ type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
23
+ // Note: also true for `any` (call sites that care check `IsAny` first).
24
+ type IsUnknown<T> = unknown extends T ? true : false; // Types that can be passed over RPC
25
+ // The reason for using a generic type here is to build the serializable subset of RPC-compatible
26
+ // composite types. This allows types defined with the "interface" keyword to pass the
25
27
  // 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
-
28
+ type RpcCompatible<T> = // Allow `unknown` as a leaf so records/interfaces with `unknown` fields remain compatible.
29
+ (IsUnknown<T> extends true ? unknown : never) // RPC-compatible base values
30
+ | BaseType // RPC-compatible composites
31
+ | Map<T extends Map<infer U, unknown> ? RpcCompatible<U> : never, T extends Map<unknown, infer U> ? RpcCompatible<U> : never> | Set<T extends Set<infer U> ? RpcCompatible<U> : never> | Array<T extends Array<infer U> ? RpcCompatible<U> : never> | ReadonlyArray<T extends ReadonlyArray<infer U> ? RpcCompatible<U> : never> | { [K in keyof T as K extends string | number ? K : never]: RpcCompatible<T[K]> } | Promise<T extends Promise<infer U> ? RpcCompatible<U> : never> // Special types
32
+ | Stub<Stubable> // Serialized as stubs, see `Stubify`
33
+ | Stubable;
46
34
  // Base type for all RPC stubs, including common memory management methods.
47
35
  // `T` is used as a marker type for unwrapping `Stub`s later.
48
- interface StubBase<T extends RpcCompatible<T>> extends Disposable {
36
+ interface StubBase<T = unknown> extends Disposable {
49
37
  [__RPC_STUB_BRAND]: T;
50
38
  dup(): this;
51
39
  onRpcBroken(callback: (error: any) => void): void;
52
40
  }
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.
41
+ type Stub<T extends RpcCompatible<T>> = T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
42
+ type TypedArray = Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | Int8Array | Int16Array | Int32Array | BigUint64Array | BigInt64Array | Float32Array | Float64Array; // This represents all the types that can be sent as-is over an RPC boundary
43
+ type BaseType = void | undefined | null | boolean | number | bigint | string | TypedArray | ArrayBuffer | DataView | Date | Error | RegExp | Blob | ReadableStream<any> // Chunk type can be any RPC-compatible type
44
+ | WritableStream<any> // Chunk type can be any RPC-compatible type
45
+ | URL | Request | Response | Headers; // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
46
+ // Arm ordering matters here:
47
+ // - `Promise` must come before `StubBase`: `RpcPromise<T>` matches both, and must resolve
48
+ // through the Promise arm rather than pass through as-is.
49
+ // - `StubBase` must come before `Stubable`: `Stub<T>` of a callable `T` is itself callable, so
50
+ // it matches `Stubable`. Checking `StubBase` first keeps existing stubs as-is instead of
51
+ // double-wrapping them as `Stub<Stub<T>>`.
90
52
  // 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
-
53
+ type Stubify<T> = T extends Promise<infer U> ? Stubify<U> : T extends StubBase<any> ? T : T extends Stubable ? Stub<T> : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>> : T extends Set<infer V> ? Set<Stubify<V>> : T extends [] ? [] : T extends [infer Head, ...infer Tail] ? [Stubify<Head>, ...Stubify<Tail>] : T extends readonly [] ? readonly [] : T extends readonly [infer Head, ...infer Tail] ? readonly [Stubify<Head>, ...Stubify<Tail>] : T extends Array<infer V> ? Array<Stubify<V>> : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>> : T extends BaseType ? T // When using "unknown" instead of "any", interfaces are not stubified.
54
+ : T extends {
55
+ [key: string | number]: any;
56
+ } ? { [K in keyof T as K extends string | number ? K : never]: Stubify<T[K]> } : T;
108
57
  // Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
109
58
  // Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
110
59
  // `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
111
60
  // prettier-ignore
112
- type UnstubifyInner<T> =
113
- T extends StubBase<infer V> ? (T | V) // can provide either stub or local RpcTarget
114
- : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>>
115
- : T extends Set<infer V> ? Set<Unstubify<V>>
116
- : T extends [] ? []
117
- : T extends [infer Head, ...infer Tail] ? [Unstubify<Head>, ...Unstubify<Tail>]
118
- : T extends readonly [] ? readonly []
119
- : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head>, ...Unstubify<Tail>]
120
- : T extends Array<infer V> ? Array<Unstubify<V>>
121
- : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>>
122
- : T extends BaseType ? T
123
- : T extends { [key: string | number]: unknown } ? { [K in keyof T]: Unstubify<T[K]> }
124
- : T;
125
-
126
- // You can put promises anywhere in the params and they'll be resolved before delivery.
61
+ type UnstubifyInner<T> = // Preserve local RpcTarget acceptance, but avoid needless `Stub | Value` unions when the stub
62
+ // is already assignable to the value type (important for callback contextual typing).
63
+ T extends StubBase<infer V> ? (T extends V ? UnstubifyInner<V> : (T | UnstubifyInner<V>)) : T extends Promise<infer U> ? UnstubifyInner<U> : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>> : T extends Set<infer V> ? Set<Unstubify<V>> : T extends [] ? [] : T extends [infer Head, ...infer Tail] ? [Unstubify<Head>, ...Unstubify<Tail>] : T extends readonly [] ? readonly [] : T extends readonly [infer Head, ...infer Tail] ? readonly [Unstubify<Head>, ...Unstubify<Tail>] : T extends Array<infer V> ? Array<Unstubify<V>> : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>> : T extends BaseType ? T : T extends {
64
+ [key: string | number]: unknown;
65
+ } ? { [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.
127
66
  // (This also covers RpcPromise, because it's defined as being a Promise.)
128
- type Unstubify<T> = UnstubifyInner<T> | Promise<UnstubifyInner<T>>
129
-
130
- type UnstubifyAll<A extends any[]> = { [I in keyof A]: Unstubify<A[I]> };
131
-
132
- // Utility type for adding `Disposable`s to `object` types only.
67
+ // Map placeholders are also allowed so primitive map callback inputs can be forwarded directly
68
+ // into RPC params.
69
+ //
70
+ // Keep raw non-stub members so generic assignability still works when UnstubifyInner<T> is deferred.
71
+ // Remove stub members from mixed unions so callback params don’t get both stub and unstubbed signatures.
72
+ // Marker carried by map() callback inputs. This lets primitive placeholders flow through params.
73
+ type Unstubify<T> = NonStubMembers<T> | UnstubifyInner<T> | Promise<UnstubifyInner<T>> | MapValuePlaceholder<UnstubifyInner<T>>;
74
+ type UnstubifyAll<A extends readonly unknown[]> = { [I in keyof A]: Unstubify<A[I]> };
75
+ interface MapValuePlaceholder<T> {
76
+ [__RPC_MAP_VALUE_BRAND]: T;
77
+ }
78
+ type NonStubMembers<T> = Exclude<T, StubBase<any>>; // Utility type for adding `Disposable`s to `object` types only.
133
79
  // Note `unknown & T` is equivalent to `T`.
134
- type MaybeDisposable<T> = T extends object ? Disposable : unknown;
135
-
80
+ type MaybeDisposable<T> = T extends object ? Disposable : unknown; // The type behind the public `RpcPromise` (re-exported with its `RpcCompatible` constraint from
81
+ // index.ts). Defined here so that `Result`'s arms below resolve to the exact same alias
82
+ // instantiation: when both sides of an assignability check are the same alias applied to the
83
+ // same type arguments, the checker short-circuits on identity instead of recursing through the
84
+ // full structural comparison of these mutually-recursive types.
85
+ type RpcPromise$1<T> = T extends Stubable ? Promise<Stub<T>> & Provider<T> & StubBase<T> : Promise<Stubify<T> & MaybeDisposable<T>> & Provider<T> & StubBase<T>;
86
+ // The elision `Result` applies to a bare stub type: unwrap `Stub<T>` back to `T` when the
87
+ // payload is `Stubable`. Such stubs await back to a stub either way, so eliding keeps a
88
+ // declared `Promise<RpcStub<T>>` return interchangeable with a `Promise<T>` return.
89
+ // Plain-interface stubs are NOT elided: `RpcPromise<U>` only awaits to `Stub<U>` when
90
+ // `U extends Stubable`, so eliding those would change the awaited type from a stub to a
91
+ // stubified record. The payload check is deliberately non-distributive (`[U] extends [...]`).
92
+ // `Stub<any>` is not elided either: `[any] extends [Stubable]` is true, so without the `IsAny`
93
+ // guard an `any`-payload stub would lose its stub surface.
94
+ // Also used by the `RpcPromise` constructor signature (index.ts), which applies exactly this
95
+ // transformation so constructing from a promised stub matches the method-return type.
96
+ type ElideStub<T> = T extends StubBase<infer U> ? (IsAny<U> extends true ? T : [U] extends [Stubable] ? U : T) : T;
97
+ // What the promise given to `new RpcPromise<T>(...)` may resolve to: the payload itself, or —
98
+ // for stubable payloads — a stub of it. `NoInfer` keeps the stub arm out of inference, so an
99
+ // inferred `T` is always the promise's own resolution type; the arm only matters when `T` is
100
+ // explicitly annotated (`new RpcPromise<Counter>(promiseOfStub)`). Stubs of non-stubable
101
+ // payloads are deliberately rejected: `ElideStub` wouldn't elide those, so accepting one would
102
+ // claim the promise awaits to a stubified record while the runtime resolves to a stub.
103
+ type PayloadOrStub<T> = T | NoInfer<Stub<Extract<T, Stubable>>>;
136
104
  // Type for method return or property on an RPC interface.
137
105
  // - Stubable types are replaced by stubs.
138
106
  // - RpcCompatible types are passed by value, with stubable types replaced by stubs
@@ -141,44 +109,71 @@ type MaybeDisposable<T> = T extends object ? Disposable : unknown;
141
109
  // Technically, we use custom thenables here, but they quack like `Promise`s.
142
110
  // Intersecting with `(Maybe)Provider` allows pipelining.
143
111
  // prettier-ignore
144
- type Result<R> =
145
- R extends Stubable ? Promise<Stub<R>> & Provider<R> & StubBase<R>
146
- : R extends RpcCompatible<R> ? Promise<Stubify<R> & MaybeDisposable<R>> & Provider<R> & StubBase<R>
147
- : never;
148
-
149
- // Type for method or property on an RPC interface.
112
+ type Result<R> = IsAny<R> extends true ? RpcPromise$1<unknown> // `RpcPromise<U>`: always safe to normalize — `Result` is idempotent — so a declared
113
+ // `RpcPromise<U>` return produces the same type as a `Promise<U>` return.
114
+ : R extends PromiseLike<unknown> & StubBase<infer U> ? Result<U> // Bare stubs: elide per `ElideStub` above. Note there is no `RpcCompatible<R>` re-check
115
+ // here: anything matching our `StubBase` was produced by machinery that already enforced
116
+ // the constraint, and re-evaluating `RpcCompatible<R>` in this arm recurses through its
117
+ // `Stub<Stubable>` member back into `Result`, tripping TS2615 circularity errors in mapped
118
+ // types.
119
+ : R extends StubBase<any> ? RpcPromise$1<ElideStub<R>> : R extends RpcCompatible<R> ? RpcPromise$1<R> : never;
120
+ type IsAny<T> = 0 extends (1 & T) ? true : false; // Type for method or property on an RPC interface.
150
121
  // For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
151
122
  // Unwrapping `Stub`s allows calling with `Stubable` arguments.
152
123
  // For properties, rewrite types to be `Result`s.
153
124
  // In each case, unwrap `Promise`s.
154
- type MethodOrProperty<V> = V extends (...args: infer P) => infer R
155
- ? (...args: UnstubifyAll<P>) => Result<Awaited<R>>
156
- : Result<Awaited<V>>;
157
-
158
- // Type for the callable part of an `Provider` if `T` is callable.
125
+ type MethodOrProperty<V> = V extends ((...args: infer P) => infer R) ? (...args: UnstubifyAll<P>) => Result<Awaited<R>> : Result<Awaited<V>>; // Type for the callable part of an `Provider` if `T` is callable.
159
126
  // This is intersected with methods/properties.
160
- type MaybeCallableProvider<T> = T extends (...args: any[]) => any
161
- ? MethodOrProperty<T>
162
- : unknown;
163
-
164
- // Base type for all other types providing RPC-like interfaces.
127
+ type MaybeCallableProvider<T> = T extends ((...args: any[]) => any) ? MethodOrProperty<T> : unknown;
128
+ type TupleIndexKeys<T extends ReadonlyArray<unknown>> = Extract<keyof T, `${number}`>;
129
+ type MapCallbackValue<T> = // `Omit` removes call signatures, so re-intersect callable provider behavior.
130
+ T extends unknown ? Omit<Result<T>, keyof Promise<unknown>> & MaybeCallableProvider<T> & MapValuePlaceholder<T> : never;
131
+ type InvalidNativePromiseInMapResult<T, Seen = never> = T extends unknown ? InvalidNativePromiseInMapResultImpl<T, Seen> : never;
132
+ type InvalidNativePromiseInMapResultImpl<T, Seen> = [T] extends [Seen] ? never // RpcPromise is modeled as Promise & StubBase, so allow promise-like stub values.
133
+ : T extends StubBase<any> ? never // Native thenables cannot be represented in map recordings, even when typed as PromiseLike.
134
+ : 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 {
135
+ [key: string | number]: unknown;
136
+ } ? InvalidNativePromiseInMapResult<T[Extract<keyof T, string | number>], Seen | T> : never;
137
+ type MapCallbackReturn<T> = InvalidNativePromiseInMapResult<T> extends never ? T : never;
138
+ type ArrayProvider<E> = { [K in number]: MethodOrProperty<E> } & {
139
+ map<V>(callback: (elem: MapCallbackValue<E>) => MapCallbackReturn<V>): Result<Array<V>>;
140
+ };
141
+ 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.
165
142
  // Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
166
- type Provider<T> = MaybeCallableProvider<T> &
167
- (T extends Array<infer U>
168
- ? {
169
- [key: number]: MethodOrProperty<U>;
170
- } & {
171
- map<V>(callback: (elem: U) => V): Result<Array<V>>;
172
- }
173
- : {
174
- [K in Exclude<
175
- keyof T,
176
- symbol | keyof StubBase<never>
177
- >]: MethodOrProperty<T[K]>;
178
- } & {
179
- map<V>(callback: (value: NonNullable<T>) => V): Result<Array<V>>;
180
- });
181
-
143
+ // `__RPC_TARGET_BRAND` deliberately flows through the key mapping (as a `never` property) so
144
+ // stubs of branded targets stay assignable to workers-types' `Stubable`. Such stubs match our
145
+ // `Stubable` too — harmless, since all machinery checks `StubBase` before `Stubable`.
146
+ type Provider<T> = MaybeCallableProvider<T> & (T extends ReadonlyArray<unknown> ? number extends T["length"] ? ArrayProvider<T[number]> : TupleProvider<T> : { [K in Exclude<keyof T, symbol | keyof StubBase<never>>]: MethodOrProperty<T[K]> } & {
147
+ map<V>(callback: (value: MapCallbackValue<NonNullable<T>>) => MapCallbackReturn<V>): Result<Array<V>>;
148
+ });
149
+ //#endregion
150
+ //#region src/serialize.d.ts
151
+ /**
152
+ * Encoding levels determine what representation the RPC system hands to the transport.
153
+ * Each level names what the transport can assume about message values.
154
+ *
155
+ * - `"string"`: JSON string. Default, used by HTTP batch and WebSocket transports.
156
+ * - `"jsonCompatible"`: JSON-compatible JS value tree. For custom encoders.
157
+ * - `"jsonCompatibleWithBytes"`: Like `"jsonCompatible"` but Uint8Array stays raw.
158
+ * - `"structuredClonable"`: Structured-clonable native values pass through where possible.
159
+ *
160
+ * @example
161
+ * ```ts
162
+ * // What happens to Uint8Array([1, 2, 3]) at each level:
163
+ * "string" → '["bytes","AQID"]' // JSON string with base64
164
+ * "jsonCompatible" → ["bytes", "AQID"] // JS array with base64
165
+ * "jsonCompatibleWithBytes" → ["bytes", Uint8Array] // JS array with raw bytes
166
+ * "structuredClonable" → ["bytes", Uint8Array] // + Date, BigInt stay native
167
+ * ```
168
+ */
169
+ type EncodingLevel = "string" | "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
170
+ interface RpcLimits {
171
+ maxBigIntDigits: number;
172
+ maxDepth: number;
173
+ maxMessageSize: number;
174
+ }
175
+ declare const DEFAULT_MAX_DEPTH = 256;
176
+ declare const DEFAULT_LIMITS: RpcLimits;
182
177
  /**
183
178
  * Serialize a value, using Cap'n Web's underlying serialization. This won't be able to serialize
184
179
  * RPC stubs, but it will support basic data types.
@@ -188,59 +183,129 @@ declare function serialize(value: unknown): string;
188
183
  * Deserialize a value serialized using serialize().
189
184
  */
190
185
  declare function deserialize(value: string): unknown;
191
-
186
+ //#endregion
187
+ //#region src/rpc.d.ts
192
188
  /**
193
- * Interface for an RPC transport, which is a simple bidirectional message stream. Implement this
194
- * interface if the built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
189
+ * Interface for a string-based RPC transport. This is the default transport type — no
190
+ * `encodingLevel` field is needed. Messages are JSON strings. Implement this interface if the
191
+ * built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
195
192
  */
196
193
  interface RpcTransport {
197
- /**
198
- * Sends a message to the other end.
199
- */
200
- send(message: string): Promise<void>;
201
- /**
202
- * Receives a message sent by the other end.
203
- *
204
- * If and when the transport becomes disconnected, this will reject. The thrown error will be
205
- * propagated to all outstanding calls and future calls on any stubs associated with the session.
206
- * If there are no outstanding calls (and none are made in the future), then the error does not
207
- * propagate anywhere -- this is considered a "clean" shutdown.
208
- */
209
- receive(): Promise<string>;
210
- /**
211
- * Indicates that the RPC system has suffered an error that prevents the session from continuing.
212
- * The transport should ideally try to send any queued messages if it can, and then close the
213
- * connection. (It's not strictly necessary to deliver queued messages, but the last message sent
214
- * before abort() is called is often an "abort" message, which communicates the error to the
215
- * peer, so if that is dropped, the peer may have less information about what happened.)
216
- */
217
- abort?(reason: any): void;
194
+ /**
195
+ * The encoding level this transport works with. For this interface it is always "string";
196
+ * it may be omitted. (See `RpcTransportWithCustomEncoding` for the other levels.)
197
+ */
198
+ readonly encodingLevel?: "string";
199
+ /**
200
+ * Sends a message to the other end. May optionally return a promise; if the promise rejects,
201
+ * the session is aborted.
202
+ */
203
+ send(message: string): void | Promise<void>;
204
+ /**
205
+ * Receives a message sent by the other end.
206
+ *
207
+ * If and when the transport becomes disconnected, this will reject. The thrown error will be
208
+ * propagated to all outstanding calls and future calls on any stubs associated with the session.
209
+ * If there are no outstanding calls (and none are made in the future), then the error does not
210
+ * propagate anywhere -- this is considered a "clean" shutdown.
211
+ */
212
+ receive(): Promise<string>;
213
+ /**
214
+ * Indicates that the RPC system has suffered an error that prevents the session from continuing.
215
+ * The transport should ideally try to send any queued messages if it can, and then close the
216
+ * connection. (It's not strictly necessary to deliver queued messages, but the last message sent
217
+ * before abort() is called is often an "abort" message, which communicates the error to the
218
+ * peer, so if that is dropped, the peer may have less information about what happened.)
219
+ */
220
+ abort?(reason: any): void;
218
221
  }
222
+ /**
223
+ * Interface for a transport that receives partially encoded JS values instead of JSON strings.
224
+ * The selected `encodingLevel` describes what the transport can assume about message values.
225
+ */
226
+ interface RpcTransportWithCustomEncoding {
227
+ /**
228
+ * The encoding level this transport works with.
229
+ *
230
+ * - "jsonCompatible": JSON-compatible JS value tree; transport handles final serialization.
231
+ * - "jsonCompatibleWithBytes": Like "jsonCompatible" but Uint8Array values are left raw.
232
+ * - "structuredClonable": Structured-clonable native values pass through where possible.
233
+ */
234
+ readonly encodingLevel: "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
235
+ /**
236
+ * Encodes and sends a message to the other end. Returns the encoded byte size if known.
237
+ * If the size is unavailable, return void; Cap'n Web will estimate stream message sizes for
238
+ * flow control. Send errors should be propagated via `receive()` rejecting.
239
+ */
240
+ send(message: unknown): number | void;
241
+ /**
242
+ * Receives and decodes a message sent by the other end.
243
+ *
244
+ * If and when the transport becomes disconnected, this will reject. The thrown error will be
245
+ * propagated to all outstanding calls and future calls on any stubs associated with the session.
246
+ * If there are no outstanding calls (and none are made in the future), then the error does not
247
+ * propagate anywhere -- this is considered a "clean" shutdown.
248
+ */
249
+ receive(): Promise<unknown>;
250
+ /**
251
+ * Indicates that the RPC system has suffered an error that prevents the session from continuing.
252
+ * The transport should ideally try to send any queued messages if it can, and then close the
253
+ * connection. (It's not strictly necessary to deliver queued messages, but the last message sent
254
+ * before abort() is called is often an "abort" message, which communicates the error to the
255
+ * peer, so if that is dropped, the peer may have less information about what happened.)
256
+ */
257
+ abort?(reason: any): void;
258
+ }
259
+ /** Any supported transport type. */
260
+ type AnyRpcTransport = RpcTransport | RpcTransportWithCustomEncoding;
219
261
  /**
220
262
  * Options to customize behavior of an RPC session. All functions which start a session should
221
263
  * optionally accept this.
222
264
  */
223
265
  type RpcSessionOptions = {
224
- /**
225
- * If provided, this function will be called whenever an `Error` object is serialized (for any
226
- * reason, not just because it was thrown). This can be used to log errors, and also to redact
227
- * them.
228
- *
229
- * If `onSendError` returns an Error object, than object will be substituted in place of the
230
- * original. If it has a stack property, the stack will be sent to the client.
231
- *
232
- * If `onSendError` doesn't return anything (or is not provided at all), the default behavior is
233
- * to serialize the error with the stack omitted.
234
- */
235
- onSendError?: (error: Error) => Error | void;
266
+ /**
267
+ * If provided, this function will be called whenever an `Error` object is serialized (for any
268
+ * reason, not just because it was thrown). This can be used to log errors, and also to redact
269
+ * them.
270
+ *
271
+ * If `onSendError` returns an Error object, than object will be substituted in place of the
272
+ * original. If it has a stack property, the stack will be sent to the client.
273
+ *
274
+ * If `onSendError` doesn't return anything (or is not provided at all), the default behavior is
275
+ * to serialize the error with the stack omitted.
276
+ */
277
+ onSendError?: (error: Error) => Error | void;
278
+ /**
279
+ * Overrides for the resource limits enforced while deserializing messages from the peer. Any
280
+ * field left unset falls back to `DEFAULT_LIMITS`. These guard against resource-exhaustion
281
+ * attacks from untrusted peers; see `RpcLimits` for the meaning and defaults of each field.
282
+ *
283
+ * Limits are a purely local, receiver-side decision -- the protocol has no negotiation step, so
284
+ * the peer never learns these values. A message that exceeds a limit is rejected, aborting the
285
+ * session.
286
+ */
287
+ limits?: Partial<RpcLimits>;
236
288
  };
237
-
289
+ //#endregion
290
+ //#region src/websocket.d.ts
238
291
  /**
239
292
  * For use in Cloudflare Workers: Construct an HTTP response that starts a WebSocket RPC session
240
293
  * with the given `localMain`.
241
294
  */
242
295
  declare function newWorkersWebSocketRpcResponse(request: Request, localMain?: any, options?: RpcSessionOptions): Response;
243
-
296
+ /**
297
+ * Generic WebSocket transport. Default `T = string` is backward-compatible and satisfies
298
+ * `RpcTransport`. Use `T = ArrayBuffer` as a building block for binary transports.
299
+ */
300
+ declare class WebSocketTransport<T extends string | ArrayBuffer = string> {
301
+ #private;
302
+ constructor(webSocket: WebSocket);
303
+ send(message: T): void;
304
+ receive(): Promise<T>;
305
+ abort(reason: any): void;
306
+ }
307
+ //#endregion
308
+ //#region src/batch.d.ts
244
309
  /**
245
310
  * Implements the server end of an HTTP batch session, using standard Fetch API types to represent
246
311
  * HTTP requests and responses.
@@ -261,9 +326,10 @@ declare function newHttpBatchRpcResponse(request: Request, localMain: any, optio
261
326
  * @param options Optional RPC session options. You can also pass headers to set on the response.
262
327
  */
263
328
  declare function nodeHttpBatchRpcResponse(request: IncomingMessage, response: ServerResponse, localMain: any, options?: RpcSessionOptions & {
264
- headers?: OutgoingHttpHeaders | OutgoingHttpHeader[];
329
+ headers?: OutgoingHttpHeaders | OutgoingHttpHeader[];
265
330
  }): Promise<void>;
266
-
331
+ //#endregion
332
+ //#region src/index.d.ts
267
333
  /**
268
334
  * Represents a reference to a remote object, on which methods may be remotely invoked via RPC.
269
335
  *
@@ -276,7 +342,7 @@ declare function nodeHttpBatchRpcResponse(request: IncomingMessage, response: Se
276
342
  */
277
343
  type RpcStub<T extends RpcCompatible<T>> = Stub<T>;
278
344
  declare const RpcStub: {
279
- new <T extends RpcCompatible<T>>(value: T): RpcStub<T>;
345
+ new <T extends RpcCompatible<T>>(value: T): RpcStub<T>;
280
346
  };
281
347
  /**
282
348
  * Represents the result of an RPC call.
@@ -295,24 +361,36 @@ declare const RpcStub: {
295
361
  * until you actually `await` the promise (or call `then()`, etc. on it). This is an optimization:
296
362
  * if you only intend to use the promise for pipelining and you never await it, then there's no
297
363
  * need to transmit the resolution!
364
+ *
365
+ * You may also construct an `RpcPromise` yourself from a regular `Promise`, using
366
+ * `new RpcPromise(promise)`, allowing you to perform promise pipelining on a local promise. This
367
+ * is semantically identical to creating a local-loopback RPC that returns the promise, and then
368
+ * invoking it: pipelined calls wait until the promise resolves, then are delivered, in order, to
369
+ * the resolution. This is useful when you plan to obtain some stub in the future, but want to
370
+ * allow code to start queuing calls on it immediately. Note that the `RpcPromise` takes
371
+ * ownership of the resolution: disposing it disposes the resolution, so resolve the promise
372
+ * with a `dup()` if you also intend to keep the stub.
298
373
  */
299
- type RpcPromise<T extends RpcCompatible<T>> = Stub<T> & Promise<Stubify<T>>;
300
- declare const RpcPromise: {};
374
+ type RpcPromise<T extends RpcCompatible<T>> = RpcPromise$1<T>;
375
+ declare const RpcPromise: {
376
+ new <T extends RpcCompatible<T>>(value: Promise<T>): RpcPromise$1<ElideStub<T>>;
377
+ new <T extends RpcCompatible<T>>(value: Promise<PayloadOrStub<T>>): RpcPromise$1<ElideStub<T>>;
378
+ };
301
379
  /**
302
380
  * Use to construct an `RpcSession` on top of a custom `RpcTransport`.
303
381
  *
304
382
  * Most people won't use this. You only need it if you've implemented your own `RpcTransport`.
305
383
  */
306
384
  interface RpcSession<T extends RpcCompatible<T> = undefined> {
307
- getRemoteMain(): RpcStub<T>;
308
- getStats(): {
309
- imports: number;
310
- exports: number;
311
- };
312
- drain(): Promise<void>;
385
+ getRemoteMain(): RpcStub<T>;
386
+ getStats(): {
387
+ imports: number;
388
+ exports: number;
389
+ };
390
+ drain(): Promise<void>;
313
391
  }
314
392
  declare const RpcSession: {
315
- new <T extends RpcCompatible<T> = undefined>(transport: RpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
393
+ new <T extends RpcCompatible<T> = undefined>(transport: AnyRpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
316
394
  };
317
395
  /**
318
396
  * Classes which are intended to be passed by reference and called over RPC must extend
@@ -322,17 +400,15 @@ declare const RpcSession: {
322
400
  * Note that on Cloudflare Workers, this `RpcTarget` is an alias for the one exported from the
323
401
  * "cloudflare:workers" module, so they can be used interchangably.
324
402
  */
325
- interface RpcTarget extends RpcTargetBranded {
326
- }
403
+ interface RpcTarget extends RpcTargetBranded {}
327
404
  declare const RpcTarget: {
328
- new (): RpcTarget;
405
+ new (): RpcTarget;
329
406
  };
330
407
  /**
331
408
  * Empty interface used as default type parameter for sessions where the other side doesn't
332
409
  * necessarily export a main interface.
333
410
  */
334
- interface Empty {
335
- }
411
+ interface Empty {}
336
412
  /**
337
413
  * Start a WebSocket session given either an already-open WebSocket or a URL.
338
414
  *
@@ -367,6 +443,7 @@ declare let newMessagePortRpcSession: <T extends RpcCompatible<T> = Empty>(port:
367
443
  * credentials as parameters and returns the authorized API), then cross-origin requests should
368
444
  * be safe.
369
445
  */
370
- declare function newWorkersRpcResponse(request: Request, localMain: any): Promise<Response>;
371
-
372
- export { type RpcCompatible, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
446
+ declare function newWorkersRpcResponse(request: Request, localMain: any, options?: RpcSessionOptions): Promise<Response>;
447
+ //#endregion
448
+ export { type AnyRpcTransport, DEFAULT_LIMITS, DEFAULT_MAX_DEPTH, type EncodingLevel, type RpcCompatible, type RpcLimits, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, type RpcTransportWithCustomEncoding, WebSocketTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
449
+ //# sourceMappingURL=index.d.cts.map