@replit/river - npm Package Compare versions

Comparing version 0.15.7 to 0.16.0

dist/router/index.d.ts

@@ -1,24 +0,308 @@
-import { A as AnyService, P as PayloadType, b as Result, R as RiverError, S as ServiceContext, d as ProcType, e as ProcInput, f as ProcOutput, g as ProcErrors, h as ProcHasInit, i as ProcInit } from '../builder-4d392f6c.js';
-export { E as Err, O as Ok, m as ProcHandler, k as ProcListing, a as Procedure, p as RiverErrorSchema, c as RiverUncaughtSchema, l as Service, j as ServiceBuilder, n as ServiceContextWithState, o as ServiceContextWithTransportInfo, U as UNCAUGHT_ERROR, V as ValidProcType, s as serializeService } from '../builder-4d392f6c.js';
+import { TObject, TUnion, Static } from '@sinclair/typebox';
+import { e as ProcedureMap, c as RiverUncaughtSchema, U as Unbranded, B as Branded, A as AnyProcedure, P as PayloadType, b as Result, R as RiverError, S as ServiceContext } from '../procedures-f0226890.js';
+export { E as Err, O as Ok, a as Procedure, d as ProcedureResult, f as RPCProcedure, m as RiverErrorSchema, j as ServiceContextWithState, k as ServiceContextWithTransportInfo, i as StreamProcedure, h as SubscriptionProcedure, l as UNCAUGHT_ERROR, g as UploadProcedure, V as ValidProcType } from '../procedures-f0226890.js';
 import { S as ServerTransport, C as Connection, a as ClientTransport, b as TransportClientId } from '../index-2e402bb8.js';
 import { Pushable } from 'it-pushable';
-import { Static } from '@sinclair/typebox';
 import '../types-3e5768ec.js';
 
 /**
- * Defines a type for a collection service definitions. Should be
- * build with the {@link buildServiceDefs} function.
- * @template T - An array of services.
+ * An instantiated service, probably from a {@link ServiceSchema}.
+ *
+ * You shouldn't construct these directly, use {@link ServiceSchema} instead.
  */
-type ServiceDefs<T extends Array<AnyService> = Array<AnyService>> = {
-    [K in T[number]['name']]: Extract<T[number], {
-        name: K;
-    }>;
+interface Service<State extends object, Procs extends ProcedureMap<State>> {
+    readonly state: State;
+    readonly procedures: Procs;
+}
+/**
+ * Represents any {@link Service} object.
+ */
+type AnyService = Service<object, ProcedureMap>;
+/**
+ * Represents any {@link ServiceSchema} object.
+ */
+type AnyServiceSchema = ServiceSchema<object, ProcedureMap>;
+/**
+ * A dictionary of {@link ServiceSchema}s, where the key is the service name.
+ */
+type ServiceSchemaMap = Record<string, AnyServiceSchema>;
+/**
+ * Takes a {@link ServiceSchemaMap} and returns a dictionary of instantiated
+ * services.
+ */
+type InstantiatedServiceSchemaMap<T extends ServiceSchemaMap> = {
+    [K in keyof T]: T[K] extends ServiceSchema<infer S, infer P> ? Service<S, P> : never;
 };
 /**
- * Builds service definitions based on an array of services.
- * @param services - The array of services.
- * @returns The service definitions.
+ * 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.
  */
-declare function buildServiceDefs<T extends Array<AnyService>>(services: T): ServiceDefs<T>;
+type ProcHandler<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['handler'];
+/**
+ * Helper to get whether the type definition for the procedure contains an init type.
+ * @template S - The service.
+ * @template ProcName - The name of the procedure.
+ */
+type ProcHasInit<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName] extends {
+    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] 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.
+ * @template ProcName - The name of the procedure.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+type ProcType<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['type'];
+/**
+ * A list of procedures where every procedure is "branded", as-in the procedure
+ * was created via the {@link Procedure} constructors.
+ */
+type BrandedProcedureMap<State> = Record<string, Branded<AnyProcedure<State>>>;
+/**
+ * The configuration for a service.
+ */
+interface ServiceConfiguration<State extends object> {
+    /**
+     * A factory function for creating a fresh state.
+     */
+    initializeState: () => State;
+}
+/**
+ * The schema for a {@link Service}. This is used to define a service, specifically
+ * its initial state and procedures.
+ *
+ * There are two ways to define a service:
+ * 1. the {@link ServiceSchema.define} static method, which takes a configuration and
+ *    a list of procedures directly. Use this to ergonomically define a service schema
+ *    in one go. Good for smaller services, especially if they're stateless.
+ * 2. the {@link ServiceSchema.scaffold} static method, which creates a scaffold that
+ *    can be used to define procedures separately from the configuration. Use this to
+ *    better organize your service's definition, especially if it's a large service.
+ *    You can also use it in a builder pattern to define the service in a more
+ *    fluent way.
+ *
+ * See the static methods for more information and examples.
+ *
+ * When defining procedures, use the {@link Procedure} constructors to create them.
+ */
+declare class ServiceSchema<State extends object, Procedures extends ProcedureMap<State>> {
+    /**
+     * Factory function for creating a fresh state.
+     */
+    protected readonly initializeState: () => State;
+    /**
+     * The procedures for this service.
+     */
+    readonly procedures: Procedures;
+    /**
+     * @param config - The configuration for this service.
+     * @param procedures - The procedures for this service.
+     */
+    protected constructor(config: ServiceConfiguration<State>, procedures: Procedures);
+    /**
+     * 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.
+     */
+    static scaffold<State extends object>(config: ServiceConfiguration<State>): ServiceScaffold<State>;
+    /**
+     * Creates a new {@link ServiceSchema} with the given configuration and procedures.
+     *
+     * All procedures must be created with the {@link Procedure} constructors.
+     *
+     * NOTE: There is an overload that lets you just provide the procedures alone if your
+     * service has no state.
+     *
+     * @param config - The configuration for this service.
+     * @param procedures - The procedures for this service.
+     *
+     * @example
+     * ```
+     * const service = ServiceSchema.define(
+     *   { initializeState: () => ({ count: 0 }) },
+     *   {
+     *     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 });
+     *       }
+     *     }),
+     *   },
+     * );
+     * ```
+     */
+    static define<State extends object, Procedures extends BrandedProcedureMap<State>>(config: ServiceConfiguration<State>, procedures: Procedures): ServiceSchema<State, {
+        [K in keyof Procedures]: Unbranded<Procedures[K]>;
+    }>;
+    /**
+     * Creates a new {@link ServiceSchema} with the given procedures.
+     *
+     * All procedures must be created with the {@link Procedure} constructors.
+     *
+     * NOTE: There is an overload that lets you provide configuration as well,
+     * if your service has extra configuration like a state.
+     *
+     * @param procedures - The procedures for this service.
+     *
+     * @example
+     * ```
+     * const service = ServiceSchema.define({
+     *   add: Procedure.rpc({
+     *     input: Type.Object({ a: Type.Number(), b: Type.Number() }),
+     *     output: Type.Object({ result: Type.Number() }),
+     *     async handler(ctx, input) {
+     *       return Ok({ result: input.a + input.b });
+     *     }
+     *   }),
+     * });
+     */
+    static define<Procedures extends BrandedProcedureMap<Record<string, never>>>(procedures: Procedures): ServiceSchema<Record<string, never>, {
+        [K in keyof Procedures]: Unbranded<Procedures[K]>;
+    }>;
+    /**
+     * Serializes this schema's procedures into a plain object that is JSON compatible.
+     */
+    serialize(): object;
+    /**
+     * Instantiates this schema into a {@link Service} object.
+     *
+     * You probably don't need this, usually the River server will handle this
+     * for you.
+     */
+    instantiate(): Service<State, Procedures>;
+}
+/**
+ * A scaffold for defining a service's procedures.
+ *
+ * @see {@link ServiceSchema.scaffold}
+ */
+declare class ServiceScaffold<State extends object> {
+    /**
+     * The configuration for this service.
+     */
+    protected readonly config: ServiceConfiguration<State>;
+    /**
+     * @param config - The configuration for this service.
+     */
+    constructor(config: ServiceConfiguration<State>);
+    /**
+     * 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<T extends BrandedProcedureMap<State>>(procedures: T): T;
+    /**
+     * 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<T extends BrandedProcedureMap<State>>(procedures: T): ServiceSchema<State, {
+        [K in keyof T]: Unbranded<T[K]>;
+    }>;
+}
 
@@ -29,4 +313,4 @@ /**
  */
-interface Server<Services> {
-    services: Services;
+interface Server<Services extends ServiceSchemaMap> {
+    services: InstantiatedServiceSchemaMap<Services>;
     streams: Map<string, ProcStream>;
@@ -54,3 +338,3 @@ close(): Promise<void>;
  */
-declare function createServer<Services extends ServiceDefs>(transport: ServerTransport<Connection>, services: Services, extendedContext?: Omit<ServiceContext, 'state'>): Server<Services>;
+declare function createServer<Services extends ServiceSchemaMap>(transport: ServerTransport<Connection>, services: Services, extendedContext?: Omit<ServiceContext, 'state'>): Server<Services>;
 
@@ -99,3 +383,3 @@ type AsyncIter<T> = AsyncGenerator<T, T>;
  */
-type ServerClient<Srv extends Server<ServiceDefs>> = {
+type ServerClient<Srv extends Server<ServiceSchemaMap>> = {
     [SvcName in keyof Srv['services']]: ServiceClient<Srv['services'][SvcName]>;
@@ -116,4 +400,4 @@ };
  */
-declare const createClient: <Srv extends Server<ServiceDefs>>(transport: ClientTransport<Connection>, serverId: TransportClientId, eagerlyConnect?: boolean) => ServerClient<Srv>;
+declare const createClient: <Srv extends Server<ServiceSchemaMap>>(transport: ClientTransport<Connection>, serverId: TransportClientId, eagerlyConnect?: boolean) => ServerClient<Srv>;
 
-export { PayloadType, ProcInput, ProcOutput, ProcType, Result, RiverError, Server, ServerClient, ServiceContext, ServiceDefs, buildServiceDefs, createClient, createServer };
+export { PayloadType, ProcErrors, ProcHandler, ProcInit, ProcInput, ProcOutput, ProcType, ProcedureMap, Result, RiverError, RiverUncaughtSchema, Server, ServerClient, Service, ServiceConfiguration, ServiceContext, ServiceSchema, createClient, createServer };

dist/router/index.js

 import {
   Err,
   Ok,
+  Procedure,
   RiverUncaughtSchema,
-  ServiceBuilder,
+  ServiceSchema,
   UNCAUGHT_ERROR,
-  buildServiceDefs,
   createClient,
-  createServer,
-  serializeService
-} from "../chunk-KWXQLQAF.js";
+  createServer
+} from "../chunk-Q6WPGM3K.js";
 import "../chunk-GFRAOY75.js";
@@ -17,9 +16,8 @@ import "../chunk-H4BYJELI.js";
   Ok,
+  Procedure,
   RiverUncaughtSchema,
-  ServiceBuilder,
+  ServiceSchema,
   UNCAUGHT_ERROR,
-  buildServiceDefs,
   createClient,
-  createServer,
-  serializeService
+  createServer
 };

dist/util/testHelpers.d.ts

@@ -0,1 +1,4 @@
+import { Static } from '@sinclair/typebox';
+import { P as PayloadType, R as RiverError, a as Procedure, S as ServiceContext, b as Result, c as RiverUncaughtSchema, d as ProcedureResult } from '../procedures-f0226890.js';
+import { P as PartialTransportMessage, T as Transport, C as Connection, O as OpaqueTransportMessage } from '../index-2e402bb8.js';
 import * as it_pushable from 'it-pushable';
@@ -5,5 +8,2 @@ import { C as Codec } from '../types-3e5768ec.js';
 import http from 'node:http';
-import { P as PartialTransportMessage, T as Transport, C as Connection, O as OpaqueTransportMessage } from '../index-2e402bb8.js';
-import { P as PayloadType, R as RiverError, a as Procedure, S as ServiceContext, b as Result, c as RiverUncaughtSchema } from '../builder-4d392f6c.js';
-import { Static } from '@sinclair/typebox';
 import net from 'node:net';
@@ -67,5 +67,5 @@
     };
-} | Result<Static<O>, Static<E>>>];
+} | ProcedureResult<O, E>>];
 declare const getUnixSocketPath: () => string;
 
 export { asClientRpc, asClientStream, asClientSubscription, asClientUpload, createDummyTransportMessage, createLocalWebSocketClient, createWebSocketServer, getUnixSocketPath, iterNext, onUdsServeReady, onWsServerReady, payloadToTransportMessage, testingSessionOptions, waitForMessage };

dist/util/testHelpers.js

 import {
   UNCAUGHT_ERROR,
   pushable
-} from "../chunk-KWXQLQAF.js";
+} from "../chunk-Q6WPGM3K.js";
 import "../chunk-RPIDSIQG.js";
@@ -6,0 +6,0 @@ import {

package.json

 {
   "name": "@replit/river",
   "description": "It's like tRPC but... with JSON Schema Support, duplex streaming and support for service multiplexing. Transport agnostic!",
-  "version": "0.15.7",
+  "version": "0.16.0",
   "type": "module",
@@ -6,0 +6,0 @@ "exports": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

396818

increased by9%

Lines of code

11365

increased by5.91%

Worsened metrics

Number of medium supply chain risk alerts

2

increased by100%

No dependency changes