capnweb 0.0.0-79bc296 → 0.0.0-7a6e5da
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/README.md +60 -2
- package/dist/index-bun.cjs +335 -67
- package/dist/index-bun.cjs.map +1 -1
- package/dist/index-bun.d.cts +87 -14
- package/dist/index-bun.d.ts +87 -14
- package/dist/index-bun.js +334 -68
- package/dist/index-bun.js.map +1 -1
- package/dist/index-workers.cjs +335 -67
- package/dist/index-workers.cjs.map +1 -1
- package/dist/index-workers.d.cts +83 -13
- package/dist/index-workers.d.ts +83 -13
- package/dist/index-workers.js +334 -68
- package/dist/index-workers.js.map +1 -1
- package/dist/index.cjs +335 -67
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +83 -13
- package/dist/index.d.ts +83 -13
- package/dist/index.js +334 -68
- package/dist/index.js.map +1 -1
- package/package.json +5 -5
package/dist/index-bun.d.cts
CHANGED
|
@@ -21,7 +21,8 @@ interface RpcTargetBranded {
|
|
|
21
21
|
// `never[]` preserves compatibility with strongly-typed function signatures without introducing
|
|
22
22
|
// `any` into inference.
|
|
23
23
|
type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
|
|
24
|
-
|
|
24
|
+
// Note: also true for `any` (call sites that care check `IsAny` first).
|
|
25
|
+
type IsUnknown<T> = unknown extends T ? true : false; // Types that can be passed over RPC
|
|
25
26
|
// The reason for using a generic type here is to build the serializable subset of RPC-compatible
|
|
26
27
|
// composite types. This allows types defined with the "interface" keyword to pass the
|
|
27
28
|
// serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
|
|
@@ -40,10 +41,17 @@ interface StubBase<T = unknown> extends Disposable {
|
|
|
40
41
|
}
|
|
41
42
|
type Stub<T extends RpcCompatible<T>> = T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
|
|
42
43
|
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<
|
|
44
|
-
|
|
|
44
|
+
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
|
|
45
|
+
| WritableStream<any> // Chunk type can be any RPC-compatible type
|
|
46
|
+
| URL | Request | Response | Headers; // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
|
|
47
|
+
// Arm ordering matters here:
|
|
48
|
+
// - `Promise` must come before `StubBase`: `RpcPromise<T>` matches both, and must resolve
|
|
49
|
+
// through the Promise arm rather than pass through as-is.
|
|
50
|
+
// - `StubBase` must come before `Stubable`: `Stub<T>` of a callable `T` is itself callable, so
|
|
51
|
+
// it matches `Stubable`. Checking `StubBase` first keeps existing stubs as-is instead of
|
|
52
|
+
// double-wrapping them as `Stub<Stub<T>>`.
|
|
45
53
|
// prettier-ignore
|
|
46
|
-
type Stubify<T> = T extends
|
|
54
|
+
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.
|
|
47
55
|
: T extends {
|
|
48
56
|
[key: string | number]: any;
|
|
49
57
|
} ? { [K in keyof T as K extends string | number ? K : never]: Stubify<T[K]> } : T;
|
|
@@ -70,7 +78,31 @@ interface MapValuePlaceholder<T> {
|
|
|
70
78
|
}
|
|
71
79
|
type NonStubMembers<T> = Exclude<T, StubBase<any>>; // Utility type for adding `Disposable`s to `object` types only.
|
|
72
80
|
// Note `unknown & T` is equivalent to `T`.
|
|
73
|
-
type MaybeDisposable<T> = T extends object ? Disposable : unknown; //
|
|
81
|
+
type MaybeDisposable<T> = T extends object ? Disposable : unknown; // The type behind the public `RpcPromise` (re-exported with its `RpcCompatible` constraint from
|
|
82
|
+
// index.ts). Defined here so that `Result`'s arms below resolve to the exact same alias
|
|
83
|
+
// instantiation: when both sides of an assignability check are the same alias applied to the
|
|
84
|
+
// same type arguments, the checker short-circuits on identity instead of recursing through the
|
|
85
|
+
// full structural comparison of these mutually-recursive types.
|
|
86
|
+
type RpcPromise$2<T> = T extends Stubable ? Promise<Stub<T>> & Provider<T> & StubBase<T> : Promise<Stubify<T> & MaybeDisposable<T>> & Provider<T> & StubBase<T>;
|
|
87
|
+
// The elision `Result` applies to a bare stub type: unwrap `Stub<T>` back to `T` when the
|
|
88
|
+
// payload is `Stubable`. Such stubs await back to a stub either way, so eliding keeps a
|
|
89
|
+
// declared `Promise<RpcStub<T>>` return interchangeable with a `Promise<T>` return.
|
|
90
|
+
// Plain-interface stubs are NOT elided: `RpcPromise<U>` only awaits to `Stub<U>` when
|
|
91
|
+
// `U extends Stubable`, so eliding those would change the awaited type from a stub to a
|
|
92
|
+
// stubified record. The payload check is deliberately non-distributive (`[U] extends [...]`).
|
|
93
|
+
// `Stub<any>` is not elided either: `[any] extends [Stubable]` is true, so without the `IsAny`
|
|
94
|
+
// guard an `any`-payload stub would lose its stub surface.
|
|
95
|
+
// Also used by the `RpcPromise` constructor signature (index.ts), which applies exactly this
|
|
96
|
+
// transformation so constructing from a promised stub matches the method-return type.
|
|
97
|
+
type ElideStub<T> = T extends StubBase<infer U> ? (IsAny<U> extends true ? T : [U] extends [Stubable] ? U : T) : T;
|
|
98
|
+
// What the promise given to `new RpcPromise<T>(...)` may resolve to: the payload itself, or —
|
|
99
|
+
// for stubable payloads — a stub of it. `NoInfer` keeps the stub arm out of inference, so an
|
|
100
|
+
// inferred `T` is always the promise's own resolution type; the arm only matters when `T` is
|
|
101
|
+
// explicitly annotated (`new RpcPromise<Counter>(promiseOfStub)`). Stubs of non-stubable
|
|
102
|
+
// payloads are deliberately rejected: `ElideStub` wouldn't elide those, so accepting one would
|
|
103
|
+
// claim the promise awaits to a stubified record while the runtime resolves to a stub.
|
|
104
|
+
type PayloadOrStub<T> = T | NoInfer<Stub<Extract<T, Stubable>>>;
|
|
105
|
+
// Type for method return or property on an RPC interface.
|
|
74
106
|
// - Stubable types are replaced by stubs.
|
|
75
107
|
// - RpcCompatible types are passed by value, with stubable types replaced by stubs
|
|
76
108
|
// and a top-level `Disposer`.
|
|
@@ -78,14 +110,20 @@ type MaybeDisposable<T> = T extends object ? Disposable : unknown; // Type for m
|
|
|
78
110
|
// Technically, we use custom thenables here, but they quack like `Promise`s.
|
|
79
111
|
// Intersecting with `(Maybe)Provider` allows pipelining.
|
|
80
112
|
// prettier-ignore
|
|
81
|
-
type Result<R> = IsAny<R> extends true ?
|
|
82
|
-
|
|
83
|
-
|
|
113
|
+
type Result<R> = IsAny<R> extends true ? RpcPromise$2<unknown> // `RpcPromise<U>`: always safe to normalize — `Result` is idempotent — so a declared
|
|
114
|
+
// `RpcPromise<U>` return produces the same type as a `Promise<U>` return.
|
|
115
|
+
: R extends PromiseLike<unknown> & StubBase<infer U> ? Result<U> // Bare stubs: elide per `ElideStub` above. Note there is no `RpcCompatible<R>` re-check
|
|
116
|
+
// here: anything matching our `StubBase` was produced by machinery that already enforced
|
|
117
|
+
// the constraint, and re-evaluating `RpcCompatible<R>` in this arm recurses through its
|
|
118
|
+
// `Stub<Stubable>` member back into `Result`, tripping TS2615 circularity errors in mapped
|
|
119
|
+
// types.
|
|
120
|
+
: R extends StubBase<any> ? RpcPromise$2<ElideStub<R>> : R extends RpcCompatible<R> ? RpcPromise$2<R> : never;
|
|
121
|
+
type IsAny<T> = 0 extends (1 & T) ? true : false; // Type for method or property on an RPC interface.
|
|
84
122
|
// For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
|
|
85
123
|
// Unwrapping `Stub`s allows calling with `Stubable` arguments.
|
|
86
124
|
// For properties, rewrite types to be `Result`s.
|
|
87
125
|
// In each case, unwrap `Promise`s.
|
|
88
|
-
type MethodOrProperty<V> = V extends ((...args: infer P) => infer R) ? (...args: UnstubifyAll<P>) =>
|
|
126
|
+
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.
|
|
89
127
|
// This is intersected with methods/properties.
|
|
90
128
|
type MaybeCallableProvider<T> = T extends ((...args: any[]) => any) ? MethodOrProperty<T> : unknown;
|
|
91
129
|
type TupleIndexKeys<T extends ReadonlyArray<unknown>> = Extract<keyof T, `${number}`>;
|
|
@@ -103,6 +141,9 @@ type ArrayProvider<E> = { [K in number]: MethodOrProperty<E> } & {
|
|
|
103
141
|
};
|
|
104
142
|
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.
|
|
105
143
|
// Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
|
|
144
|
+
// `__RPC_TARGET_BRAND` deliberately flows through the key mapping (as a `never` property) so
|
|
145
|
+
// stubs of branded targets stay assignable to workers-types' `Stubable`. Such stubs match our
|
|
146
|
+
// `Stubable` too — harmless, since all machinery checks `StubBase` before `Stubable`.
|
|
106
147
|
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]> } & {
|
|
107
148
|
map<V>(callback: (value: MapCallbackValue<NonNullable<T>>) => MapCallbackReturn<V>): Result<Array<V>>;
|
|
108
149
|
});
|
|
@@ -140,7 +181,7 @@ declare class RpcStub$1 extends RpcTarget$1 {
|
|
|
140
181
|
toString(): string;
|
|
141
182
|
}
|
|
142
183
|
declare class RpcPromise$1 extends RpcStub$1 {
|
|
143
|
-
constructor(hook: StubHook
|
|
184
|
+
constructor(hook: StubHook | PromiseLike<unknown>, pathIfPromise?: PropertyPath);
|
|
144
185
|
then(onfulfilled?: ((value: unknown) => unknown) | undefined | null, onrejected?: ((reason: any) => unknown) | undefined | null): Promise<unknown>;
|
|
145
186
|
catch(onrejected?: ((reason: any) => unknown) | undefined | null): Promise<unknown>;
|
|
146
187
|
finally(onfinally?: (() => void) | undefined | null): Promise<unknown>;
|
|
@@ -171,6 +212,9 @@ declare class RpcPayload {
|
|
|
171
212
|
private deliverTo;
|
|
172
213
|
private static deliverRpcPromiseTo;
|
|
173
214
|
deliverCall(func: Function, thisArg: object | undefined): Promise<RpcPayload>;
|
|
215
|
+
deliverStreamWrite(writer: {
|
|
216
|
+
write(chunk: unknown): Promise<void>;
|
|
217
|
+
}): Promise<RpcPayload>;
|
|
174
218
|
deliverResolve(): Promise<unknown>;
|
|
175
219
|
dispose(): void;
|
|
176
220
|
private disposeImpl;
|
|
@@ -198,6 +242,13 @@ declare class RpcPayload {
|
|
|
198
242
|
* ```
|
|
199
243
|
*/
|
|
200
244
|
type EncodingLevel = "string" | "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
|
|
245
|
+
interface RpcLimits {
|
|
246
|
+
maxBigIntDigits: number;
|
|
247
|
+
maxDepth: number;
|
|
248
|
+
maxMessageSize: number;
|
|
249
|
+
}
|
|
250
|
+
declare const DEFAULT_MAX_DEPTH = 256;
|
|
251
|
+
declare const DEFAULT_LIMITS: RpcLimits;
|
|
201
252
|
/**
|
|
202
253
|
* Serialize a value, using Cap'n Web's underlying serialization. This won't be able to serialize
|
|
203
254
|
* RPC stubs, but it will support basic data types.
|
|
@@ -299,6 +350,16 @@ type RpcSessionOptions = {
|
|
|
299
350
|
* to serialize the error with the stack omitted.
|
|
300
351
|
*/
|
|
301
352
|
onSendError?: (error: Error) => Error | void;
|
|
353
|
+
/**
|
|
354
|
+
* Overrides for the resource limits enforced while deserializing messages from the peer. Any
|
|
355
|
+
* field left unset falls back to `DEFAULT_LIMITS`. These guard against resource-exhaustion
|
|
356
|
+
* attacks from untrusted peers; see `RpcLimits` for the meaning and defaults of each field.
|
|
357
|
+
*
|
|
358
|
+
* Limits are a purely local, receiver-side decision -- the protocol has no negotiation step, so
|
|
359
|
+
* the peer never learns these values. A message that exceeds a limit is rejected, aborting the
|
|
360
|
+
* session.
|
|
361
|
+
*/
|
|
362
|
+
limits?: Partial<RpcLimits>;
|
|
302
363
|
};
|
|
303
364
|
//#endregion
|
|
304
365
|
//#region src/websocket.d.ts
|
|
@@ -375,9 +436,21 @@ declare const RpcStub: {
|
|
|
375
436
|
* until you actually `await` the promise (or call `then()`, etc. on it). This is an optimization:
|
|
376
437
|
* if you only intend to use the promise for pipelining and you never await it, then there's no
|
|
377
438
|
* need to transmit the resolution!
|
|
439
|
+
*
|
|
440
|
+
* You may also construct an `RpcPromise` yourself from a regular `Promise`, using
|
|
441
|
+
* `new RpcPromise(promise)`, allowing you to perform promise pipelining on a local promise. This
|
|
442
|
+
* is semantically identical to creating a local-loopback RPC that returns the promise, and then
|
|
443
|
+
* invoking it: pipelined calls wait until the promise resolves, then are delivered, in order, to
|
|
444
|
+
* the resolution. This is useful when you plan to obtain some stub in the future, but want to
|
|
445
|
+
* allow code to start queuing calls on it immediately. Note that the `RpcPromise` takes
|
|
446
|
+
* ownership of the resolution: disposing it disposes the resolution, so resolve the promise
|
|
447
|
+
* with a `dup()` if you also intend to keep the stub.
|
|
378
448
|
*/
|
|
379
|
-
type RpcPromise<T extends RpcCompatible<T>> =
|
|
380
|
-
declare const RpcPromise: {
|
|
449
|
+
type RpcPromise<T extends RpcCompatible<T>> = RpcPromise$2<T>;
|
|
450
|
+
declare const RpcPromise: {
|
|
451
|
+
new <T extends RpcCompatible<T>>(value: Promise<T>): RpcPromise$2<ElideStub<T>>;
|
|
452
|
+
new <T extends RpcCompatible<T>>(value: Promise<PayloadOrStub<T>>): RpcPromise$2<ElideStub<T>>;
|
|
453
|
+
};
|
|
381
454
|
/**
|
|
382
455
|
* Use to construct an `RpcSession` on top of a custom `RpcTransport`.
|
|
383
456
|
*
|
|
@@ -445,7 +518,7 @@ declare let newMessagePortRpcSession: <T extends RpcCompatible<T> = Empty$1>(por
|
|
|
445
518
|
* credentials as parameters and returns the authorized API), then cross-origin requests should
|
|
446
519
|
* be safe.
|
|
447
520
|
*/
|
|
448
|
-
declare function newWorkersRpcResponse(request: Request, localMain: any): Promise<Response>;
|
|
521
|
+
declare function newWorkersRpcResponse(request: Request, localMain: any, options?: RpcSessionOptions): Promise<Response>;
|
|
449
522
|
//#endregion
|
|
450
523
|
//#region src/bun.d.ts
|
|
451
524
|
type WsData = {
|
|
@@ -496,5 +569,5 @@ declare let newBunWebSocketRpcSession: <T extends RpcCompatible<T> = Empty, D =
|
|
|
496
569
|
transport: BunWebSocketTransport<D>;
|
|
497
570
|
};
|
|
498
571
|
//#endregion
|
|
499
|
-
export { type AnyRpcTransport, BunWebSocketTransport, type EncodingLevel, type RpcCompatible, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, type RpcTransportWithCustomEncoding, WebSocketTransport, deserialize, newBunWebSocketRpcHandler, newBunWebSocketRpcSession, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
|
|
572
|
+
export { type AnyRpcTransport, BunWebSocketTransport, DEFAULT_LIMITS, DEFAULT_MAX_DEPTH, type EncodingLevel, type RpcCompatible, type RpcLimits, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, type RpcTransportWithCustomEncoding, WebSocketTransport, deserialize, newBunWebSocketRpcHandler, newBunWebSocketRpcSession, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
|
|
500
573
|
//# sourceMappingURL=index-bun.d.cts.map
|
package/dist/index-bun.d.ts
CHANGED
|
@@ -21,7 +21,8 @@ interface RpcTargetBranded {
|
|
|
21
21
|
// `never[]` preserves compatibility with strongly-typed function signatures without introducing
|
|
22
22
|
// `any` into inference.
|
|
23
23
|
type Stubable = RpcTargetBranded | ((...args: never[]) => unknown);
|
|
24
|
-
|
|
24
|
+
// Note: also true for `any` (call sites that care check `IsAny` first).
|
|
25
|
+
type IsUnknown<T> = unknown extends T ? true : false; // Types that can be passed over RPC
|
|
25
26
|
// The reason for using a generic type here is to build the serializable subset of RPC-compatible
|
|
26
27
|
// composite types. This allows types defined with the "interface" keyword to pass the
|
|
27
28
|
// serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
|
|
@@ -40,10 +41,17 @@ interface StubBase<T = unknown> extends Disposable {
|
|
|
40
41
|
}
|
|
41
42
|
type Stub<T extends RpcCompatible<T>> = T extends object ? Provider<T> & StubBase<T> : StubBase<T>;
|
|
42
43
|
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<
|
|
44
|
-
|
|
|
44
|
+
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
|
|
45
|
+
| WritableStream<any> // Chunk type can be any RPC-compatible type
|
|
46
|
+
| URL | Request | Response | Headers; // Recursively rewrite all `Stubable` types with `Stub`s, and resolve promises.
|
|
47
|
+
// Arm ordering matters here:
|
|
48
|
+
// - `Promise` must come before `StubBase`: `RpcPromise<T>` matches both, and must resolve
|
|
49
|
+
// through the Promise arm rather than pass through as-is.
|
|
50
|
+
// - `StubBase` must come before `Stubable`: `Stub<T>` of a callable `T` is itself callable, so
|
|
51
|
+
// it matches `Stubable`. Checking `StubBase` first keeps existing stubs as-is instead of
|
|
52
|
+
// double-wrapping them as `Stub<Stub<T>>`.
|
|
45
53
|
// prettier-ignore
|
|
46
|
-
type Stubify<T> = T extends
|
|
54
|
+
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.
|
|
47
55
|
: T extends {
|
|
48
56
|
[key: string | number]: any;
|
|
49
57
|
} ? { [K in keyof T as K extends string | number ? K : never]: Stubify<T[K]> } : T;
|
|
@@ -70,7 +78,31 @@ interface MapValuePlaceholder<T> {
|
|
|
70
78
|
}
|
|
71
79
|
type NonStubMembers<T> = Exclude<T, StubBase<any>>; // Utility type for adding `Disposable`s to `object` types only.
|
|
72
80
|
// Note `unknown & T` is equivalent to `T`.
|
|
73
|
-
type MaybeDisposable<T> = T extends object ? Disposable : unknown; //
|
|
81
|
+
type MaybeDisposable<T> = T extends object ? Disposable : unknown; // The type behind the public `RpcPromise` (re-exported with its `RpcCompatible` constraint from
|
|
82
|
+
// index.ts). Defined here so that `Result`'s arms below resolve to the exact same alias
|
|
83
|
+
// instantiation: when both sides of an assignability check are the same alias applied to the
|
|
84
|
+
// same type arguments, the checker short-circuits on identity instead of recursing through the
|
|
85
|
+
// full structural comparison of these mutually-recursive types.
|
|
86
|
+
type RpcPromise$2<T> = T extends Stubable ? Promise<Stub<T>> & Provider<T> & StubBase<T> : Promise<Stubify<T> & MaybeDisposable<T>> & Provider<T> & StubBase<T>;
|
|
87
|
+
// The elision `Result` applies to a bare stub type: unwrap `Stub<T>` back to `T` when the
|
|
88
|
+
// payload is `Stubable`. Such stubs await back to a stub either way, so eliding keeps a
|
|
89
|
+
// declared `Promise<RpcStub<T>>` return interchangeable with a `Promise<T>` return.
|
|
90
|
+
// Plain-interface stubs are NOT elided: `RpcPromise<U>` only awaits to `Stub<U>` when
|
|
91
|
+
// `U extends Stubable`, so eliding those would change the awaited type from a stub to a
|
|
92
|
+
// stubified record. The payload check is deliberately non-distributive (`[U] extends [...]`).
|
|
93
|
+
// `Stub<any>` is not elided either: `[any] extends [Stubable]` is true, so without the `IsAny`
|
|
94
|
+
// guard an `any`-payload stub would lose its stub surface.
|
|
95
|
+
// Also used by the `RpcPromise` constructor signature (index.ts), which applies exactly this
|
|
96
|
+
// transformation so constructing from a promised stub matches the method-return type.
|
|
97
|
+
type ElideStub<T> = T extends StubBase<infer U> ? (IsAny<U> extends true ? T : [U] extends [Stubable] ? U : T) : T;
|
|
98
|
+
// What the promise given to `new RpcPromise<T>(...)` may resolve to: the payload itself, or —
|
|
99
|
+
// for stubable payloads — a stub of it. `NoInfer` keeps the stub arm out of inference, so an
|
|
100
|
+
// inferred `T` is always the promise's own resolution type; the arm only matters when `T` is
|
|
101
|
+
// explicitly annotated (`new RpcPromise<Counter>(promiseOfStub)`). Stubs of non-stubable
|
|
102
|
+
// payloads are deliberately rejected: `ElideStub` wouldn't elide those, so accepting one would
|
|
103
|
+
// claim the promise awaits to a stubified record while the runtime resolves to a stub.
|
|
104
|
+
type PayloadOrStub<T> = T | NoInfer<Stub<Extract<T, Stubable>>>;
|
|
105
|
+
// Type for method return or property on an RPC interface.
|
|
74
106
|
// - Stubable types are replaced by stubs.
|
|
75
107
|
// - RpcCompatible types are passed by value, with stubable types replaced by stubs
|
|
76
108
|
// and a top-level `Disposer`.
|
|
@@ -78,14 +110,20 @@ type MaybeDisposable<T> = T extends object ? Disposable : unknown; // Type for m
|
|
|
78
110
|
// Technically, we use custom thenables here, but they quack like `Promise`s.
|
|
79
111
|
// Intersecting with `(Maybe)Provider` allows pipelining.
|
|
80
112
|
// prettier-ignore
|
|
81
|
-
type Result<R> = IsAny<R> extends true ?
|
|
82
|
-
|
|
83
|
-
|
|
113
|
+
type Result<R> = IsAny<R> extends true ? RpcPromise$2<unknown> // `RpcPromise<U>`: always safe to normalize — `Result` is idempotent — so a declared
|
|
114
|
+
// `RpcPromise<U>` return produces the same type as a `Promise<U>` return.
|
|
115
|
+
: R extends PromiseLike<unknown> & StubBase<infer U> ? Result<U> // Bare stubs: elide per `ElideStub` above. Note there is no `RpcCompatible<R>` re-check
|
|
116
|
+
// here: anything matching our `StubBase` was produced by machinery that already enforced
|
|
117
|
+
// the constraint, and re-evaluating `RpcCompatible<R>` in this arm recurses through its
|
|
118
|
+
// `Stub<Stubable>` member back into `Result`, tripping TS2615 circularity errors in mapped
|
|
119
|
+
// types.
|
|
120
|
+
: R extends StubBase<any> ? RpcPromise$2<ElideStub<R>> : R extends RpcCompatible<R> ? RpcPromise$2<R> : never;
|
|
121
|
+
type IsAny<T> = 0 extends (1 & T) ? true : false; // Type for method or property on an RPC interface.
|
|
84
122
|
// For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
|
|
85
123
|
// Unwrapping `Stub`s allows calling with `Stubable` arguments.
|
|
86
124
|
// For properties, rewrite types to be `Result`s.
|
|
87
125
|
// In each case, unwrap `Promise`s.
|
|
88
|
-
type MethodOrProperty<V> = V extends ((...args: infer P) => infer R) ? (...args: UnstubifyAll<P>) =>
|
|
126
|
+
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.
|
|
89
127
|
// This is intersected with methods/properties.
|
|
90
128
|
type MaybeCallableProvider<T> = T extends ((...args: any[]) => any) ? MethodOrProperty<T> : unknown;
|
|
91
129
|
type TupleIndexKeys<T extends ReadonlyArray<unknown>> = Extract<keyof T, `${number}`>;
|
|
@@ -103,6 +141,9 @@ type ArrayProvider<E> = { [K in number]: MethodOrProperty<E> } & {
|
|
|
103
141
|
};
|
|
104
142
|
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.
|
|
105
143
|
// Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
|
|
144
|
+
// `__RPC_TARGET_BRAND` deliberately flows through the key mapping (as a `never` property) so
|
|
145
|
+
// stubs of branded targets stay assignable to workers-types' `Stubable`. Such stubs match our
|
|
146
|
+
// `Stubable` too — harmless, since all machinery checks `StubBase` before `Stubable`.
|
|
106
147
|
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]> } & {
|
|
107
148
|
map<V>(callback: (value: MapCallbackValue<NonNullable<T>>) => MapCallbackReturn<V>): Result<Array<V>>;
|
|
108
149
|
});
|
|
@@ -140,7 +181,7 @@ declare class RpcStub$1 extends RpcTarget$1 {
|
|
|
140
181
|
toString(): string;
|
|
141
182
|
}
|
|
142
183
|
declare class RpcPromise$1 extends RpcStub$1 {
|
|
143
|
-
constructor(hook: StubHook
|
|
184
|
+
constructor(hook: StubHook | PromiseLike<unknown>, pathIfPromise?: PropertyPath);
|
|
144
185
|
then(onfulfilled?: ((value: unknown) => unknown) | undefined | null, onrejected?: ((reason: any) => unknown) | undefined | null): Promise<unknown>;
|
|
145
186
|
catch(onrejected?: ((reason: any) => unknown) | undefined | null): Promise<unknown>;
|
|
146
187
|
finally(onfinally?: (() => void) | undefined | null): Promise<unknown>;
|
|
@@ -171,6 +212,9 @@ declare class RpcPayload {
|
|
|
171
212
|
private deliverTo;
|
|
172
213
|
private static deliverRpcPromiseTo;
|
|
173
214
|
deliverCall(func: Function, thisArg: object | undefined): Promise<RpcPayload>;
|
|
215
|
+
deliverStreamWrite(writer: {
|
|
216
|
+
write(chunk: unknown): Promise<void>;
|
|
217
|
+
}): Promise<RpcPayload>;
|
|
174
218
|
deliverResolve(): Promise<unknown>;
|
|
175
219
|
dispose(): void;
|
|
176
220
|
private disposeImpl;
|
|
@@ -198,6 +242,13 @@ declare class RpcPayload {
|
|
|
198
242
|
* ```
|
|
199
243
|
*/
|
|
200
244
|
type EncodingLevel = "string" | "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
|
|
245
|
+
interface RpcLimits {
|
|
246
|
+
maxBigIntDigits: number;
|
|
247
|
+
maxDepth: number;
|
|
248
|
+
maxMessageSize: number;
|
|
249
|
+
}
|
|
250
|
+
declare const DEFAULT_MAX_DEPTH = 256;
|
|
251
|
+
declare const DEFAULT_LIMITS: RpcLimits;
|
|
201
252
|
/**
|
|
202
253
|
* Serialize a value, using Cap'n Web's underlying serialization. This won't be able to serialize
|
|
203
254
|
* RPC stubs, but it will support basic data types.
|
|
@@ -299,6 +350,16 @@ type RpcSessionOptions = {
|
|
|
299
350
|
* to serialize the error with the stack omitted.
|
|
300
351
|
*/
|
|
301
352
|
onSendError?: (error: Error) => Error | void;
|
|
353
|
+
/**
|
|
354
|
+
* Overrides for the resource limits enforced while deserializing messages from the peer. Any
|
|
355
|
+
* field left unset falls back to `DEFAULT_LIMITS`. These guard against resource-exhaustion
|
|
356
|
+
* attacks from untrusted peers; see `RpcLimits` for the meaning and defaults of each field.
|
|
357
|
+
*
|
|
358
|
+
* Limits are a purely local, receiver-side decision -- the protocol has no negotiation step, so
|
|
359
|
+
* the peer never learns these values. A message that exceeds a limit is rejected, aborting the
|
|
360
|
+
* session.
|
|
361
|
+
*/
|
|
362
|
+
limits?: Partial<RpcLimits>;
|
|
302
363
|
};
|
|
303
364
|
//#endregion
|
|
304
365
|
//#region src/websocket.d.ts
|
|
@@ -375,9 +436,21 @@ declare const RpcStub: {
|
|
|
375
436
|
* until you actually `await` the promise (or call `then()`, etc. on it). This is an optimization:
|
|
376
437
|
* if you only intend to use the promise for pipelining and you never await it, then there's no
|
|
377
438
|
* need to transmit the resolution!
|
|
439
|
+
*
|
|
440
|
+
* You may also construct an `RpcPromise` yourself from a regular `Promise`, using
|
|
441
|
+
* `new RpcPromise(promise)`, allowing you to perform promise pipelining on a local promise. This
|
|
442
|
+
* is semantically identical to creating a local-loopback RPC that returns the promise, and then
|
|
443
|
+
* invoking it: pipelined calls wait until the promise resolves, then are delivered, in order, to
|
|
444
|
+
* the resolution. This is useful when you plan to obtain some stub in the future, but want to
|
|
445
|
+
* allow code to start queuing calls on it immediately. Note that the `RpcPromise` takes
|
|
446
|
+
* ownership of the resolution: disposing it disposes the resolution, so resolve the promise
|
|
447
|
+
* with a `dup()` if you also intend to keep the stub.
|
|
378
448
|
*/
|
|
379
|
-
type RpcPromise<T extends RpcCompatible<T>> =
|
|
380
|
-
declare const RpcPromise: {
|
|
449
|
+
type RpcPromise<T extends RpcCompatible<T>> = RpcPromise$2<T>;
|
|
450
|
+
declare const RpcPromise: {
|
|
451
|
+
new <T extends RpcCompatible<T>>(value: Promise<T>): RpcPromise$2<ElideStub<T>>;
|
|
452
|
+
new <T extends RpcCompatible<T>>(value: Promise<PayloadOrStub<T>>): RpcPromise$2<ElideStub<T>>;
|
|
453
|
+
};
|
|
381
454
|
/**
|
|
382
455
|
* Use to construct an `RpcSession` on top of a custom `RpcTransport`.
|
|
383
456
|
*
|
|
@@ -445,7 +518,7 @@ declare let newMessagePortRpcSession: <T extends RpcCompatible<T> = Empty$1>(por
|
|
|
445
518
|
* credentials as parameters and returns the authorized API), then cross-origin requests should
|
|
446
519
|
* be safe.
|
|
447
520
|
*/
|
|
448
|
-
declare function newWorkersRpcResponse(request: Request, localMain: any): Promise<Response>;
|
|
521
|
+
declare function newWorkersRpcResponse(request: Request, localMain: any, options?: RpcSessionOptions): Promise<Response>;
|
|
449
522
|
//#endregion
|
|
450
523
|
//#region src/bun.d.ts
|
|
451
524
|
type WsData = {
|
|
@@ -496,5 +569,5 @@ declare let newBunWebSocketRpcSession: <T extends RpcCompatible<T> = Empty, D =
|
|
|
496
569
|
transport: BunWebSocketTransport<D>;
|
|
497
570
|
};
|
|
498
571
|
//#endregion
|
|
499
|
-
export { type AnyRpcTransport, BunWebSocketTransport, type EncodingLevel, type RpcCompatible, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, type RpcTransportWithCustomEncoding, WebSocketTransport, deserialize, newBunWebSocketRpcHandler, newBunWebSocketRpcSession, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
|
|
572
|
+
export { type AnyRpcTransport, BunWebSocketTransport, DEFAULT_LIMITS, DEFAULT_MAX_DEPTH, type EncodingLevel, type RpcCompatible, type RpcLimits, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, type RpcTransportWithCustomEncoding, WebSocketTransport, deserialize, newBunWebSocketRpcHandler, newBunWebSocketRpcSession, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
|
|
500
573
|
//# sourceMappingURL=index-bun.d.ts.map
|