@replit/river 0.3.1 → 0.5.0

package/dist/router/server.js

@@ -1,90 +1,119 @@
-import { Value } from '@sinclair/typebox/value';
 import { pushable } from 'it-pushable';
+import { isStreamClose, isStreamOpen, reply, } from '../transport/message';
 import { log } from '../logging';
+import { Value } from '@sinclair/typebox/value';
+import { Err, UNCAUGHT_ERROR, } from './result';
+/**
+ * Creates a server instance that listens for incoming messages from a transport and routes them to the appropriate service and procedure.
+ * The server tracks the state of each service along with open streams and the extended context object.
+ * @param transport - The transport to listen to.
+ * @param services - An object containing all the services to be registered on the server.
+ * @param extendedContext - An optional object containing additional context to be passed to all services.
+ * @returns A promise that resolves to a server instance with the registered services.
+ */
 export async function createServer(transport, services, extendedContext) {
     const contextMap = new Map();
+    // map of streamId to ProcStream
     const streamMap = new Map();
     function getContext(service) {
         const context = contextMap.get(service);
         if (!context) {
-            const err = `No context found for ${service.name}`;
+            const err = `${transport.clientId} -- no context found for ${service.name}`;
             log?.error(err);
             throw new Error(err);
         }
         return context;
     }
-    for (const [serviceName, service] of Object.entries(services)) {
-        // populate the context map
+    // populate the context map
+    for (const service of Object.values(services)) {
         contextMap.set(service, { ...extendedContext, state: service.state });
-        // create streams for every stream procedure
-        for (const [procedureName, proc] of Object.entries(service.procedures)) {
-            const procedure = proc;
-            if (procedure.type === 'stream') {
-                const incoming = pushable({ objectMode: true });
-                const outgoing = pushable({ objectMode: true });
-                const procStream = {
-                    incoming,
-                    outgoing,
-                    doneCtx: Promise.all([
-                        // processing the actual procedure
-                        procedure.handler(getContext(service), incoming, outgoing),
-                        // sending outgoing messages back to client
-                        (async () => {
-                            for await (const response of outgoing) {
-                                transport.send(response);
-                            }
-                        })(),
-                    ]),
-                };
-                streamMap.set(`${serviceName}:${procedureName}`, procStream);
-            }
-        }
     }
     const handler = async (msg) => {
         if (msg.to !== 'SERVER') {
+            log?.info(`${transport.clientId} -- got msg with destination that isn't the server, ignoring`);
+            return;
+        }
+        if (!(msg.serviceName in services)) {
+            log?.warn(`${transport.clientId} -- couldn't find service ${msg.serviceName}`);
+            return;
+        }
+        const service = services[msg.serviceName];
+        const serviceContext = getContext(service);
+        if (!(msg.procedureName in service.procedures)) {
+            log?.warn(`${transport.clientId} -- couldn't find a matching procedure for ${msg.serviceName}.${msg.procedureName}`);
             return;
         }
-        if (msg.serviceName in services) {
-            const service = services[msg.serviceName];
-            if (msg.procedureName in service.procedures) {
-                const procedure = service.procedures[msg.procedureName];
-                const inputMessage = msg;
-                if (procedure.type === 'rpc' &&
-                    Value.Check(procedure.input, inputMessage.payload)) {
-                    const response = await procedure.handler(getContext(service), inputMessage);
-                    transport.send(response);
-                    return;
-                }
-                else if (procedure.type === 'stream' &&
-                    Value.Check(procedure.input, inputMessage.payload)) {
-                    // async stream, push to associated stream. code above handles sending responses
-                    // back to the client
-                    const streams = streamMap.get(`${msg.serviceName}:${msg.procedureName}`);
-                    if (!streams) {
-                        // this should never happen but log here if we get here
-                        return;
+        const procedure = service.procedures[msg.procedureName];
+        if (!Value.Check(procedure.input, msg.payload)) {
+            log?.error(`${transport.clientId} -- procedure ${msg.serviceName}.${msg.procedureName} received invalid payload: ${msg.payload}`);
+            return;
+        }
+        const inputMessage = msg;
+        if (isStreamOpen(inputMessage.controlFlags)) {
+            const incoming = pushable({ objectMode: true });
+            const outgoing = pushable({ objectMode: true });
+            const openPromises = [
+                // sending outgoing messages back to client
+                (async () => {
+                    for await (const response of outgoing) {
+                        transport.send(response);
                     }
-                    streams.incoming.push(inputMessage);
-                    return;
-                }
-                else {
-                    log?.error(`${transport.clientId} -- procedure ${msg.serviceName}.${msg.procedureName} received invalid payload: ${inputMessage.payload}`);
-                }
+                })(),
+            ];
+            function errorHandler(err) {
+                const errorMsg = err instanceof Error ? err.message : `[coerced to error] ${err}`;
+                log?.error(`${transport.clientId} -- procedure ${msg.serviceName}.${msg.procedureName}:${msg.streamId} threw an error: ${errorMsg}`);
+                outgoing.push(reply(msg, Err({
+                    code: UNCAUGHT_ERROR,
+                    message: errorMsg,
+                })));
             }
+            // pump incoming message stream -> handler -> outgoing message stream
+            if (procedure.type === 'stream') {
+                openPromises.push(procedure
+                    .handler(serviceContext, incoming, outgoing)
+                    .catch(errorHandler));
+            }
+            else if (procedure.type === 'rpc') {
+                openPromises.push((async () => {
+                    for await (const inputMessage of incoming) {
+                        try {
+                            const outputMessage = await procedure.handler(serviceContext, inputMessage);
+                            outgoing.push(outputMessage);
+                        }
+                        catch (err) {
+                            errorHandler(err);
+                        }
+                    }
+                })());
+            }
+            streamMap.set(`${msg.serviceName}.${msg.procedureName}:${msg.streamId}`, {
+                incoming,
+                outgoing,
+                openPromises,
+            });
+        }
+        const procStream = streamMap.get(`${msg.serviceName}.${msg.procedureName}:${msg.streamId}`);
+        if (!procStream) {
+            log?.warn(`${transport.clientId} -- couldn't find a matching procedure stream for ${msg.serviceName}.${msg.procedureName}:${msg.streamId}`);
+            return;
+        }
+        procStream.incoming.push(inputMessage);
+        if (isStreamClose(inputMessage.controlFlags)) {
+            procStream.incoming.end();
+            await Promise.all(procStream.openPromises);
+            procStream.outgoing.end();
         }
-        log?.warn(`${transport.clientId} -- couldn't find a matching procedure for ${msg.serviceName}.${msg.procedureName}`);
     };
     transport.addMessageListener(handler);
     return {
         services,
         async close() {
-            // remove listener
             transport.removeMessageListener(handler);
-            // end all existing streams
             for (const [_, stream] of streamMap) {
                 stream.incoming.end();
+                await Promise.all(stream.openPromises);
                 stream.outgoing.end();
-                await stream.doneCtx;
             }
         },
     };

package/dist/testUtils.d.ts

@@ -5,10 +5,77 @@ import http from 'http';
 import { WebSocketTransport } from './transport/impls/ws';
 import { Static, TObject } from '@sinclair/typebox';
 import { Procedure, ServiceContext } from './router';
+import { OpaqueTransportMessage, TransportMessage } from './transport';
 import { Pushable } from 'it-pushable';
+import { Result, RiverError, RiverUncaughtSchema } from './router/result';
+/**
+ * Creates a WebSocket server instance using the provided HTTP server.
+ * Only used as helper for testing.
+ * @param server - The HTTP server instance to use for the WebSocket server.
+ * @returns A Promise that resolves to the created WebSocket server instance.
+ */
 export declare function createWebSocketServer(server: http.Server): Promise<WebSocket.Server<typeof WebSocket, typeof http.IncomingMessage>>;
+/**
+ * Starts listening on the given server and returns the automatically allocated port number.
+ * This should only be used for testing.
+ * @param server - The http server to listen on.
+ * @returns A promise that resolves with the allocated port number.
+ * @throws An error if a port cannot be allocated.
+ */
 export declare function onServerReady(server: http.Server): Promise<number>;
+/**
+ * Creates a WebSocket client that connects to a local server at the specified port.
+ * This should only be used for testing.
+ * @param port - The port number to connect to.
+ * @returns A Promise that resolves to a WebSocket instance.
+ */
 export declare function createLocalWebSocketClient(port: number): Promise<WebSocket>;
+/**
+ * Creates a pair of WebSocket transports for testing purposes.
+ * @param port - The port number to use for the client transport. This should be acquired after starting a server via {@link createWebSocketServer}.
+ * @param wss - The WebSocketServer instance to use for the server transport.
+ * @returns An array containing the client and server {@link WebSocketTransport} instances.
+ */
 export declare function createWsTransports(port: number, wss: WebSocketServer): [WebSocketTransport, WebSocketTransport];
-export declare function asClientRpc<State extends object | unknown, I extends TObject, O extends TObject>(state: State, proc: Procedure<State, 'rpc', I, O>, extendedContext?: Omit<ServiceContext, 'state'>): (msg: Static<I>) => Promise<Static<O>>;
-export declare function asClientStream<State extends object | unknown, I extends TObject, O extends TObject>(state: State, proc: Procedure<State, 'stream', I, O>, extendedContext?: Omit<ServiceContext, 'state'>): [Pushable<Static<I>>, Pushable<Static<O>>];
+/**
+ * Transforms an RPC procedure definition into a normal function call.
+ * This should only be used for testing.
+ * @template State - The type of the state object.
+ * @template I - The type of the input message payload.
+ * @template O - The type of the output message payload.
+ * @param {State} state - The state object.
+ * @param {Procedure<State, 'rpc', I, O>} proc - The RPC procedure to invoke.
+ * @param {Omit<ServiceContext, 'state'>} [extendedContext] - Optional extended context.
+ * @returns A function that can be used to invoke the RPC procedure.
+ */
+export declare function asClientRpc<State extends object | unknown, I extends TObject, O extends TObject, E extends RiverError>(state: State, proc: Procedure<State, 'rpc', I, O, E>, extendedContext?: Omit<ServiceContext, 'state'>): (msg: Static<I>) => Promise<Result<Static<O>, Static<E> | Static<typeof RiverUncaughtSchema>>>;
+/**
+ * Transforms a stream procedure definition into a pair of input and output streams.
+ * Input messages can be pushed into the input stream.
+ * This should only be used for testing.
+ * @template State - The type of the state object.
+ * @template I - The type of the input object.
+ * @template O - The type of the output object.
+ * @param {State} state - The state object.
+ * @param {Procedure<State, 'stream', I, O>} proc - The procedure to handle the stream.
+ * @param {Omit<ServiceContext, 'state'>} [extendedContext] - The extended context object.
+ * @returns {[Pushable<Static<I>>, Pushable<Static<O>>]} - Pair of input and output streams.
+ */
+export declare function asClientStream<State extends object | unknown, I extends TObject, O extends TObject, E extends RiverError>(state: State, proc: Procedure<State, 'stream', I, O, E>, extendedContext?: Omit<ServiceContext, 'state'>): [
+    Pushable<Static<I>>,
+    Pushable<Result<Static<O>, Static<E> | Static<typeof RiverUncaughtSchema>>>
+];
+/**
+ * Converts a payload object to a transport message with reasonable defaults.
+ * This should only be used for testing.
+ * @param payload - The payload object to be converted.
+ * @param streamId - The optional stream ID.
+ * @returns The transport message.
+ */
+export declare function payloadToTransportMessage<Payload extends object>(payload: Payload, streamId?: string): TransportMessage<Payload>;
+/**
+ * Creates a dummy opaque transport message for testing purposes.
+ * @returns The created opaque transport message.
+ */
+export declare function createDummyTransportMessage(): OpaqueTransportMessage;
+//# sourceMappingURL=testUtils.d.ts.map

package/dist/testUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testUtils.d.ts","sourceRoot":"","sources":["../testUtils.ts"],"names":[],"mappings":";AAAA,OAAO,SAAS,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AACrC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAGjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAY,MAAM,aAAa,CAAC;AACjD,OAAO,EAEL,MAAM,EACN,UAAU,EACV,mBAAmB,EAEpB,MAAM,iBAAiB,CAAC;AAEzB;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,4EAE9D;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAWxE;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,MAAM,sBAE5D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,eAAe,GACnB,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAc1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,KAAK,SAAS,MAAM,GAAG,OAAO,EAC9B,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,UAAU,EAEpB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACtC,eAAe,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,SAGxC,OAAO,CAAC,CAAC,KACb,QACD,OAAO,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,0BAA0B,CAAC,CAAC,CAClE,CAYF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,KAAK,SAAS,MAAM,GAAG,OAAO,EAC9B,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,UAAU,EAEpB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACzC,eAAe,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,GAC9C;IACD,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC;CAC5E,CAuDA;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,SAAS,MAAM,EAC9D,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,MAAM,6BAUlB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,sBAAsB,CAKpE"}

package/dist/testUtils.js

@@ -1,11 +1,25 @@
 import WebSocket from 'isomorphic-ws';
 import { WebSocketServer } from 'ws';
 import { WebSocketTransport } from './transport/impls/ws';
-import { payloadToTransportMessage } from './transport';
+import { msg, reply, } from './transport';
 import { pushable } from 'it-pushable';
+import { Err, UNCAUGHT_ERROR, } from './router/result';
+/**
+ * Creates a WebSocket server instance using the provided HTTP server.
+ * Only used as helper for testing.
+ * @param server - The HTTP server instance to use for the WebSocket server.
+ * @returns A Promise that resolves to the created WebSocket server instance.
+ */
 export async function createWebSocketServer(server) {
     return new WebSocketServer({ server });
 }
+/**
+ * Starts listening on the given server and returns the automatically allocated port number.
+ * This should only be used for testing.
+ * @param server - The http server to listen on.
+ * @returns A promise that resolves with the allocated port number.
+ * @throws An error if a port cannot be allocated.
+ */
 export async function onServerReady(server) {
     return new Promise((resolve, reject) => {
         server.listen(() => {
@@ -19,9 +33,21 @@ export async function onServerReady(server) {
         });
     });
 }
+/**
+ * Creates a WebSocket client that connects to a local server at the specified port.
+ * This should only be used for testing.
+ * @param port - The port number to connect to.
+ * @returns A Promise that resolves to a WebSocket instance.
+ */
 export async function createLocalWebSocketClient(port) {
     return new WebSocket(`ws://localhost:${port}`);
 }
+/**
+ * Creates a pair of WebSocket transports for testing purposes.
+ * @param port - The port number to use for the client transport. This should be acquired after starting a server via {@link createWebSocketServer}.
+ * @param wss - The WebSocketServer instance to use for the server transport.
+ * @returns An array containing the client and server {@link WebSocketTransport} instances.
+ */
 export function createWsTransports(port, wss) {
     return [
         new WebSocketTransport(async () => {
@@ -37,14 +63,46 @@ export function createWsTransports(port, wss) {
         }, 'SERVER'),
     ];
 }
+/**
+ * Transforms an RPC procedure definition into a normal function call.
+ * This should only be used for testing.
+ * @template State - The type of the state object.
+ * @template I - The type of the input message payload.
+ * @template O - The type of the output message payload.
+ * @param {State} state - The state object.
+ * @param {Procedure<State, 'rpc', I, O>} proc - The RPC procedure to invoke.
+ * @param {Omit<ServiceContext, 'state'>} [extendedContext] - Optional extended context.
+ * @returns A function that can be used to invoke the RPC procedure.
+ */
 export function asClientRpc(state, proc, extendedContext) {
     return (msg) => proc
         .handler({ ...extendedContext, state }, payloadToTransportMessage(msg))
-        .then((res) => res.payload);
+        .then((res) => res.payload)
+        .catch((err) => {
+        const errorMsg = err instanceof Error ? err.message : `[coerced to error] ${err}`;
+        return Err({
+            code: UNCAUGHT_ERROR,
+            message: errorMsg,
+        });
+    });
 }
+/**
+ * Transforms a stream procedure definition into a pair of input and output streams.
+ * Input messages can be pushed into the input stream.
+ * This should only be used for testing.
+ * @template State - The type of the state object.
+ * @template I - The type of the input object.
+ * @template O - The type of the output object.
+ * @param {State} state - The state object.
+ * @param {Procedure<State, 'stream', I, O>} proc - The procedure to handle the stream.
+ * @param {Omit<ServiceContext, 'state'>} [extendedContext] - The extended context object.
+ * @returns {[Pushable<Static<I>>, Pushable<Static<O>>]} - Pair of input and output streams.
+ */
 export function asClientStream(state, proc, extendedContext) {
     const rawInput = pushable({ objectMode: true });
-    const rawOutput = pushable({ objectMode: true });
+    const rawOutput = pushable({
+        objectMode: true,
+    });
     const transportInput = pushable({
         objectMode: true,
     });
@@ -66,8 +124,37 @@ export function asClientStream(state, proc, extendedContext) {
     })();
     // handle
     (async () => {
-        await proc.handler({ ...extendedContext, state }, transportInput, transportOutput);
+        try {
+            await proc.handler({ ...extendedContext, state }, transportInput, transportOutput);
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : `[coerced to error] ${err}`;
+            transportOutput.push(reply(payloadToTransportMessage({}), Err({
+                code: UNCAUGHT_ERROR,
+                message: errorMsg,
+            })));
+        }
         transportOutput.end();
     })();
     return [rawInput, rawOutput];
 }
+/**
+ * Converts a payload object to a transport message with reasonable defaults.
+ * This should only be used for testing.
+ * @param payload - The payload object to be converted.
+ * @param streamId - The optional stream ID.
+ * @returns The transport message.
+ */
+export function payloadToTransportMessage(payload, streamId) {
+    return msg('client', 'SERVER', 'service', 'procedure', streamId ?? 'stream', payload);
+}
+/**
+ * Creates a dummy opaque transport message for testing purposes.
+ * @returns The created opaque transport message.
+ */
+export function createDummyTransportMessage() {
+    return payloadToTransportMessage({
+        msg: 'cool',
+        test: Math.random(),
+    });
+}

package/dist/transport/impls/stdio.d.ts

@@ -1,10 +1,35 @@
 /// <reference types="node" />
 import { OpaqueTransportMessage, TransportClientId } from '../message';
 import { Transport } from '../types';
+/**
+ * A transport implementation that uses standard input and output streams.
+ * @extends Transport
+ */
 export declare class StdioTransport extends Transport {
+    /**
+     * The readable stream to use as input.
+     */
     input: NodeJS.ReadableStream;
+    /**
+     * The writable stream to use as output.
+     */
     output: NodeJS.WritableStream;
+    /**
+     * Constructs a new StdioTransport instance.
+     * @param clientId - The ID of the client associated with this transport.
+     * @param input - The readable stream to use as input. Defaults to process.stdin.
+     * @param output - The writable stream to use as output. Defaults to process.stdout.
+     */
     constructor(clientId: TransportClientId, input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream);
+    /**
+     * Sends a message over the transport.
+     * @param msg - The message to send.
+     * @returns The ID of the sent message.
+     */
     send(msg: OpaqueTransportMessage): string;
+    /**
+     * Closes the transport.
+     */
     close(): Promise<void>;
 }
+//# sourceMappingURL=stdio.d.ts.map

package/dist/transport/impls/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../../transport/impls/stdio.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGrC;;;GAGG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC3C;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC;IAC7B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAE9B;;;;;OAKG;gBAED,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,GAAE,MAAM,CAAC,cAA8B,EAC5C,MAAM,GAAE,MAAM,CAAC,cAA+B;IAYhD;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,sBAAsB,GAAG,MAAM;IAMzC;;OAEG;IACG,KAAK;CACZ"}

package/dist/transport/impls/stdio.js

@@ -1,9 +1,25 @@
 import { NaiveJsonCodec } from '../../codec/json';
 import { Transport } from '../types';
 import readline from 'readline';
+/**
+ * A transport implementation that uses standard input and output streams.
+ * @extends Transport
+ */
 export class StdioTransport extends Transport {
+    /**
+     * The readable stream to use as input.
+     */
     input;
+    /**
+     * The writable stream to use as output.
+     */
     output;
+    /**
+     * Constructs a new StdioTransport instance.
+     * @param clientId - The ID of the client associated with this transport.
+     * @param input - The readable stream to use as input. Defaults to process.stdin.
+     * @param output - The writable stream to use as output. Defaults to process.stdout.
+     */
     constructor(clientId, input = process.stdin, output = process.stdout) {
         super(NaiveJsonCodec, clientId);
         this.input = input;
@@ -13,10 +29,18 @@ export class StdioTransport extends Transport {
         });
         rl.on('line', (msg) => this.onMessage(msg));
     }
+    /**
+     * Sends a message over the transport.
+     * @param msg - The message to send.
+     * @returns The ID of the sent message.
+     */
     send(msg) {
         const id = msg.id;
         this.output.write(this.codec.toStringBuf(msg) + '\n');
         return id;
     }
+    /**
+     * Closes the transport.
+     */
     async close() { }
 }

package/dist/transport/impls/stdio.test.d.ts

@@ -1 +1,2 @@
 export {};
+//# sourceMappingURL=stdio.test.d.ts.map

package/dist/transport/impls/stdio.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.test.d.ts","sourceRoot":"","sources":["../../../transport/impls/stdio.test.ts"],"names":[],"mappings":""}

package/dist/transport/impls/stdio.test.js

@@ -2,6 +2,7 @@ import { describe, test, expect } from 'vitest';
 import stream from 'node:stream';
 import { StdioTransport } from './stdio';
 import { waitForMessage } from '..';
+import { payloadToTransportMessage } from '../../testUtils';
 describe('sending and receiving across node streams works', () => {
     test('basic send/receive', async () => {
         const clientToServer = new stream.PassThrough();
@@ -13,14 +14,7 @@ describe('sending and receiving across node streams works', () => {
             test: 123,
         };
         const p = waitForMessage(serverTransport);
-        clientTransport.send({
-            id: '1',
-            from: 'client',
-            to: 'SERVER',
-            serviceName: 'test',
-            procedureName: 'test',
-            payload: msg,
-        });
+        clientTransport.send(payloadToTransportMessage(msg));
         await expect(p).resolves.toStrictEqual(msg);
     });
 });

package/dist/transport/impls/ws.d.ts

@@ -10,16 +10,55 @@ type WebSocketResult = {
 } | {
     err: string;
 };
+/**
+ * A transport implementation that uses a WebSocket connection with automatic reconnection.
+ * @class
+ * @extends Transport
+ */
 export declare class WebSocketTransport extends Transport {
+    /**
+     * A function that returns a Promise that resolves to a WebSocket instance.
+     */
     wsGetter: () => Promise<WebSocket>;
     ws?: WebSocket;
+    options: Options;
+    /**
+     * A flag indicating whether the transport has been destroyed.
+     * A destroyed transport will not attempt to reconnect and cannot be used again.
+     */
     destroyed: boolean;
+    /**
+     * An ongoing reconnect attempt if it exists. When the attempt finishes, it contains a
+     * {@link WebSocketResult} object when a connection is established or an error occurs.
+     */
     reconnectPromise?: Promise<WebSocketResult>;
-    options: Options;
+    /**
+     * An array of message IDs that are waiting to be sent over the WebSocket connection.
+     * This builds up if the WebSocket is down for a period of time.
+     */
     sendQueue: Array<MessageId>;
+    /**
+     * Creates a new WebSocketTransport instance.
+     * @param wsGetter A function that returns a Promise that resolves to a WebSocket instance.
+     * @param clientId The ID of the client using the transport.
+     * @param options An optional object containing configuration options for the transport.
+     */
     constructor(wsGetter: () => Promise<WebSocket>, clientId: TransportClientId, options?: Partial<Options>);
+    /**
+     * Begins a new attempt to establish a WebSocket connection.
+     */
     private tryConnect;
+    /**
+     * Sends a message over the WebSocket connection. If the WebSocket connection is
+     * not healthy, it will queue until the connection is successful.
+     * @param msg The message to send.
+     * @returns The ID of the sent message.
+     */
     send(msg: OpaqueTransportMessage): MessageId;
+    /**
+     * Destroys the WebSocket transport and marks it as unusable.
+     */
     close(): Promise<void | undefined>;
 }
 export {};
+//# sourceMappingURL=ws.d.ts.map

package/dist/transport/impls/ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../../transport/impls/ws.ts"],"names":[],"mappings":";AAAA,OAAO,SAAS,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,EACL,SAAS,EACT,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAGpB,UAAU,OAAO;IACf,eAAe,EAAE,MAAM,CAAC;CACzB;AAMD,KAAK,eAAe,GAAG;IAAE,EAAE,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C;;OAEG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;IACnC,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAE5C;;;OAGG;IACH,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAE5B;;;;;OAKG;gBAED,QAAQ,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EAClC,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAU5B;;OAEG;YACW,UAAU;IAkExB;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,sBAAsB,GAAG,SAAS;IAyB5C;;OAEG;IACG,KAAK;CAKZ"}

package/dist/transport/impls/ws.js

@@ -4,13 +4,39 @@ import { log } from '../../logging';
 const defaultOptions = {
     retryIntervalMs: 250,
 };
+/**
+ * A transport implementation that uses a WebSocket connection with automatic reconnection.
+ * @class
+ * @extends Transport
+ */
 export class WebSocketTransport extends Transport {
+    /**
+     * A function that returns a Promise that resolves to a WebSocket instance.
+     */
     wsGetter;
     ws;
+    options;
+    /**
+     * A flag indicating whether the transport has been destroyed.
+     * A destroyed transport will not attempt to reconnect and cannot be used again.
+     */
     destroyed;
+    /**
+     * An ongoing reconnect attempt if it exists. When the attempt finishes, it contains a
+     * {@link WebSocketResult} object when a connection is established or an error occurs.
+     */
     reconnectPromise;
-    options;
+    /**
+     * An array of message IDs that are waiting to be sent over the WebSocket connection.
+     * This builds up if the WebSocket is down for a period of time.
+     */
     sendQueue;
+    /**
+     * Creates a new WebSocketTransport instance.
+     * @param wsGetter A function that returns a Promise that resolves to a WebSocket instance.
+     * @param clientId The ID of the client using the transport.
+     * @param options An optional object containing configuration options for the transport.
+     */
     constructor(wsGetter, clientId, options) {
         super(NaiveJsonCodec, clientId);
         this.destroyed = false;
@@ -19,7 +45,9 @@ export class WebSocketTransport extends Transport {
         this.sendQueue = [];
         this.tryConnect();
     }
-    // postcondition: ws is concretely a WebSocket
+    /**
+     * Begins a new attempt to establish a WebSocket connection.
+     */
     async tryConnect() {
         // wait until it's ready or we get an error
         this.reconnectPromise ??= new Promise(async (resolve) => {
@@ -73,6 +101,12 @@ export class WebSocketTransport extends Transport {
         this.reconnectPromise = undefined;
         setTimeout(() => this.tryConnect(), this.options.retryIntervalMs);
     }
+    /**
+     * Sends a message over the WebSocket connection. If the WebSocket connection is
+     * not healthy, it will queue until the connection is successful.
+     * @param msg The message to send.
+     * @returns The ID of the sent message.
+     */
     send(msg) {
         const id = msg.id;
         if (this.destroyed) {
@@ -92,6 +126,9 @@ export class WebSocketTransport extends Transport {
         }
         return id;
     }
+    /**
+     * Destroys the WebSocket transport and marks it as unusable.
+     */
     async close() {
         log?.info('manually closed ws');
         this.destroyed = true;

package/dist/transport/impls/ws.test.d.ts

@@ -1 +1,2 @@
 export {};
+//# sourceMappingURL=ws.test.d.ts.map

package/dist/transport/impls/ws.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.test.d.ts","sourceRoot":"","sources":["../../../transport/impls/ws.test.ts"],"names":[],"mappings":""}