@replit/river 0.11.0 → 0.12.0

package/README.md

@@ -1,4 +1,4 @@
-# river - Streaming Remote Procedure Calls
+# river - Long-lived Streaming Remote Procedure Calls
 
 It's like tRPC/gRPC but with
 
@@ -7,6 +7,7 @@ It's like tRPC/gRPC but with
 - service multiplexing
 - result types and error handling
 - snappy DX (no code-generation)
+- transparent reconnect support for long-lived sessions
 - over any transport (WebSockets, stdio, Unix Domain Socket out of the box)
 
 ## Installation
@@ -32,6 +33,8 @@ npm i ws isomorphic-ws
   - `subscription` whose handler has a signature of `Input -> Pushable<Result<Output, Error>>`.
   - `stream` whose handler has a signature of `AsyncIterableIterator<Input> -> Pushable<Result<Output, Error>>`.
 - Transport: manages the lifecycle (creation/deletion) of connections and multiplexing read/writes from clients. Both the client and the server must be passed in a subclass of `Transport` to work.
+  - Connection: the actual raw underlying transport connection
+  - Session: a higher-level abstraction that operates over the span of potentially multiple transport-level connections
 - Codec: encodes messages between clients/servers before the transport sends it across the wire.
 
 ### A basic router
@@ -110,6 +113,8 @@ if (result.ok) {
 }
 ```
 
+### Logging
+
 To add logging,
 
 ```ts
@@ -119,7 +124,20 @@ bindLogger(console.log);
 setLevel('info');
 ```
 
-To listen for connection status changes,
+### Connection Status
+
+River define two types of reconnects:
+
+1. Transparent reconnects: we lost the connection temporarily and reconnected without losing any messages. To the application level, nothing happened.
+2. Hard reconnect: we've lost all server state and the client should setup the world again.
+
+We can listen for transparent reconnects via the `connectionStatus` events but realistically
+no applications should need to listen for this unless it is for debug purposes. Hard reconnects
+are signalled via `sessionStatus` events.
+
+If your application is stateful on either the server or the client, the service consumer _should_
+wrap all the client-side setup with `transport.addEventListener('sessionStatus', (evt) => ...)` to
+do appropriate setup and teardown.
 
 ```ts
 transport.addEventListener('connectionStatus', (evt) => {
@@ -129,13 +147,15 @@ transport.addEventListener('connectionStatus', (evt) => {
     // do something else
   }
 });
-```
 
-> [!note] WebSocket connection behaviour
-> WebSocket is an idle protocol. This means that when the underlying connection drops, the WebSocket
-> may still think it is still connected (e.g. turning off the network via devtools).
-> You can use `window.addEventListener('online', ...);` and `window.addEventListener('offline', ...);` to
-> know if you need to recreate the transport.
+transport.addEventListener('sessionStatus', (evt) => {
+  if (evt.status === 'connect') {
+    // do something
+  } else if (evt.status === 'disconnect') {
+    // do something else
+  }
+});
+```
 
 ### Further examples
 

package/dist/{builder-1f26296b.d.ts → builder-c593de11.d.ts}

@@ -22,25 +22,24 @@ import { Pushable } from 'it-pushable';
  * ```
  */
 interface ServiceContext {
-    state: object | unknown;
 }
 /**
  * The {@link ServiceContext} with state. This is what is passed to procedures.
  */
-type ServiceContextWithState<State extends object | unknown> = ServiceContext & {
+type ServiceContextWithState<State> = ServiceContext & {
     state: State;
 };
 
 type TLiteralString = TLiteral<string>;
 type RiverErrorSchema = TObject<{
-    code: TLiteralString | TUnion<TLiteralString[]>;
+    code: TLiteralString | TUnion<Array<TLiteralString>>;
     message: TLiteralString | TString;
 }> | TObject<{
-    code: TLiteralString | TUnion<TLiteralString[]>;
+    code: TLiteralString | TUnion<Array<TLiteralString>>;
     message: TLiteralString | TString;
     extras: TSchema;
 }>;
-type RiverError = TUnion<RiverErrorSchema[]> | RiverErrorSchema | TNever;
+type RiverError = TUnion<Array<RiverErrorSchema>> | RiverErrorSchema | TNever;
 declare const UNCAUGHT_ERROR = "UNCAUGHT_ERROR";
 declare const RiverUncaughtSchema: TObject<{
     code: TUnion<[TLiteral<"UNCAUGHT_ERROR">, TLiteral<"UNEXPECTED_DISCONNECT">]>;
@@ -80,7 +79,7 @@ interface Service<Name extends string, State extends object, Procs extends ProcL
     state: State;
     procedures: Procs;
 }
-type AnyService = Service<string, object, any>;
+type AnyService = Service<string, object, ProcListing>;
 /**
  * Serializes a service object into its corresponding JSON Schema Draft 7 type.
  * @param {AnyService} s - The service object to serialize.
@@ -99,14 +98,16 @@ type ProcHandler<S extends AnyService, ProcName extends keyof S['procedures']> =
  * @template ProcName - The name of the procedure.
  */
 type ProcHasInit<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName] extends {
-    init: any;
+    init: TObject;
 } ? true : false;
 /**
  * Helper to get the type definition for the procedure init type of a service.
  * @template S - The service.
  * @template ProcName - The name of the procedure.
  */
-type ProcInit<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['init'];
+type ProcInit<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName] extends {
+    init: TObject;
+} ? S['procedures'][ProcName]['init'] : never;
 /**
  * Helper to get the type definition for the procedure input of a service.
  * @template S - The service.
@@ -131,7 +132,7 @@ type ProcErrors<S extends AnyService, ProcName extends keyof S['procedures']> =
  * @template ProcName - The name of the procedure.
  */
 type ProcType<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['type'];
-type PayloadType = TObject | TUnion<TObject[]>;
+type PayloadType = TObject | TUnion<Array<TObject>>;
 /**
  * Defines a Procedure type that can be either an RPC or a stream procedure.
  * @template State - The TypeBox schema of the state object.
@@ -140,7 +141,7 @@ type PayloadType = TObject | TUnion<TObject[]>;
  * @template O - The TypeBox schema of the output object.
  * @template Init - The TypeBox schema of the input initialization object.
  */
-type Procedure<State extends object | unknown, Ty extends ValidProcType, I extends PayloadType, O extends PayloadType, E extends RiverError, Init extends PayloadType | null = null> = Ty extends 'rpc' ? Init extends null ? {
+type Procedure<State, Ty extends ValidProcType, I extends PayloadType, O extends PayloadType, E extends RiverError, Init extends PayloadType | null = null> = Ty extends 'rpc' ? Init extends null ? {
     input: I;
     output: O;
     errors: E;
@@ -224,9 +225,9 @@ declare class ServiceBuilder<T extends Service<string, object, ProcListing>> {
      */
     static create<Name extends string>(name: Name): ServiceBuilder<{
         name: Name;
-        state: {};
-        procedures: {};
+        state: object;
+        procedures: ProcListing;
     }>;
 }
 
-export { AnyService as A, Err as E, Ok as O, PayloadType as P, RiverError as R, ServiceContext as S, UNCAUGHT_ERROR as U, ValidProcType as V, Procedure as a, Result as b, RiverUncaughtSchema as c, AnyProcedure as d, ProcType as e, ProcInput as f, ProcOutput as g, ProcErrors as h, ProcHasInit as i, ProcInit as j, ServiceBuilder as k, ProcListing as l, Service as m, ProcHandler as n, ServiceContextWithState as o, RiverErrorSchema as p, serializeService as s };
+export { AnyService as A, Err as E, Ok as O, PayloadType as P, RiverError as R, ServiceContext as S, UNCAUGHT_ERROR as U, ValidProcType as V, Procedure as a, Result as b, RiverUncaughtSchema as c, ProcType as d, ProcInput as e, ProcOutput as f, ProcErrors as g, ProcHasInit as h, ProcInit as i, ServiceBuilder as j, ProcListing as k, Service as l, ProcHandler as m, ServiceContextWithState as n, RiverErrorSchema as o, serializeService as s };