@replit/river 0.15.7 → 0.16.1

package/dist/router/index.cjs

@@ -22,103 +22,244 @@ var router_exports = {};
 __export(router_exports, {
   Err: () => Err,
   Ok: () => Ok,
+  Procedure: () => Procedure,
   RiverUncaughtSchema: () => RiverUncaughtSchema,
-  ServiceBuilder: () => ServiceBuilder,
+  ServiceSchema: () => ServiceSchema,
   UNCAUGHT_ERROR: () => UNCAUGHT_ERROR,
-  buildServiceDefs: () => buildServiceDefs,
   createClient: () => createClient,
-  createServer: () => createServer,
-  serializeService: () => serializeService
+  createServer: () => createServer
 });
 module.exports = __toCommonJS(router_exports);
 
-// router/builder.ts
+// router/services.ts
 var import_typebox = require("@sinclair/typebox");
-function serializeService(s) {
-  return {
-    name: s.name,
-    state: s.state,
-    procedures: Object.fromEntries(
-      Object.entries(s.procedures).map(([procName, procDef]) => [
-        procName,
-        {
-          input: import_typebox.Type.Strict(procDef.input),
-          output: import_typebox.Type.Strict(procDef.output),
-          // Only add the `errors` field if it is non-never.
-          ..."errors" in procDef ? {
-            errors: import_typebox.Type.Strict(procDef.errors)
-          } : {},
-          type: procDef.type,
-          // Only add the `init` field if the type declares it.
-          ..."init" in procDef ? {
-            init: import_typebox.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: import_typebox.Type.Strict(procDef.input),
+            output: import_typebox.Type.Strict(procDef.output),
+            // Only add the `errors` field if it is non-never.
+            ..."errors" in procDef ? {
+              errors: import_typebox.Type.Strict(procDef.errors)
+            } : {},
+            type: procDef.type,
+            // Only add the `init` field if the type declares it.
+            ..."init" in procDef ? {
+              init: import_typebox.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
+var import_typebox2 = require("@sinclair/typebox");
+function rpc({
+  input,
+  output,
+  errors = import_typebox2.Type.Never(),
+  handler
+}) {
+  return { type: "rpc", input, output, errors, handler };
+}
+function upload({
+  init,
+  input,
+  output,
+  errors = import_typebox2.Type.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 = import_typebox2.Type.Never(),
+  handler
+}) {
+  return { type: "subscription", input, output, errors, handler };
+}
+function stream({
+  init,
+  input,
+  output,
+  errors = import_typebox2.Type.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() {
@@ -403,52 +544,52 @@ function _pushable(getNext, options) {
 }
 
 // transport/message.ts
-var import_typebox2 = require("@sinclair/typebox");
+var import_typebox3 = require("@sinclair/typebox");
 var import_nanoid = require("nanoid");
-var TransportMessageSchema = (t) => import_typebox2.Type.Object({
-  id: import_typebox2.Type.String(),
-  from: import_typebox2.Type.String(),
-  to: import_typebox2.Type.String(),
-  seq: import_typebox2.Type.Integer(),
-  ack: import_typebox2.Type.Integer(),
-  serviceName: import_typebox2.Type.Optional(import_typebox2.Type.String()),
-  procedureName: import_typebox2.Type.Optional(import_typebox2.Type.String()),
-  streamId: import_typebox2.Type.String(),
-  controlFlags: import_typebox2.Type.Integer(),
+var TransportMessageSchema = (t) => import_typebox3.Type.Object({
+  id: import_typebox3.Type.String(),
+  from: import_typebox3.Type.String(),
+  to: import_typebox3.Type.String(),
+  seq: import_typebox3.Type.Integer(),
+  ack: import_typebox3.Type.Integer(),
+  serviceName: import_typebox3.Type.Optional(import_typebox3.Type.String()),
+  procedureName: import_typebox3.Type.Optional(import_typebox3.Type.String()),
+  streamId: import_typebox3.Type.String(),
+  controlFlags: import_typebox3.Type.Integer(),
   payload: t
 });
-var ControlMessageAckSchema = import_typebox2.Type.Object({
-  type: import_typebox2.Type.Literal("ACK")
+var ControlMessageAckSchema = import_typebox3.Type.Object({
+  type: import_typebox3.Type.Literal("ACK")
 });
-var ControlMessageCloseSchema = import_typebox2.Type.Object({
-  type: import_typebox2.Type.Literal("CLOSE")
+var ControlMessageCloseSchema = import_typebox3.Type.Object({
+  type: import_typebox3.Type.Literal("CLOSE")
 });
-var ControlMessageHandshakeRequestSchema = import_typebox2.Type.Object({
-  type: import_typebox2.Type.Literal("HANDSHAKE_REQ"),
-  protocolVersion: import_typebox2.Type.String(),
-  instanceId: import_typebox2.Type.String()
+var ControlMessageHandshakeRequestSchema = import_typebox3.Type.Object({
+  type: import_typebox3.Type.Literal("HANDSHAKE_REQ"),
+  protocolVersion: import_typebox3.Type.String(),
+  instanceId: import_typebox3.Type.String()
 });
-var ControlMessageHandshakeResponseSchema = import_typebox2.Type.Object({
-  type: import_typebox2.Type.Literal("HANDSHAKE_RESP"),
-  status: import_typebox2.Type.Union([
-    import_typebox2.Type.Object({
-      ok: import_typebox2.Type.Literal(true),
-      instanceId: import_typebox2.Type.String()
+var ControlMessageHandshakeResponseSchema = import_typebox3.Type.Object({
+  type: import_typebox3.Type.Literal("HANDSHAKE_RESP"),
+  status: import_typebox3.Type.Union([
+    import_typebox3.Type.Object({
+      ok: import_typebox3.Type.Literal(true),
+      instanceId: import_typebox3.Type.String()
     }),
-    import_typebox2.Type.Object({
-      ok: import_typebox2.Type.Literal(false),
-      reason: import_typebox2.Type.String()
+    import_typebox3.Type.Object({
+      ok: import_typebox3.Type.Literal(false),
+      reason: import_typebox3.Type.String()
     })
   ])
 });
-var ControlMessagePayloadSchema = import_typebox2.Type.Union([
+var ControlMessagePayloadSchema = import_typebox3.Type.Union([
   ControlMessageCloseSchema,
   ControlMessageAckSchema,
   ControlMessageHandshakeRequestSchema,
   ControlMessageHandshakeResponseSchema
 ]);
 var OpaqueTransportMessageSchema = TransportMessageSchema(
-  import_typebox2.Type.Unknown()
+  import_typebox3.Type.Unknown()
 );
 function isStreamOpen(controlFlag) {
   return (
@@ -467,15 +608,15 @@ function isStreamClose(controlFlag) {
 var import_nanoid2 = require("nanoid");
 
 // router/result.ts
-var import_typebox3 = require("@sinclair/typebox");
+var import_typebox4 = require("@sinclair/typebox");
 var UNCAUGHT_ERROR = "UNCAUGHT_ERROR";
 var UNEXPECTED_DISCONNECT = "UNEXPECTED_DISCONNECT";
-var RiverUncaughtSchema = import_typebox3.Type.Object({
-  code: import_typebox3.Type.Union([
-    import_typebox3.Type.Literal(UNCAUGHT_ERROR),
-    import_typebox3.Type.Literal(UNEXPECTED_DISCONNECT)
+var RiverUncaughtSchema = import_typebox4.Type.Object({
+  code: import_typebox4.Type.Union([
+    import_typebox4.Type.Literal(UNCAUGHT_ERROR),
+    import_typebox4.Type.Literal(UNEXPECTED_DISCONNECT)
   ]),
-  message: import_typebox3.Type.String()
+  message: import_typebox4.Type.String()
 });
 function Ok(payload) {
   return {
@@ -812,16 +953,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);
@@ -890,7 +1034,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}`
@@ -1100,24 +1244,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);
   };
 };
@@ -1128,11 +1272,10 @@ function createServer(transport, services, extendedContext) {
 0 && (module.exports = {
   Err,
   Ok,
+  Procedure,
   RiverUncaughtSchema,
-  ServiceBuilder,
+  ServiceSchema,
   UNCAUGHT_ERROR,
-  buildServiceDefs,
   createClient,
-  createServer,
-  serializeService
+  createServer
 });