@confect/server 6.0.0 → 7.0.0

package/src/RegisteredFunction.ts

@@ -8,7 +8,9 @@ import {
   type RegisteredMutation,
   type RegisteredQuery,
 } from "convex/server";
-import { Effect, Layer, pipe, Schema } from "effect";
+import type { Value } from "convex/values";
+import { ConvexError } from "convex/values";
+import { Effect, Either, Layer, pipe, Schema } from "effect";
 import * as ActionCtx from "./ActionCtx";
 import * as ActionRunner from "./ActionRunner";
 import * as Auth from "./Auth";
@@ -18,9 +20,9 @@ import * as MutationRunner from "./MutationRunner";
 import * as QueryRunner from "./QueryRunner";
 import * as Scheduler from "./Scheduler";
 import * as SchemaToValidator from "./SchemaToValidator";
-import { StorageActionWriter } from "./StorageActionWriter";
-import { StorageReader } from "./StorageReader";
-import { StorageWriter } from "./StorageWriter";
+import * as StorageActionWriter from "./StorageActionWriter";
+import * as StorageReader from "./StorageReader";
+import * as StorageWriter from "./StorageWriter";
 import * as VectorSearch from "./VectorSearch";
 
 export type Any =
@@ -111,6 +113,48 @@ export type RegisteredFunction<
       ? ConfectRegisteredFunction<FunctionSpec_>
       : never;
 
+/**
+ * Run the `Effect` as a `Promise`. The error schema acts as an allowlist of
+ * failures that may be surfaced to the client as a `ConvexError`:
+ *
+ * - With a schema: typed errors are schema-encoded and wrapped in a
+ * `ConvexError`, then thrown so Convex surfaces the data to the client.
+ * `Effect.either` escapes the failure channel before `runPromise` so the thrown
+ * `ConvexError` retains its `Symbol.for("ConvexError")` identity instead of
+ * being wrapped in Effect's `FiberFailure`.
+ *
+ * - Without a schema: every failure is converted to a defect via
+ * `Effect.orDie`, so nothing—not even a `ConvexError` the handler placed in its
+ * error channel—reaches the client as a `ConvexError`. The fiber dies and
+ * `runPromise` rejects with a generic failure.
+ */
+export const runHandlerPromise =
+  (errorSchema: Schema.Schema.AnyNoContext | undefined) =>
+  <A, E>(effect: Effect.Effect<A, E>): Promise<A> => {
+    if (errorSchema === undefined) {
+      return Effect.runPromise(Effect.orDie(effect));
+    }
+    const withConvexError = effect.pipe(
+      Effect.catchAll((typedError) =>
+        pipe(
+          Schema.encode(errorSchema)(typedError),
+          Effect.orDie,
+          Effect.andThen((encodedError) =>
+            Effect.fail(new ConvexError(encodedError)),
+          ),
+        ),
+      ),
+    );
+    return Effect.runPromise(Effect.either(withConvexError)).then(
+      Either.match({
+        onLeft: (error) => {
+          throw error;
+        },
+        onRight: (value) => value,
+      }),
+    );
+  };
+
 export const actionFunctionBase = <
   Schema extends DatabaseSchema.AnyWithProps,
   Args,
@@ -122,11 +166,13 @@ export const actionFunctionBase = <
 >({
   args,
   returns,
+  error,
   handler,
   createLayer,
 }: {
   args: Schema.Schema<Args, ConvexArgs>;
   returns: Schema.Schema<Returns, ConvexReturns>;
+  error: Schema.Schema<Error, Value> | undefined;
   handler: (a: Args) => Effect.Effect<Returns, E, R>;
   createLayer: (
     ctx: GenericActionCtx<DataModel.ToConvex<DataModel.FromSchema<Schema>>>,
@@ -138,18 +184,17 @@ export const actionFunctionBase = <
     ctx: GenericActionCtx<DataModel.ToConvex<DataModel.FromSchema<Schema>>>,
     actualArgs: ConvexArgs,
   ): Promise<ConvexReturns> =>
-    pipe(
-      actualArgs,
-      Schema.decode(args),
-      Effect.orDie,
-      Effect.andThen((decodedArgs) =>
-        handler(decodedArgs).pipe(Effect.provide(createLayer(ctx))),
-      ),
-      Effect.andThen((convexReturns) =>
-        Schema.encodeUnknown(returns)(convexReturns),
-      ),
-      Effect.runPromise,
-    ),
+    Effect.gen(function* () {
+      const decodedArgs = yield* pipe(
+        actualArgs,
+        Schema.decode(args),
+        Effect.orDie,
+      );
+      const decodedReturns = yield* handler(decodedArgs).pipe(
+        Effect.provide(createLayer(ctx)),
+      );
+      return yield* pipe(decodedReturns, Schema.encode(returns), Effect.orDie);
+    }).pipe(runHandlerPromise(error)),
 });
 
 export type ActionServices<
@@ -157,9 +202,9 @@ export type ActionServices<
 > =
   | Scheduler.Scheduler
   | Auth.Auth
-  | StorageReader
-  | StorageWriter
-  | StorageActionWriter
+  | StorageReader.StorageReader
+  | StorageWriter.StorageWriter
+  | StorageActionWriter.StorageActionWriter
   | QueryRunner.QueryRunner
   | MutationRunner.MutationRunner
   | ActionRunner.ActionRunner
@@ -179,9 +224,9 @@ export const actionLayer = <
   Layer.mergeAll(
     Scheduler.layer(ctx.scheduler),
     Auth.layer(ctx.auth),
-    StorageReader.layer(ctx.storage),
-    StorageWriter.layer(ctx.storage),
-    StorageActionWriter.layer(ctx.storage),
+    StorageReader.StorageReader.layer(ctx.storage),
+    StorageWriter.StorageWriter.layer(ctx.storage),
+    StorageActionWriter.StorageActionWriter.layer(ctx.storage),
     QueryRunner.layer(ctx.runQuery),
     MutationRunner.layer(ctx.runMutation),
     ActionRunner.layer(ctx.runAction),

package/src/RegisteredNodeFunction.ts

@@ -33,6 +33,7 @@ export const make = <Api_ extends Api.AnyWithPropsWithRuntime<"Node">>(
         nodeActionFunction(api.databaseSchema, {
           args: functionProvenance.args,
           returns: functionProvenance.returns,
+          error: functionProvenance.error,
           handler: handler as Handler.AnyConfectProvenance,
         }),
       );
@@ -52,10 +53,12 @@ const nodeActionFunction = <
   {
     args,
     returns,
+    error,
     handler,
   }: {
     args: Schema.Schema<Args, ConvexArgs>;
     returns: Schema.Schema<Returns, ConvexReturns>;
+    error: Schema.Schema.AnyNoContext | undefined;
     handler: (
       a: Args,
     ) => Effect.Effect<
@@ -69,6 +72,7 @@ const nodeActionFunction = <
   RegisteredFunction.actionFunctionBase({
     args,
     returns,
+    error,
     handler,
     createLayer: (ctx) =>
       Layer.mergeAll(