@replit/river 0.15.7 → 0.16.1

package/README.md

@@ -67,20 +67,21 @@ npm i ws isomorphic-ws
 
 ### A basic router
 
-First, we create a service using the `ServiceBuilder`
+First, we create a service using `ServiceSchema`:
 
 ```ts
-import { ServiceBuilder, Ok, buildServiceDefs } from '@replit/river';
+import { ServicaSchema, Procedure, Ok } from '@replit/river';
 import { Type } from '@sinclair/typebox';
 
-export const ExampleServiceConstructor = () =>
-  ServiceBuilder.create('example')
+export const ExampleService = ServiceSchema.define(
+  // configuration
+  {
     // initializer for shared state
-    .initialState({
-      count: 0,
-    })
-    .defineProcedure('add', {
-      type: 'rpc',
+    initializeState: () => ({ count: 0 }),
+  },
+  // procedures
+  {
+    add: Procedure.rpc({
       input: Type.Object({ n: Type.Number() }),
       output: Type.Object({ result: Type.Number() }),
       errors: Type.Never(),
@@ -90,11 +91,9 @@ export const ExampleServiceConstructor = () =>
         ctx.state.count += n;
         return Ok({ result: ctx.state.count });
       },
-    })
-    .finalize();
-
-// expore a listing of all the services that we have
-export const serviceDefs = buildServiceDefs([ExampleServiceConstructor()]);
+    }),
+  },
+);
 ```
 
 Then, we create the server:
@@ -111,7 +110,10 @@ const port = 3000;
 const wss = new WebSocketServer({ server: httpServer });
 const transport = new WebSocketServerTransport(wss, 'SERVER');
 
-export const server = createServer(transport, serviceDefs);
+export const server = createServer(transport, {
+  example: ExampleService,
+});
+
 export type ServiceSurface = typeof server;
 
 httpServer.listen(port);

package/dist/{chunk-KWXQLQAF.js → chunk-Q6WPGM3K.js}

@@ -8,93 +8,235 @@ import {
   log
 } from "./chunk-H4BYJELI.js";
 
-// router/builder.ts
+// router/services.ts
 import { Type } from "@sinclair/typebox";
-function serializeService(s) {
-  return {
-    name: s.name,
-    state: s.state,
-    procedures: Object.fromEntries(
-      Object.entries(s.procedures).map(([procName, procDef]) => [
-        procName,
-        {
-          input: Type.Strict(procDef.input),
-          output: Type.Strict(procDef.output),
-          // Only add the `errors` field if it is non-never.
-          ..."errors" in procDef ? {
-            errors: Type.Strict(procDef.errors)
-          } : {},
-          type: procDef.type,
-          // Only add the `init` field if the type declares it.
-          ..."init" in procDef ? {
-            init: Type.Strict(procDef.init)
-          } : {}
-        }
-      ])
-    )
-  };
-}
-var ServiceBuilder = class _ServiceBuilder {
-  schema;
-  constructor(schema) {
-    this.schema = schema;
-  }
+var ServiceSchema = class _ServiceSchema {
   /**
-   * Finalizes the schema for the service.
+   * Factory function for creating a fresh state.
    */
-  finalize() {
-    return Object.freeze(this.schema);
+  initializeState;
+  /**
+   * The procedures for this service.
+   */
+  procedures;
+  /**
+   * @param config - The configuration for this service.
+   * @param procedures - The procedures for this service.
+   */
+  constructor(config, procedures) {
+    this.initializeState = config.initializeState;
+    this.procedures = procedures;
   }
   /**
-   * 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.
+   * Creates a {@link ServiceScaffold}, which can be used to define procedures
+   * that can then be merged into a {@link ServiceSchema}, via the scaffold's
+   * `finalize` method.
+   *
+   * There are two patterns that work well with this method. The first is using
+   * it to separate the definition of procedures from the definition of the
+   * service's configuration:
+   * ```ts
+   * const MyServiceScaffold = ServiceSchema.scaffold({
+   *   initializeState: () => ({ count: 0 }),
+   * });
+   *
+   * const incrementProcedures = MyServiceScaffold.procedures({
+   *   increment: Procedure.rpc({
+   *     input: Type.Object({ amount: Type.Number() }),
+   *     output: Type.Object({ current: Type.Number() }),
+   *     async handler(ctx, input) {
+   *       ctx.state.count += input.amount;
+   *       return Ok({ current: ctx.state.count });
+   *     }
+   *   }),
+   * })
+   *
+   * const MyService = MyServiceScaffold.finalize({
+   *   ...incrementProcedures,
+   *   // you can also directly define procedures here
+   * });
+   * ```
+   * This might be really handy if you have a very large service and you're
+   * wanting to split it over multiple files. You can define the scaffold
+   * in one file, and then import that scaffold in other files where you
+   * define procedures - and then finally import the scaffolds and your
+   * procedure objects in a final file where you finalize the scaffold into
+   * a service schema.
+   *
+   * The other way is to use it like in a builder pattern:
+   * ```ts
+   * const MyService = ServiceSchema
+   *   .scaffold({ initializeState: () => ({ count: 0 }) })
+   *   .finalize({
+   *     increment: Procedure.rpc({
+   *       input: Type.Object({ amount: Type.Number() }),
+   *       output: Type.Object({ current: Type.Number() }),
+   *       async handler(ctx, input) {
+   *         ctx.state.count += input.amount;
+   *         return Ok({ current: ctx.state.count });
+   *       }
+   *     }),
+   *   })
+   * ```
+   * Depending on your preferences, this may be a more appealing way to define
+   * a schema versus using the {@link ServiceSchema.define} method.
    */
-  initialState(state) {
-    return new _ServiceBuilder({
-      ...this.schema,
-      state
-    });
+  static scaffold(config) {
+    return new ServiceScaffold(config);
+  }
+  // actual implementation
+  static define(configOrProcedures, maybeProcedures) {
+    let config;
+    let procedures;
+    if ("initializeState" in configOrProcedures && typeof configOrProcedures.initializeState === "function") {
+      if (!maybeProcedures) {
+        throw new Error("Expected procedures to be defined");
+      }
+      config = configOrProcedures;
+      procedures = maybeProcedures;
+    } else {
+      config = { initializeState: () => ({}) };
+      procedures = configOrProcedures;
+    }
+    return new _ServiceSchema(config, procedures);
   }
   /**
-   * Defines a new procedure for the service.
-   * @param {ProcName} procName The name of the procedure.
-   * @param {Procedure<T['state'], Ty, I, O, E, Init>} 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, E, Init>; }; }>} A new ServiceBuilder instance with the updated schema.
+   * Serializes this schema's procedures into a plain object that is JSON compatible.
    */
-  defineProcedure(procName, procDef) {
-    const newProcedure = { [procName]: procDef };
-    const procedures = {
-      ...this.schema.procedures,
-      ...newProcedure
+  serialize() {
+    return {
+      procedures: Object.fromEntries(
+        Object.entries(this.procedures).map(([procName, procDef]) => [
+          procName,
+          {
+            input: Type.Strict(procDef.input),
+            output: Type.Strict(procDef.output),
+            // Only add the `errors` field if it is non-never.
+            ..."errors" in procDef ? {
+              errors: Type.Strict(procDef.errors)
+            } : {},
+            type: procDef.type,
+            // Only add the `init` field if the type declares it.
+            ..."init" in procDef ? {
+              init: Type.Strict(procDef.init)
+            } : {}
+          }
+        ])
+      )
     };
-    return new _ServiceBuilder({
-      ...this.schema,
-      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.
+   * Instantiates this schema into a {@link Service} object.
+   *
+   * You probably don't need this, usually the River server will handle this
+   * for you.
    */
-  static create(name) {
-    return new _ServiceBuilder({
-      name,
-      state: {},
-      procedures: {}
+  instantiate() {
+    return Object.freeze({
+      state: this.initializeState(),
+      procedures: this.procedures
     });
   }
 };
+var ServiceScaffold = class {
+  /**
+   * The configuration for this service.
+   */
+  config;
+  /**
+   * @param config - The configuration for this service.
+   */
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Define procedures for this service. Use the {@link Procedure} constructors
+   * to create them. This returns the procedures object, which can then be
+   * passed to {@link ServiceSchema.finalize} to create a {@link ServiceSchema}.
+   *
+   * @example
+   * ```
+   * const myProcedures = MyServiceScaffold.procedures({
+   *   myRPC: Procedure.rpc({
+   *     // ...
+   *   }),
+   * });
+   *
+   * const MyService = MyServiceScaffold.finalize({
+   *   ...myProcedures,
+   * });
+   * ```
+   *
+   * @param procedures - The procedures for this service.
+   */
+  procedures(procedures) {
+    return procedures;
+  }
+  /**
+   * Finalizes the scaffold into a {@link ServiceSchema}. This is where you
+   * provide the service's procedures and get a {@link ServiceSchema} in return.
+   *
+   * You can directly define procedures here, or you can define them separately
+   * with the {@link ServiceScaffold.procedures} method, and then pass them here.
+   *
+   * @example
+   * ```
+   * const MyService = MyServiceScaffold.finalize({
+   *  myRPC: Procedure.rpc({
+   *   // ...
+   *  }),
+   *  // e.g. from the procedures method
+   *  ...myOtherProcedures,
+   * });
+   * ```
+   */
+  finalize(procedures) {
+    return ServiceSchema.define(this.config, procedures);
+  }
+};
 
-// router/defs.ts
-function buildServiceDefs(services) {
-  return services.reduce((acc, service) => {
-    acc[service.name] = service;
-    return acc;
-  }, {});
+// router/procedures.ts
+import { Type as Type2 } from "@sinclair/typebox";
+function rpc({
+  input,
+  output,
+  errors = Type2.Never(),
+  handler
+}) {
+  return { type: "rpc", input, output, errors, handler };
+}
+function upload({
+  init,
+  input,
+  output,
+  errors = Type2.Never(),
+  handler
+}) {
+  return init !== void 0 && init !== null ? { type: "upload", init, input, output, errors, handler } : { type: "upload", input, output, errors, handler };
+}
+function subscription({
+  input,
+  output,
+  errors = Type2.Never(),
+  handler
+}) {
+  return { type: "subscription", input, output, errors, handler };
 }
+function stream({
+  init,
+  input,
+  output,
+  errors = Type2.Never(),
+  handler
+}) {
+  return init !== void 0 && init !== null ? { type: "stream", init, input, output, errors, handler } : { type: "stream", input, output, errors, handler };
+}
+var Procedure = {
+  rpc,
+  upload,
+  subscription,
+  stream
+};
 
 // node_modules/p-defer/index.js
 function pDefer() {
@@ -383,16 +525,16 @@ import { nanoid } from "nanoid";
 
 // router/result.ts
 import {
-  Type as Type2
+  Type as Type3
 } from "@sinclair/typebox";
 var UNCAUGHT_ERROR = "UNCAUGHT_ERROR";
 var UNEXPECTED_DISCONNECT = "UNEXPECTED_DISCONNECT";
-var RiverUncaughtSchema = Type2.Object({
-  code: Type2.Union([
-    Type2.Literal(UNCAUGHT_ERROR),
-    Type2.Literal(UNEXPECTED_DISCONNECT)
+var RiverUncaughtSchema = Type3.Object({
+  code: Type3.Union([
+    Type3.Literal(UNCAUGHT_ERROR),
+    Type3.Literal(UNEXPECTED_DISCONNECT)
   ]),
-  message: Type2.String()
+  message: Type3.String()
 });
 function Ok(payload) {
   return {
@@ -716,16 +858,19 @@ var RiverServer = class {
   clientStreams;
   disconnectedSessions;
   constructor(transport, services, extendedContext) {
-    this.transport = transport;
-    this.services = services;
+    const instances = {};
+    this.services = instances;
     this.contextMap = /* @__PURE__ */ new Map();
-    this.disconnectedSessions = /* @__PURE__ */ new Set();
-    for (const service of Object.values(services)) {
-      this.contextMap.set(service, {
+    for (const [name, service] of Object.entries(services)) {
+      const instance = service.instantiate();
+      instances[name] = instance;
+      this.contextMap.set(instance, {
         ...extendedContext,
-        state: service.state
+        state: instance.state
       });
     }
+    this.transport = transport;
+    this.disconnectedSessions = /* @__PURE__ */ new Set();
     this.streamMap = /* @__PURE__ */ new Map();
     this.clientStreams = /* @__PURE__ */ new Map();
     this.transport.addEventListener("message", this.onMessage);
@@ -794,7 +939,7 @@ var RiverServer = class {
       return;
     }
     const service = this.services[message.serviceName];
-    const serviceContext = this.getContext(service);
+    const serviceContext = this.getContext(service, message.serviceName);
     if (!(message.procedureName in service.procedures)) {
       log?.warn(
         `${this.transport.clientId} -- couldn't find a matching procedure for ${message.serviceName}.${message.procedureName}`
@@ -1004,24 +1149,24 @@ var RiverServer = class {
       }
     }
   }
-  getContext(service) {
+  getContext(service, name) {
     const context = this.contextMap.get(service);
     if (!context) {
-      const err = `${this.transport.clientId} -- no context found for ${service.name}`;
+      const err = `${this.transport.clientId} -- no context found for ${name}`;
       log?.error(err);
       throw new Error(err);
     }
     return context;
   }
   cleanupStream = async (id) => {
-    const stream = this.streamMap.get(id);
-    if (!stream) {
+    const stream2 = this.streamMap.get(id);
+    if (!stream2) {
       return;
     }
-    stream.incoming.end();
-    await stream.promises.inputHandler;
-    stream.outgoing.end();
-    await stream.promises.outputHandler;
+    stream2.incoming.end();
+    await stream2.promises.inputHandler;
+    stream2.outgoing.end();
+    await stream2.promises.outputHandler;
     this.streamMap.delete(id);
   };
 };
@@ -1030,9 +1175,8 @@ function createServer(transport, services, extendedContext) {
 }
 
 export {
-  serializeService,
-  ServiceBuilder,
-  buildServiceDefs,
+  ServiceSchema,
+  Procedure,
   pushable,
   UNCAUGHT_ERROR,
   RiverUncaughtSchema,