capnweb 0.0.0-1cca1a2 → 0.0.0-20fe0fb

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 CHANGED
@@ -203,6 +203,7 @@ The following types can be passed over RPC (in arguments or return values), and
203
203
  * `Error` and its well-known subclasses
204
204
  * `Blob`
205
205
  * `ReadableStream` and `WritableStream`, with automatic flow control.
206
+ * `URL`
206
207
  * `Headers`, `Request`, and `Response` from the Fetch API.
207
208
 
208
209
  The following types are not supported as of this writing, but may be added in the future:
@@ -378,6 +379,40 @@ Sometimes you need to pass a stub somewhere where it will be disposed, but also
378
379
 
379
380
  Hint: You can call `.dup()` on a property of a stub or promise, in order to create a stub backed by that property. This is particularly useful when you know in advance that the property is going to resolve to a stub: calling `.dup()` on it gives you a stub you can start using immediately, that otherwise behaves exactly the same as the eventual stub would if you awaited it.
380
381
 
382
+ #### Holding on to a callback past the call that delivered it
383
+
384
+ A common bidirectional-calling pattern is for the client to pass a callback to the server, which the server then invokes later (for example from a timer, an event handler, or a subsequent RPC). Because the callback parameter is a stub, and stubs in params are implicitly disposed when the call returns, the server must duplicate the stub with `.dup()` if it wants to invoke the callback after the call completes:
385
+
386
+ ```ts
387
+ import { type RpcStub, RpcTarget } from 'capnweb';
388
+
389
+ // A callback the client passes in: a stub wrapping a function.
390
+ type Listener = RpcStub<(msg: string) => void>;
391
+
392
+ class Api extends RpcTarget {
393
+ #listener?: Listener;
394
+
395
+ // Stubs passed as params are disposed when the call returns, so `.dup()`
396
+ // to keep a reference that outlives registerListener().
397
+ registerListener(listener: Listener) {
398
+ this.#listener?.[Symbol.dispose](); // release any previous listener
399
+ this.#listener = listener.dup();
400
+ }
401
+
402
+ // A *later* call can invoke the retained callback -- still valid thanks to .dup().
403
+ notify(msg: string) {
404
+ this.#listener?.(msg);
405
+ }
406
+
407
+ // Dispose our duplicate when done so the client-side stub can be freed.
408
+ [Symbol.dispose]() {
409
+ this.#listener?.[Symbol.dispose]();
410
+ }
411
+ }
412
+ ```
413
+
414
+ The same rule applies in the other direction: if the server returns a stub to the client and the client wants to keep using it after disposing the result, the client should `.dup()` the stub before the result is disposed.
415
+
381
416
  ### Listening for disposal
382
417
 
383
418
  An `RpcTarget` may declare a `Symbol.dispose` method. If it does, the RPC system will automatically invoke it when a stub pointing at it (and all its duplicates) has been disposed.
@@ -58,6 +58,7 @@ function typeForRpc(value) {
58
58
  case Float64Array.prototype: return "bytes";
59
59
  case WritableStream.prototype: return "writable";
60
60
  case ReadableStream.prototype: return "readable";
61
+ case URL.prototype: return "url";
61
62
  case Headers.prototype: return "headers";
62
63
  case Request.prototype: return "request";
63
64
  case Response.prototype: return "response";
@@ -392,6 +393,7 @@ var RpcPayload = class RpcPayload {
392
393
  case "date":
393
394
  case "bytes":
394
395
  case "blob":
396
+ case "url":
395
397
  case "error":
396
398
  case "undefined": return value;
397
399
  case "array": {
@@ -589,6 +591,7 @@ var RpcPayload = class RpcPayload {
589
591
  case "bytes":
590
592
  case "blob":
591
593
  case "date":
594
+ case "url":
592
595
  case "error":
593
596
  case "undefined": return;
594
597
  case "array": {
@@ -671,6 +674,7 @@ var RpcPayload = class RpcPayload {
671
674
  case "rpc-target":
672
675
  case "writable":
673
676
  case "readable":
677
+ case "url":
674
678
  case "headers":
675
679
  case "request":
676
680
  case "response": return;
@@ -740,6 +744,7 @@ function followPath(value, parent, path, owner) {
740
744
  case "blob":
741
745
  case "date":
742
746
  case "error":
747
+ case "url":
743
748
  case "headers":
744
749
  case "request":
745
750
  case "response":
@@ -1162,6 +1167,7 @@ var Devaluator = class Devaluator {
1162
1167
  alternateTypeName
1163
1168
  ];
1164
1169
  }
1170
+ case "url": return ["url", value.href];
1165
1171
  case "headers": return ["headers", [...value]];
1166
1172
  case "request": {
1167
1173
  let req = value;
@@ -1481,6 +1487,9 @@ var Evaluator = class Evaluator {
1481
1487
  case "inf": return Infinity;
1482
1488
  case "-inf": return -Infinity;
1483
1489
  case "nan": return NaN;
1490
+ case "url":
1491
+ if (value.length === 2 && typeof value[1] === "string") return new URL(value[1]);
1492
+ break;
1484
1493
  case "headers":
1485
1494
  if (value.length === 2 && value[1] instanceof Array) return new Headers(value[1]);
1486
1495
  break;
@@ -2301,7 +2310,7 @@ var RpcSession$1 = class {
2301
2310
 
2302
2311
  //#endregion
2303
2312
  //#region src/websocket.ts
2304
- /** Close-frame reason max UTF-8 bytes: 125 payload − 2-byte status (RFC 6455 §5.5). */
2313
+ /** Close-frame reason max UTF-8 bytes: 125 payload - 2-byte status (RFC 6455 section 5.5). */
2305
2314
  const MAX_CLOSE_REASON_BYTES = 123;
2306
2315
  function newWebSocketRpcSession$1(webSocket, localMain, options) {
2307
2316
  if (typeof webSocket === "string") webSocket = new WebSocket(webSocket);
@@ -2397,6 +2406,7 @@ var WebSocketTransport = class {
2397
2406
 
2398
2407
  //#endregion
2399
2408
  //#region src/batch.ts
2409
+ const yieldToMacrotask = typeof setImmediate === "function" ? () => new Promise((resolve) => setImmediate(resolve)) : () => new Promise((resolve) => setTimeout(resolve, 0));
2400
2410
  var BatchClientTransport = class {
2401
2411
  constructor(sendBatch) {
2402
2412
  this.#promise = this.#scheduleBatch(sendBatch);
@@ -2418,7 +2428,7 @@ var BatchClientTransport = class {
2418
2428
  this.#aborted = reason;
2419
2429
  }
2420
2430
  async #scheduleBatch(sendBatch) {
2421
- await new Promise((resolve) => setTimeout(resolve, 0));
2431
+ await yieldToMacrotask();
2422
2432
  if (this.#aborted !== void 0) throw this.#aborted;
2423
2433
  let batch = this.#batchToSend;
2424
2434
  this.#batchToSend = null;