@replit/river 0.7.2 → 0.8.1

package/dist/transport/transport.js

@@ -2,11 +2,15 @@ import { Value } from '@sinclair/typebox/value';
 import { OpaqueTransportMessageSchema, TransportAckSchema, isAck, reply, } from './message';
 import { log } from '../logging';
 /**
- * Abstract base for a connection between two nodes in a River network.
- * A connection is responsible for sending and receiving messages on a 1:1
- * basis between nodes.
- * Connections can be reused across different transports.
- * @abstract
+ * A 1:1 connection between two transports. Once this is created,
+ * the {@link Connection} is expected to take over responsibility for
+ * reading and writing messages from the underlying connection.
+ *
+ * 1) Messages received on the {@link Connection} are dispatched back to the {@link Transport}
+ *    via {@link Transport.onMessage}. The {@link Transport} then notifies any registered message listeners.
+ * 2) When {@link Transport.send}(msg) is called, the transport looks up the appropriate
+ *    connection in the {@link connections} map via `msg.to` and calls {@link send}(bytes)
+ *    so the connection can send it.
  */
 export class Connection {
     connectedTo;
@@ -15,15 +19,35 @@ export class Connection {
         this.connectedTo = connectedTo;
         this.transport = transport;
     }
-    onMessage(msg) {
-        return this.transport.onMessage(msg);
-    }
 }
 /**
- * Abstract base for a transport layer for communication between nodes in a River network.
- * A transport is responsible for handling the 1:n connection logic between nodes and
- * delegating sending/receiving to connections.
- * Any River transport methods need to implement this interface.
+ * Transports manage the lifecycle (creation/deletion) of connections. Its responsibilities include:
+ *
+ *  1) Constructing a new {@link Connection} on {@link TransportMessage}s from new clients.
+ *     After constructing the {@link Connection}, {@link onConnect} is called which adds it to the connection map.
+ *  2) Delegating message listening of the connection to the newly created {@link Connection}.
+ *     From this point on, the {@link Connection} is responsible for *reading* and *writing*
+ *     messages from the connection.
+ *  3) When a connection is closed, the {@link Transport} calls {@link onDisconnect} which closes the
+ *     connection via {@link Connection.close} and removes it from the {@link connections} map.
+
+ *
+ * ```plaintext
+ *            ▲
+ *  incoming  │
+ *  messages  │
+ *            ▼
+ *      ┌─────────────┐   1:N   ┌────────────┐
+ *      │  Transport  │ ◄─────► │ Connection │
+ *      └─────────────┘         └────────────┘
+ *            ▲
+ *            │
+ *            ▼
+ *      ┌───────────┐
+ *      │ Message   │
+ *      │ Listeners │
+ *      └───────────┘
+ * ```
  * @abstract
  */
 export class Transport {
@@ -91,7 +115,7 @@ export class Transport {
             }
             this.send(msg);
         }
-        this.sendQueue.set(conn.connectedTo, []);
+        this.sendQueue.delete(conn.connectedTo);
     }
     /**
      * The downstream implementation needs to call this when a connection is closed.

package/dist/{testUtils.d.ts → util/testHelpers.d.ts}

@@ -2,14 +2,14 @@
 import WebSocket from 'isomorphic-ws';
 import { WebSocketServer } from 'ws';
 import http from 'http';
-import { WebSocketClientTransport } from './transport/impls/ws/client';
+import { WebSocketClientTransport } from '../transport/impls/ws/client';
 import { Static, TObject } from '@sinclair/typebox';
-import { Procedure, ServiceContext } from './router';
-import { OpaqueTransportMessage, TransportClientId, TransportMessage } from './transport';
+import { Procedure, ServiceContext } from '../router';
+import { OpaqueTransportMessage, TransportClientId, TransportMessage } from '../transport';
 import { Pushable } from 'it-pushable';
-import { Result, RiverError, RiverUncaughtSchema } from './router/result';
-import { Codec } from './codec';
-import { WebSocketServerTransport } from './transport/impls/ws/server';
+import { Result, RiverError, RiverUncaughtSchema } from '../router/result';
+import { Codec } from '../codec';
+import { WebSocketServerTransport } from '../transport/impls/ws/server';
 /**
  * Creates a WebSocket server instance using the provided HTTP server.
  * Only used as helper for testing.
@@ -61,12 +61,25 @@ export declare function asClientRpc<State extends object | unknown, I extends TO
  * @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.
+ * @returns 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>>>
 ];
+/**
+ * Transforms a subscription procedure definition into a procedure that returns an output stream.
+ * 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 A function that when passed a message, returns the output stream.
+ */
+export declare function asClientSubscription<State extends object | unknown, I extends TObject, O extends TObject, E extends RiverError>(state: State, proc: Procedure<State, 'subscription', I, O, E>, extendedContext?: Omit<ServiceContext, 'state'>): (msg: Static<I>) => Promise<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.
@@ -80,4 +93,10 @@ export declare function payloadToTransportMessage<Payload extends object>(payloa
  * @returns The created opaque transport message.
  */
 export declare function createDummyTransportMessage(): OpaqueTransportMessage;
-//# sourceMappingURL=testUtils.d.ts.map
+/**
+ * Retrieves the next value from an async iterable iterator.
+ * @param iter The async iterable iterator.
+ * @returns A promise that resolves to the next value from the iterator.
+ */
+export declare function iterNext<T>(iter: AsyncIterableIterator<T>): Promise<any>;
+//# sourceMappingURL=testHelpers.d.ts.map

package/dist/util/testHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testHelpers.d.ts","sourceRoot":"","sources":["../../util/testHelpers.ts"],"names":[],"mappings":"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"}

package/dist/{testUtils.js → util/testHelpers.js}

@@ -1,10 +1,10 @@
 import WebSocket from 'isomorphic-ws';
 import { WebSocketServer } from 'ws';
-import { WebSocketClientTransport } from './transport/impls/ws/client';
-import { msg, reply, } from './transport';
+import { WebSocketClientTransport } from '../transport/impls/ws/client';
+import { msg, reply, } from '../transport';
 import { pushable } from 'it-pushable';
-import { Err, UNCAUGHT_ERROR, } from './router/result';
-import { WebSocketServerTransport } from './transport/impls/ws/server';
+import { Err, UNCAUGHT_ERROR, } from '../router/result';
+import { WebSocketServerTransport } from '../transport/impls/ws/server';
 /**
  * Creates a WebSocket server instance using the provided HTTP server.
  * Only used as helper for testing.
@@ -91,7 +91,7 @@ export function asClientRpc(state, proc, extendedContext) {
  * @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.
+ * @returns Pair of input and output streams.
  */
 export function asClientStream(state, proc, extendedContext) {
     const rawInput = pushable({ objectMode: true });
@@ -133,6 +133,44 @@ export function asClientStream(state, proc, extendedContext) {
     })();
     return [rawInput, rawOutput];
 }
+/**
+ * Transforms a subscription procedure definition into a procedure that returns an output stream.
+ * 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 A function that when passed a message, returns the output stream.
+ */
+export function asClientSubscription(state, proc, extendedContext) {
+    const rawOutput = pushable({
+        objectMode: true,
+    });
+    const transportOutput = pushable({
+        objectMode: true,
+    });
+    // unwrap from transport
+    (async () => {
+        for await (const transportRes of transportOutput) {
+            rawOutput.push(transportRes.payload);
+        }
+    })();
+    return async (msg) => {
+        proc
+            .handler({ ...extendedContext, state }, payloadToTransportMessage(msg), transportOutput)
+            .catch((err) => {
+            const errorMsg = err instanceof Error ? err.message : `[coerced to error] ${err}`;
+            return Err({
+                code: UNCAUGHT_ERROR,
+                message: errorMsg,
+            });
+        });
+        return rawOutput;
+    };
+}
 /**
  * Converts a payload object to a transport message with reasonable defaults.
  * This should only be used for testing.
@@ -153,3 +191,11 @@ export function createDummyTransportMessage() {
         test: Math.random(),
     });
 }
+/**
+ * Retrieves the next value from an async iterable iterator.
+ * @param iter The async iterable iterator.
+ * @returns A promise that resolves to the next value from the iterator.
+ */
+export function iterNext(iter) {
+    return iter.next().then((res) => res.value);
+}

package/package.json

@@ -2,13 +2,13 @@
   "name": "@replit/river",
   "sideEffects": false,
   "description": "It's like tRPC but... with JSON Schema Support, duplex streaming and support for service multiplexing. Transport agnostic!",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "type": "module",
   "exports": {
     ".": "./dist/router/index.js",
     "./logging": "./dist/logging/index.js",
     "./codec": "./dist/codec/index.js",
-    "./test-util": "./dist/testUtils.js",
+    "./test-util": "./dist/util/testHelpers.js",
     "./transport": "./dist/transport/index.js",
     "./transport/ws/client": "./dist/transport/impls/ws/client.js",
     "./transport/ws/server": "./dist/transport/impls/ws/server.js",
@@ -40,7 +40,7 @@
     "prepack": "npm run build",
     "release": "npm publish --access public",
     "test:ui": "echo \"remember to go to /__vitest__ in the webview\" && vitest --ui --api.host 0.0.0.0 --api.port 3000",
-    "test": "vitest",
+    "test": "vitest --test-timeout=500",
     "bench": "vitest bench"
   },
   "engines": {

package/dist/__tests__/fixtures.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../__tests__/fixtures.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,WAAW;;;EAGtB,CAAC;AACH,eAAO,MAAM,YAAY;;EAA2C,CAAC;AAErE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BpB,CAAC;AAEhB,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyBxB,CAAC;AAEhB,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;CAc1B,CAAC;AAEhB,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAC3C,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiExB,CAAC"}

package/dist/testUtils.d.ts.map

@@ -1 +0,0 @@
-{"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,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,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;AACzB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;;;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,sBAI5D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,eAAe,EACpB,KAAK,CAAC,EAAE,KAAK,GACZ,CAAC,wBAAwB,EAAE,wBAAwB,CAAC,CAWtD;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,EACjB,IAAI,GAAE,iBAA4B,EAClC,EAAE,GAAE,iBAA4B,GAC/B,gBAAgB,CAAC,OAAO,CAAC,CAE3B;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,sBAAsB,CAKpE"}