capnweb 0.0.0-409821 → 0.0.0-47df697

package/dist/index.d.cts

@@ -107,6 +107,25 @@ type Provider<T> = MaybeCallableProvider<T> & (T extends ReadonlyArray<unknown>
 });
 //#endregion
 //#region src/serialize.d.ts
+/**
+ * Encoding levels determine what representation the RPC system hands to the transport.
+ * Each level names what the transport can assume about message values.
+ *
+ * - `"string"`: JSON string. Default, used by HTTP batch and WebSocket transports.
+ * - `"jsonCompatible"`: JSON-compatible JS value tree. For custom encoders.
+ * - `"jsonCompatibleWithBytes"`: Like `"jsonCompatible"` but Uint8Array stays raw.
+ * - `"structuredClonable"`: Structured-clonable native values pass through where possible.
+ *
+ * @example
+ * ```ts
+ * // What happens to Uint8Array([1, 2, 3]) at each level:
+ * "string"          → '["bytes","AQID"]'           // JSON string with base64
+ * "jsonCompatible"          → ["bytes", "AQID"]      // JS array with base64
+ * "jsonCompatibleWithBytes" → ["bytes", Uint8Array]  // JS array with raw bytes
+ * "structuredClonable"      → ["bytes", Uint8Array]  // + Date, BigInt stay native
+ * ```
+ */
+type EncodingLevel = "string" | "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
 /**
  * Serialize a value, using Cap'n Web's underlying serialization. This won't be able to serialize
  * RPC stubs, but it will support basic data types.
@@ -119,14 +138,21 @@ declare function deserialize(value: string): unknown;
 //#endregion
 //#region src/rpc.d.ts
 /**
- * Interface for an RPC transport, which is a simple bidirectional message stream. Implement this
- * interface if the built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
+ * Interface for a string-based RPC transport. This is the default transport type — no
+ * `encodingLevel` field is needed. Messages are JSON strings. Implement this interface if the
+ * built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
  */
 interface RpcTransport {
   /**
-   * Sends a message to the other end.
+   * The encoding level this transport works with. For this interface it is always "string";
+   * it may be omitted. (See `RpcTransportWithCustomEncoding` for the other levels.)
    */
-  send(message: string): Promise<void>;
+  readonly encodingLevel?: "string";
+  /**
+   * Sends a message to the other end. May optionally return a promise; if the promise rejects,
+   * the session is aborted.
+   */
+  send(message: string): void | Promise<void>;
   /**
    * Receives a message sent by the other end.
    *
@@ -145,6 +171,45 @@ interface RpcTransport {
    */
   abort?(reason: any): void;
 }
+/**
+ * Interface for a transport that receives partially encoded JS values instead of JSON strings.
+ * The selected `encodingLevel` describes what the transport can assume about message values.
+ */
+interface RpcTransportWithCustomEncoding {
+  /**
+   * The encoding level this transport works with.
+   *
+   * - "jsonCompatible": JSON-compatible JS value tree; transport handles final serialization.
+   * - "jsonCompatibleWithBytes": Like "jsonCompatible" but Uint8Array values are left raw.
+   * - "structuredClonable": Structured-clonable native values pass through where possible.
+   */
+  readonly encodingLevel: "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
+  /**
+   * Encodes and sends a message to the other end. Returns the encoded byte size if known.
+   * If the size is unavailable, return void; Cap'n Web will estimate stream message sizes for
+   * flow control. Send errors should be propagated via `receive()` rejecting.
+   */
+  send(message: unknown): number | void;
+  /**
+   * Receives and decodes a message sent by the other end.
+   *
+   * If and when the transport becomes disconnected, this will reject. The thrown error will be
+   * propagated to all outstanding calls and future calls on any stubs associated with the session.
+   * If there are no outstanding calls (and none are made in the future), then the error does not
+   * propagate anywhere -- this is considered a "clean" shutdown.
+   */
+  receive(): Promise<unknown>;
+  /**
+   * Indicates that the RPC system has suffered an error that prevents the session from continuing.
+   * The transport should ideally try to send any queued messages if it can, and then close the
+   * connection. (It's not strictly necessary to deliver queued messages, but the last message sent
+   * before abort() is called is often an "abort" message, which communicates the error to the
+   * peer, so if that is dropped, the peer may have less information about what happened.)
+   */
+  abort?(reason: any): void;
+}
+/** Any supported transport type. */
+type AnyRpcTransport = RpcTransport | RpcTransportWithCustomEncoding;
 /**
  * Options to customize behavior of an RPC session. All functions which start a session should
  * optionally accept this.
@@ -170,6 +235,17 @@ type RpcSessionOptions = {
  * with the given `localMain`.
  */
 declare function newWorkersWebSocketRpcResponse(request: Request, localMain?: any, options?: RpcSessionOptions): Response;
+/**
+ * Generic WebSocket transport. Default `T = string` is backward-compatible and satisfies
+ * `RpcTransport`. Use `T = ArrayBuffer` as a building block for binary transports.
+ */
+declare class WebSocketTransport<T extends string | ArrayBuffer = string> {
+  #private;
+  constructor(webSocket: WebSocket);
+  send(message: T): void;
+  receive(): Promise<T>;
+  abort(reason: any): void;
+}
 //#endregion
 //#region src/batch.d.ts
 /**
@@ -244,7 +320,7 @@ interface RpcSession<T extends RpcCompatible<T> = undefined> {
   drain(): Promise<void>;
 }
 declare const RpcSession: {
-  new <T extends RpcCompatible<T> = undefined>(transport: RpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
+  new <T extends RpcCompatible<T> = undefined>(transport: AnyRpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
 };
 /**
  * Classes which are intended to be passed by reference and called over RPC must extend
@@ -299,5 +375,5 @@ declare let newMessagePortRpcSession: <T extends RpcCompatible<T> = Empty>(port:
  */
 declare function newWorkersRpcResponse(request: Request, localMain: any): Promise<Response>;
 //#endregion
-export { type RpcCompatible, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
+export { type AnyRpcTransport, type EncodingLevel, type RpcCompatible, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, type RpcTransportWithCustomEncoding, WebSocketTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -107,6 +107,25 @@ type Provider<T> = MaybeCallableProvider<T> & (T extends ReadonlyArray<unknown>
 });
 //#endregion
 //#region src/serialize.d.ts
+/**
+ * Encoding levels determine what representation the RPC system hands to the transport.
+ * Each level names what the transport can assume about message values.
+ *
+ * - `"string"`: JSON string. Default, used by HTTP batch and WebSocket transports.
+ * - `"jsonCompatible"`: JSON-compatible JS value tree. For custom encoders.
+ * - `"jsonCompatibleWithBytes"`: Like `"jsonCompatible"` but Uint8Array stays raw.
+ * - `"structuredClonable"`: Structured-clonable native values pass through where possible.
+ *
+ * @example
+ * ```ts
+ * // What happens to Uint8Array([1, 2, 3]) at each level:
+ * "string"          → '["bytes","AQID"]'           // JSON string with base64
+ * "jsonCompatible"          → ["bytes", "AQID"]      // JS array with base64
+ * "jsonCompatibleWithBytes" → ["bytes", Uint8Array]  // JS array with raw bytes
+ * "structuredClonable"      → ["bytes", Uint8Array]  // + Date, BigInt stay native
+ * ```
+ */
+type EncodingLevel = "string" | "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
 /**
  * Serialize a value, using Cap'n Web's underlying serialization. This won't be able to serialize
  * RPC stubs, but it will support basic data types.
@@ -119,14 +138,21 @@ declare function deserialize(value: string): unknown;
 //#endregion
 //#region src/rpc.d.ts
 /**
- * Interface for an RPC transport, which is a simple bidirectional message stream. Implement this
- * interface if the built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
+ * Interface for a string-based RPC transport. This is the default transport type — no
+ * `encodingLevel` field is needed. Messages are JSON strings. Implement this interface if the
+ * built-in transports (e.g. for HTTP batch and WebSocket) don't meet your needs.
  */
 interface RpcTransport {
   /**
-   * Sends a message to the other end.
+   * The encoding level this transport works with. For this interface it is always "string";
+   * it may be omitted. (See `RpcTransportWithCustomEncoding` for the other levels.)
    */
-  send(message: string): Promise<void>;
+  readonly encodingLevel?: "string";
+  /**
+   * Sends a message to the other end. May optionally return a promise; if the promise rejects,
+   * the session is aborted.
+   */
+  send(message: string): void | Promise<void>;
   /**
    * Receives a message sent by the other end.
    *
@@ -145,6 +171,45 @@ interface RpcTransport {
    */
   abort?(reason: any): void;
 }
+/**
+ * Interface for a transport that receives partially encoded JS values instead of JSON strings.
+ * The selected `encodingLevel` describes what the transport can assume about message values.
+ */
+interface RpcTransportWithCustomEncoding {
+  /**
+   * The encoding level this transport works with.
+   *
+   * - "jsonCompatible": JSON-compatible JS value tree; transport handles final serialization.
+   * - "jsonCompatibleWithBytes": Like "jsonCompatible" but Uint8Array values are left raw.
+   * - "structuredClonable": Structured-clonable native values pass through where possible.
+   */
+  readonly encodingLevel: "jsonCompatible" | "jsonCompatibleWithBytes" | "structuredClonable";
+  /**
+   * Encodes and sends a message to the other end. Returns the encoded byte size if known.
+   * If the size is unavailable, return void; Cap'n Web will estimate stream message sizes for
+   * flow control. Send errors should be propagated via `receive()` rejecting.
+   */
+  send(message: unknown): number | void;
+  /**
+   * Receives and decodes a message sent by the other end.
+   *
+   * If and when the transport becomes disconnected, this will reject. The thrown error will be
+   * propagated to all outstanding calls and future calls on any stubs associated with the session.
+   * If there are no outstanding calls (and none are made in the future), then the error does not
+   * propagate anywhere -- this is considered a "clean" shutdown.
+   */
+  receive(): Promise<unknown>;
+  /**
+   * Indicates that the RPC system has suffered an error that prevents the session from continuing.
+   * The transport should ideally try to send any queued messages if it can, and then close the
+   * connection. (It's not strictly necessary to deliver queued messages, but the last message sent
+   * before abort() is called is often an "abort" message, which communicates the error to the
+   * peer, so if that is dropped, the peer may have less information about what happened.)
+   */
+  abort?(reason: any): void;
+}
+/** Any supported transport type. */
+type AnyRpcTransport = RpcTransport | RpcTransportWithCustomEncoding;
 /**
  * Options to customize behavior of an RPC session. All functions which start a session should
  * optionally accept this.
@@ -170,6 +235,17 @@ type RpcSessionOptions = {
  * with the given `localMain`.
  */
 declare function newWorkersWebSocketRpcResponse(request: Request, localMain?: any, options?: RpcSessionOptions): Response;
+/**
+ * Generic WebSocket transport. Default `T = string` is backward-compatible and satisfies
+ * `RpcTransport`. Use `T = ArrayBuffer` as a building block for binary transports.
+ */
+declare class WebSocketTransport<T extends string | ArrayBuffer = string> {
+  #private;
+  constructor(webSocket: WebSocket);
+  send(message: T): void;
+  receive(): Promise<T>;
+  abort(reason: any): void;
+}
 //#endregion
 //#region src/batch.d.ts
 /**
@@ -244,7 +320,7 @@ interface RpcSession<T extends RpcCompatible<T> = undefined> {
   drain(): Promise<void>;
 }
 declare const RpcSession: {
-  new <T extends RpcCompatible<T> = undefined>(transport: RpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
+  new <T extends RpcCompatible<T> = undefined>(transport: AnyRpcTransport, localMain?: any, options?: RpcSessionOptions): RpcSession<T>;
 };
 /**
  * Classes which are intended to be passed by reference and called over RPC must extend
@@ -299,5 +375,5 @@ declare let newMessagePortRpcSession: <T extends RpcCompatible<T> = Empty>(port:
  */
 declare function newWorkersRpcResponse(request: Request, localMain: any): Promise<Response>;
 //#endregion
-export { type RpcCompatible, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
+export { type AnyRpcTransport, type EncodingLevel, type RpcCompatible, RpcPromise, RpcSession, type RpcSessionOptions, RpcStub, RpcTarget, type RpcTransport, type RpcTransportWithCustomEncoding, WebSocketTransport, deserialize, newHttpBatchRpcResponse, newHttpBatchRpcSession, newMessagePortRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, newWorkersWebSocketRpcResponse, nodeHttpBatchRpcResponse, serialize };
 //# sourceMappingURL=index.d.ts.map