@replit/river 0.3.0 → 0.5.0

package/dist/__tests__/typescript-stress.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-stress.test.d.ts","sourceRoot":"","sources":["../../__tests__/typescript-stress.test.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAS,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AA8B/C,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDlB,CAAC;AAGhB,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,QAAQ,EAAE,MAAM;IAI5B,IAAI,CAAC,GAAG,EAAE,sBAAsB,GAAG,SAAS;IAKtC,KAAK;CACZ"}

package/dist/__tests__/typescript-stress.test.js

@@ -6,14 +6,26 @@ import { createServer } from '../router/server';
 import { Transport } from '../transport/types';
 import { NaiveJsonCodec } from '../codec/json';
 import { createClient } from '../router/client';
+import { Ok } from '../router/result';
 const input = Type.Object({ a: Type.Number() });
 const output = Type.Object({ b: Type.Number() });
+const errors = Type.Union([
+    Type.Object({
+        code: Type.Literal('ERROR1'),
+        message: Type.String(),
+    }),
+    Type.Object({
+        code: Type.Literal('ERROR2'),
+        message: Type.String(),
+    }),
+]);
 const fnBody = {
     type: 'rpc',
     input,
     output,
+    errors,
     async handler(_state, msg) {
-        return reply(msg, { b: msg.payload.a });
+        return reply(msg, Ok({ b: msg.payload.a }));
     },
 };
 // typescript is limited to max 50 constraints

package/dist/codec/codec.test.d.ts

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

package/dist/codec/codec.test.d.ts.map

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

package/dist/codec/index.d.ts

@@ -1,2 +1,3 @@
 export { NaiveJsonCodec } from './json';
 export type { Codec } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/codec/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../codec/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AACxC,YAAY,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC"}

package/dist/codec/json.d.ts

@@ -1,2 +1,7 @@
 import { Codec } from './types';
+/**
+ * Naive JSON codec implementation using JSON.stringify and JSON.parse.
+ * @type {Codec}
+ */
 export declare const NaiveJsonCodec: Codec;
+//# sourceMappingURL=json.d.ts.map

package/dist/codec/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../codec/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,KAS5B,CAAC"}

package/dist/codec/json.js

@@ -1,3 +1,7 @@
+/**
+ * Naive JSON codec implementation using JSON.stringify and JSON.parse.
+ * @type {Codec}
+ */
 export const NaiveJsonCodec = {
     toStringBuf: JSON.stringify,
     fromStringBuf: (s) => {

package/dist/codec/types.d.ts

@@ -1,4 +1,19 @@
+/**
+ * Codec interface for encoding and decoding objects to and from string buffers.
+ * Used to prepare messages for use by the transport layer.
+ */
 export interface Codec {
+    /**
+     * Encodes an object to a string buffer.
+     * @param obj - The object to encode.
+     * @returns The encoded string buffer.
+     */
     toStringBuf(obj: object): string;
+    /**
+     * Decodes an object from a string buffer.
+     * @param buf - The string buffer to decode.
+     * @returns The decoded object, or null if decoding failed.
+     */
     fromStringBuf(buf: string): object | null;
 }
+//# sourceMappingURL=types.d.ts.map

package/dist/codec/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../codec/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC3C"}

package/dist/logging/index.d.ts

@@ -9,7 +9,20 @@ export type Logger = {
 } & {
     [key in LoggingLevel]: (msg: string) => void;
 };
+/**
+ * The global River logger instance.
+ */
 export declare let log: Logger | undefined;
+/**
+ * Binds the given write function to River's logger {@link log}.
+ * @param write - The function to write log messages.
+ * @param color - Whether to use colored log levels.
+ */
 export declare function bindLogger(write: (msg: string) => void, color?: boolean): void;
+/**
+ * Sets the minimum logging level for the logger.
+ * @param level - The minimum logging level to set.
+ */
 export declare function setLevel(level: LoggingLevel): void;
 export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/logging/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../logging/index.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,aAAa;;;;CAIT,CAAC;AAEX,KAAK,YAAY,GAAG,MAAM,OAAO,aAAa,CAAC;AAC/C,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,EAAE,YAAY,CAAC;CACxB,GAAG;KACD,GAAG,IAAI,YAAY,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI;CAC7C,CAAC;AAEF;;GAEG;AACH,eAAO,IAAI,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;AAGnC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,QAoBvE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,QAI3C"}

package/dist/logging/index.js

@@ -3,8 +3,16 @@ const LoggingLevels = {
     warn: 1,
     error: 2,
 };
+/**
+ * The global River logger instance.
+ */
 export let log;
 const defaultLoggingLevel = 'warn';
+/**
+ * Binds the given write function to River's logger {@link log}.
+ * @param write - The function to write log messages.
+ * @param color - Whether to use colored log levels.
+ */
 export function bindLogger(write, color) {
     const info = color ? '\u001b[37minfo\u001b[0m' : 'info';
     const warn = color ? '\u001b[33mwarn\u001b[0m' : 'warn';
@@ -22,6 +30,10 @@ export function bindLogger(write, color) {
         minLevel: log?.minLevel ?? defaultLoggingLevel,
     };
 }
+/**
+ * Sets the minimum logging level for the logger.
+ * @param level - The minimum logging level to set.
+ */
 export function setLevel(level) {
     if (log) {
         log.minLevel = level;

package/dist/router/builder.d.ts

@@ -1,50 +1,134 @@
-import { TObject, Static } from '@sinclair/typebox';
+import { TObject, Static, TUnion } from '@sinclair/typebox';
 import type { Pushable } from 'it-pushable';
 import { TransportMessage } from '../transport/message';
 import { ServiceContextWithState } from './context';
+import { Result, RiverError, RiverUncaughtSchema } from './result';
+/**
+ * The valid {@link Procedure} types.
+ */
 export type ValidProcType = 'stream' | 'rpc';
-export type ProcListing = Record<string, Procedure<object, ValidProcType, TObject, TObject>>;
+/**
+ * A generic procedure listing where the keys are the names of the procedures
+ * and the values are the {@link Procedure} definitions. This is not meant to
+ * be constructed directly, use the {@link ServiceBuilder} class instead.
+ */
+export type ProcListing = Record<string, AnyProcedure>;
+/**
+ * Represents a service with a name, state, and procedures.
+ * This is not meant to be constructed directly, use the {@link ServiceBuilder} class instead.
+ * @template Name The type of the service name.
+ * @template State The type of the service state.
+ * @template Procs The type of the service procedures.
+ */
 export interface Service<Name extends string, State extends object, Procs extends ProcListing> {
     name: Name;
     state: State;
     procedures: Procs;
 }
 export type AnyService = Service<string, object, any>;
+/**
+ * Serializes a service object into its corresponding JSON Schema Draft 7 type.
+ * @param {AnyService} s - The service object to serialize.
+ * @returns A plain object representing the serialized service.
+ */
 export declare function serializeService(s: AnyService): object;
+/**
+ * Helper to get the type definition for a specific handler of a procedure in a service.
+ * @template S - The service.
+ * @template ProcName - The name of the procedure.
+ */
 export type ProcHandler<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['handler'];
+/**
+ * Helper to get the type definition for the procedure input of a service.
+ * @template S - The service.
+ * @template ProcName - The name of the procedure.
+ */
 export type ProcInput<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['input'];
+/**
+ * Helper to get the type definition for the procedure output of a service.
+ * @template S - The service.
+ * @template ProcName - The name of the procedure.
+ */
 export type ProcOutput<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['output'];
+/**
+ * Helper to get the type definition for the procedure errors of a service.
+ * @template S - The service.
+ * @template ProcName - The name of the procedure.
+ */
+export type ProcErrors<S extends AnyService, ProcName extends keyof S['procedures']> = TUnion<[S['procedures'][ProcName]['errors'], typeof RiverUncaughtSchema]>;
+/**
+ * Helper to get the type of procedure in a service.
+ * @template S - The service.
+ * @template ProcName - The name of the procedure.
+ */
 export type ProcType<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['type'];
-export type Procedure<State extends object | unknown, Ty extends ValidProcType, I extends TObject, O extends TObject> = Ty extends 'rpc' ? {
+/**
+ * Defines a Procedure type that can be either an RPC or a stream procedure.
+ * @template State - The TypeBox schema of the state object.
+ * @template Ty - The type of the procedure, either 'rpc' or 'stream'.
+ * @template I - The TypeBox schema of the input object.
+ * @template O - The TypeBox schema of the output object.
+ */
+export type Procedure<State extends object | unknown, Ty extends ValidProcType, I extends TObject, O extends TObject, E extends RiverError> = Ty extends 'rpc' ? {
     input: I;
     output: O;
-    handler: (context: ServiceContextWithState<State>, input: TransportMessage<Static<I>>) => Promise<TransportMessage<Static<O>>>;
+    errors: E;
+    handler: (context: ServiceContextWithState<State>, input: TransportMessage<Static<I>>) => Promise<TransportMessage<Result<Static<O>, Static<E>>>>;
     type: Ty;
 } : {
     input: I;
     output: O;
-    handler: (context: ServiceContextWithState<State>, input: AsyncIterable<TransportMessage<Static<I>>>, output: Pushable<TransportMessage<Static<O>>>) => Promise<void>;
+    errors: E;
+    handler: (context: ServiceContextWithState<State>, input: AsyncIterable<TransportMessage<Static<I>>>, output: Pushable<TransportMessage<Result<Static<O>, Static<E>>>>) => Promise<void>;
     type: Ty;
 };
+export type AnyProcedure = Procedure<object, ValidProcType, TObject, TObject, RiverError>;
+/**
+ * A builder class for creating River Services.
+ * You must call the finalize method to get the finalized schema for use in a service router.
+ * @template T The type of the service.
+ */
 export declare class ServiceBuilder<T extends Service<string, object, ProcListing>> {
     private readonly schema;
     private constructor();
+    /**
+     * Finalizes the schema for the service.
+     * @returns {T} The finalized schema for the service.
+     */
     finalize(): T;
+    /**
+     * Sets the initial state for the service.
+     * @template InitState The type of the initial state.
+     * @param {InitState} state The initial state for the service.
+     * @returns {ServiceBuilder<{ name: T['name']; state: InitState; procedures: T['procedures']; }>} A new ServiceBuilder instance with the updated schema.
+     */
     initialState<InitState extends T['state']>(state: InitState): ServiceBuilder<{
         name: T['name'];
         state: InitState;
         procedures: T['procedures'];
     }>;
-    defineProcedure<ProcName extends string, Ty extends ValidProcType, I extends TObject, O extends TObject>(procName: ProcName, procDef: Procedure<T['state'], Ty, I, O>): ServiceBuilder<{
+    /**
+     * Defines a new procedure for the service.
+     * @param {ProcName} procName The name of the procedure.
+     * @param {Procedure<T['state'], Ty, I, O>} procDef The definition of the procedure.
+     * @returns {ServiceBuilder<{ name: T['name']; state: T['state']; procedures: T['procedures'] & { [k in ProcName]: Procedure<T['state'], Ty, I, O>; }; }>} A new ServiceBuilder instance with the updated schema.
+     */
+    defineProcedure<ProcName extends string, Ty extends ValidProcType, I extends TObject, O extends TObject, E extends RiverError>(procName: ProcName, procDef: Procedure<T['state'], Ty, I, O, E>): ServiceBuilder<{
         name: T['name'];
         state: T['state'];
         procedures: T['procedures'] & {
-            [k in ProcName]: Procedure<T['state'], Ty, I, O>;
+            [k in ProcName]: Procedure<T['state'], Ty, I, O, E>;
         };
     }>;
+    /**
+     * Creates a new instance of ServiceBuilder.
+     * @param {Name} name The name of the service.
+     * @returns {ServiceBuilder<{ name: Name; state: {}; procedures: {}; }>} A new instance of ServiceBuilder.
+     */
     static create<Name extends string>(name: Name): ServiceBuilder<{
         name: Name;
         state: {};
         procedures: {};
     }>;
 }
+//# sourceMappingURL=builder.d.ts.map

package/dist/router/builder.d.ts.map

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

package/dist/router/builder.js

@@ -1,4 +1,9 @@
 import { Type } from '@sinclair/typebox';
+/**
+ * Serializes a service object into its corresponding JSON Schema Draft 7 type.
+ * @param {AnyService} s - The service object to serialize.
+ * @returns A plain object representing the serialized service.
+ */
 export function serializeService(s) {
     return {
         name: s.name,
@@ -8,25 +13,47 @@ export function serializeService(s) {
             {
                 input: Type.Strict(procDef.input),
                 output: Type.Strict(procDef.output),
+                errors: Type.Strict(procDef.errors),
                 type: procDef.type,
             },
         ])),
     };
 }
+/**
+ * A builder class for creating River Services.
+ * You must call the finalize method to get the finalized schema for use in a service router.
+ * @template T The type of the service.
+ */
 export class ServiceBuilder {
     schema;
     constructor(schema) {
         this.schema = schema;
     }
+    /**
+     * Finalizes the schema for the service.
+     * @returns {T} The finalized schema for the service.
+     */
     finalize() {
         return this.schema;
     }
+    /**
+     * Sets the initial state for the service.
+     * @template InitState The type of the initial state.
+     * @param {InitState} state The initial state for the service.
+     * @returns {ServiceBuilder<{ name: T['name']; state: InitState; procedures: T['procedures']; }>} A new ServiceBuilder instance with the updated schema.
+     */
     initialState(state) {
         return new ServiceBuilder({
             ...this.schema,
             state,
         });
     }
+    /**
+     * Defines a new procedure for the service.
+     * @param {ProcName} procName The name of the procedure.
+     * @param {Procedure<T['state'], Ty, I, O>} procDef The definition of the procedure.
+     * @returns {ServiceBuilder<{ name: T['name']; state: T['state']; procedures: T['procedures'] & { [k in ProcName]: Procedure<T['state'], Ty, I, O>; }; }>} A new ServiceBuilder instance with the updated schema.
+     */
     defineProcedure(procName, procDef) {
         const newProcedure = { [procName]: procDef };
         const procedures = {
@@ -38,6 +65,11 @@ export class ServiceBuilder {
             procedures,
         });
     }
+    /**
+     * Creates a new instance of ServiceBuilder.
+     * @param {Name} name The name of the service.
+     * @returns {ServiceBuilder<{ name: Name; state: {}; procedures: {}; }>} A new instance of ServiceBuilder.
+     */
     static create(name) {
         return new ServiceBuilder({
             name,

package/dist/router/client.d.ts

@@ -1,17 +1,42 @@
 import { Transport } from '../transport/types';
-import { AnyService, ProcInput, ProcOutput, ProcType } from './builder';
+import { AnyService, ProcErrors, ProcInput, ProcOutput, ProcType } from './builder';
 import type { Pushable } from 'it-pushable';
 import { Server } from './server';
 import { Static } from '@sinclair/typebox';
+import { Result } from './result';
+type AsyncIter<T> = AsyncGenerator<T, T, T>;
+/**
+ * A helper type to transform an actual service type into a type
+ * we can case to in the proxy.
+ * @template Router - The type of the Router.
+ */
 type ServiceClient<Router extends AnyService> = {
-    [ProcName in keyof Router['procedures']]: ProcType<Router, ProcName> extends 'rpc' ? (input: Static<ProcInput<Router, ProcName>>) => Promise<Static<ProcOutput<Router, ProcName>>> : () => Promise<[
+    [ProcName in keyof Router['procedures']]: ProcType<Router, ProcName> extends 'rpc' ? (input: Static<ProcInput<Router, ProcName>>) => Promise<Result<Static<ProcOutput<Router, ProcName>>, Static<ProcErrors<Router, ProcName>>>> : () => Promise<[
         Pushable<Static<ProcInput<Router, ProcName>>>,
-        AsyncIterableIterator<Static<ProcOutput<Router, ProcName>>>,
+        AsyncIter<Result<Static<ProcOutput<Router, ProcName>>, Static<ProcErrors<Router, ProcName>>>>,
         () => void
     ]>;
 };
+/**
+ * Defines a type that represents a client for a server with a set of services.
+ * @template Srv - The type of the server.
+ */
 export type ServerClient<Srv extends Server<Record<string, AnyService>>> = {
     [SvcName in keyof Srv['services']]: ServiceClient<Srv['services'][SvcName]>;
 };
+/**
+ * Creates a client for a given server using the provided transport.
+ * Note that the client only needs the type of the server, not the actual
+ * server definition itself.
+ *
+ * This relies on a proxy to dynamically create the client, so the client
+ * will be typed as if it were the actual server with the appropriate services
+ * and procedures.
+ *
+ * @template Srv - The type of the server.
+ * @param {Transport} transport - The transport to use for communication.
+ * @returns The client for the server.
+ */
 export declare const createClient: <Srv extends Server<Record<string, AnyService>>>(transport: Transport) => ServerClient<Srv>;
 export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/router/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../router/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EACL,UAAU,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,QAAQ,EACT,MAAM,WAAW,CAAC;AAEnB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAMlC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC,KAAK,SAAS,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAE5C;;;;GAIG;AACH,KAAK,aAAa,CAAC,MAAM,SAAS,UAAU,IAAI;KAC7C,QAAQ,IAAI,MAAM,MAAM,CAAC,YAAY,CAAC,GAAG,QAAQ,CAChD,MAAM,EACN,QAAQ,CACT,SAAS,KAAK,GAEX,CACE,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,KACvC,OAAO,CACV,MAAM,CACJ,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,EACpC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CACrC,CACF,GAED,MAAM,OAAO,CACX;QACE,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC7C,SAAS,CACP,MAAM,CACJ,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,EACpC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CACrC,CACF;QACD,MAAM,IAAI;KACX,CACF;CACN,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,IAAI;KACxE,OAAO,IAAI,MAAM,GAAG,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,CAAC;CAC5E,CAAC;AAgCF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,8DACZ,SAAS,sBAgFO,CAAC"}

package/dist/router/client.js

@@ -1,14 +1,17 @@
 import { pushable } from 'it-pushable';
-import { msg } from '../transport/message';
+import { msg, } from '../transport/message';
 import { waitForMessage } from '../transport';
+import { nanoid } from 'nanoid';
 const noop = () => { };
 function _createRecursiveProxy(callback, path) {
     const proxy = new Proxy(noop, {
+        // property access, recurse and add field to path
         get(_obj, key) {
             if (typeof key !== 'string')
                 return undefined;
             return _createRecursiveProxy(callback, [...path, key]);
         },
+        // hit the end, let's invoke the handler
         apply(_target, _this, args) {
             return callback({
                 path,
@@ -18,23 +21,44 @@ function _createRecursiveProxy(callback, path) {
     });
     return proxy;
 }
+/**
+ * Creates a client for a given server using the provided transport.
+ * Note that the client only needs the type of the server, not the actual
+ * server definition itself.
+ *
+ * This relies on a proxy to dynamically create the client, so the client
+ * will be typed as if it were the actual server with the appropriate services
+ * and procedures.
+ *
+ * @template Srv - The type of the server.
+ * @param {Transport} transport - The transport to use for communication.
+ * @returns The client for the server.
+ */
 export const createClient = (transport) => _createRecursiveProxy(async (opts) => {
     const [serviceName, procName] = [...opts.path];
     const [input] = opts.args;
+    const streamId = nanoid();
+    function belongsToSameStream(msg) {
+        return (msg.streamId === streamId &&
+            msg.serviceName === serviceName &&
+            msg.procedureName === procName);
+    }
     if (input === undefined) {
-        // stream case
+        // stream case (stream methods are called with zero arguments)
         const inputStream = pushable({ objectMode: true });
         const outputStream = pushable({ objectMode: true });
         // input -> transport
         // this gets cleaned up on i.end() which is called by closeHandler
         (async () => {
             for await (const rawIn of inputStream) {
-                transport.send(msg(transport.clientId, 'SERVER', serviceName, procName, rawIn));
+                const m = msg(transport.clientId, 'SERVER', serviceName, procName, streamId, rawIn);
+                m.controlFlags |= 2 /* ControlFlags.StreamOpenBit */;
+                transport.send(m);
             }
         })();
         // transport -> output
         const listener = (msg) => {
-            if (msg.serviceName === serviceName && msg.procedureName === procName) {
+            if (belongsToSameStream(msg)) {
                 outputStream.push(msg.payload);
             }
         };
@@ -42,13 +66,20 @@ export const createClient = (transport) => _createRecursiveProxy(async (opts) =>
         const closeHandler = () => {
             inputStream.end();
             outputStream.end();
+            const closeMessage = msg(transport.clientId, 'SERVER', serviceName, procName, streamId, {});
+            closeMessage.controlFlags |= 4 /* ControlFlags.StreamClosedBit */;
+            transport.send(closeMessage);
             transport.removeMessageListener(listener);
         };
         return [inputStream, outputStream, closeHandler];
     }
     else {
         // rpc case
-        const id = transport.send(msg(transport.clientId, 'SERVER', serviceName, procName, input));
-        return waitForMessage(transport, (msg) => msg.replyTo === id);
+        const m = msg(transport.clientId, 'SERVER', serviceName, procName, streamId, input);
+        // rpc is a stream open + close
+        m.controlFlags |=
+            2 /* ControlFlags.StreamOpenBit */ | 4 /* ControlFlags.StreamClosedBit */;
+        transport.send(m);
+        return waitForMessage(transport, belongsToSameStream);
     }
 }, []);

package/dist/router/context.d.ts

@@ -9,6 +9,7 @@
  * You should use declaration merging to extend this interface
  * with whatever you need. For example, if you need to access
  * a database, you could do:
+ *
  * ```ts
  * declare module '@replit/river' {
  *   interface ServiceContext {
@@ -26,3 +27,4 @@ export interface ServiceContext {
 export type ServiceContextWithState<State extends object | unknown> = ServiceContext & {
     state: State;
 };
+//# sourceMappingURL=context.d.ts.map

package/dist/router/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../router/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,CAAC,KAAK,SAAS,MAAM,GAAG,OAAO,IAChE,cAAc,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC"}

package/dist/router/index.d.ts

@@ -5,3 +5,4 @@ export type { ServerClient } from './client';
 export { createServer } from './server';
 export type { Server } from './server';
 export type { ServiceContext, ServiceContextWithState } from './context';
+//# sourceMappingURL=index.d.ts.map

package/dist/router/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../router/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7D,YAAY,EACV,aAAa,EACb,WAAW,EACX,OAAO,EACP,WAAW,EACX,SAAS,EACT,UAAU,EACV,QAAQ,EACR,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC"}

package/dist/router/result.d.ts

@@ -0,0 +1,25 @@
+import { TLiteralString, TNever, TObject, TSchema, TString, TUnion } from '@sinclair/typebox';
+export type RiverErrorSchema = TObject<{
+    code: TLiteralString;
+    message: TLiteralString | TString;
+}> | TObject<{
+    code: TLiteralString;
+    message: TLiteralString | TString;
+    extras: TSchema;
+}>;
+export type RiverError = TUnion<RiverErrorSchema[]> | RiverErrorSchema | TNever;
+export declare const UNCAUGHT_ERROR = "UNCAUGHT_ERROR";
+export declare const RiverUncaughtSchema: TObject<{
+    code: import("@sinclair/typebox").TLiteral<"UNCAUGHT_ERROR">;
+    message: TString;
+}>;
+export type Result<T, E> = {
+    ok: true;
+    payload: T;
+} | {
+    ok: false;
+    payload: E;
+};
+export declare function Ok<T, E>(payload: T): Result<T, E>;
+export declare function Err<T, E>(error: E): Result<T, E>;
+//# sourceMappingURL=result.d.ts.map

package/dist/router/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../router/result.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,MAAM,EACN,OAAO,EACP,OAAO,EACP,OAAO,EACP,MAAM,EAEP,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,gBAAgB,GACxB,OAAO,CAAC;IACN,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC;CACnC,CAAC,GACF,OAAO,CAAC;IACN,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC;IAClC,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC,CAAC;AACP,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC,GAAG,gBAAgB,GAAG,MAAM,CAAC;AAEhF,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,mBAAmB;;;EAG9B,CAAC;AAEH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IACnB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,CAAC,CAAC;CACZ,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,CAAC,CAAC;CACZ,CAAC;AAEN,wBAAgB,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAKjD;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAKhD"}

package/dist/router/result.js

@@ -0,0 +1,18 @@
+import { Type, } from '@sinclair/typebox';
+export const UNCAUGHT_ERROR = 'UNCAUGHT_ERROR';
+export const RiverUncaughtSchema = Type.Object({
+    code: Type.Literal(UNCAUGHT_ERROR),
+    message: Type.String(),
+});
+export function Ok(payload) {
+    return {
+        ok: true,
+        payload,
+    };
+}
+export function Err(error) {
+    return {
+        ok: false,
+        payload: error,
+    };
+}

package/dist/router/server.d.ts

@@ -1,8 +1,21 @@
 import { Transport } from '../transport/types';
 import { AnyService } from './builder';
 import { ServiceContext } from './context';
+/**
+ * Represents a server with a set of services. Use {@link createServer} to create it.
+ * @template Services - The type of services provided by the server.
+ */
 export interface Server<Services> {
     services: Services;
     close(): Promise<void>;
 }
+/**
+ * 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 declare function createServer<Services extends Record<string, AnyService>>(transport: Transport, services: Services, extendedContext?: Omit<ServiceContext, 'state'>): Promise<Server<Services>>;
+//# sourceMappingURL=server.d.ts.map

package/dist/router/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../router/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAgB,UAAU,EAAE,MAAM,WAAW,CAAC;AAUrD,OAAO,EAAE,cAAc,EAA2B,MAAM,WAAW,CAAC;AAWpE;;;GAGG;AACH,MAAM,WAAW,MAAM,CAAC,QAAQ;IAC9B,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAWD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EAC5E,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,QAAQ,EAClB,eAAe,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,GAC9C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAoJ3B"}