@confect/server 6.0.0 → 8.0.0

package/src/RegisteredConvexFunction.ts

@@ -10,6 +10,7 @@ import {
   mutationGeneric,
   queryGeneric,
 } from "convex/server";
+import type { Value } from "convex/values";
 import { Clock, Effect, Layer, Match, pipe, Schema } from "effect";
 import type * as Api from "./Api";
 import * as Auth from "./Auth";
@@ -49,9 +50,11 @@ export const make = <Api_ extends Api.AnyWithPropsWithRuntime<"Convex">>(
           );
 
           return genericFunction(
-            queryFunction(api.databaseSchema, {
+            queryFunction({
+              databaseSchema: api.databaseSchema,
               args: functionProvenance.args,
               returns: functionProvenance.returns,
+              error: functionProvenance.error,
               handler: handler as Handler.AnyConfectProvenance,
             }),
           );
@@ -64,9 +67,11 @@ export const make = <Api_ extends Api.AnyWithPropsWithRuntime<"Convex">>(
           );
 
           return genericFunction(
-            mutationFunction(api.databaseSchema, {
+            mutationFunction({
+              databaseSchema: api.databaseSchema,
               args: functionProvenance.args,
               returns: functionProvenance.returns,
+              error: functionProvenance.error,
               handler: handler as Handler.AnyConfectProvenance,
             }),
           );
@@ -82,6 +87,7 @@ export const make = <Api_ extends Api.AnyWithPropsWithRuntime<"Convex">>(
             convexActionFunction(api.databaseSchema, {
               args: functionProvenance.args,
               returns: functionProvenance.returns,
+              error: functionProvenance.error,
               handler: handler as Handler.AnyConfectProvenance,
             }),
           );
@@ -92,27 +98,28 @@ export const make = <Api_ extends Api.AnyWithPropsWithRuntime<"Convex">>(
     Match.exhaustive,
   );
 
-// Convex's query cache is invalidated by any Date.now() call during handler
-// execution. Effect's unsafeFork calls Date.now() when constructing a
-// FiberId.Runtime, which trips the cache for every confect-wrapped query. We
-// stub Date.now to 0 for the span of the handler; queries are forbidden from
-// relying on real time for correctness anyway.
-//
-// Users who explicitly want the real timestamp can still reach it via Effect's
-// Clock service (Clock.currentTimeMillis / Clock.currentTimeNanos). We provide
-// a Clock layer whose methods close over the *original* Date.now, so opting in
-// to Clock is an opt-in to worse caching — but caching is not broken by default.
+/**
+ * Convex's query cache is invalidated by any Date.now() call during handler
+ * execution. Effect's unsafeFork calls Date.now() when constructing a
+ * FiberId.Runtime, which trips the cache for every confect-wrapped query. We
+ * stub Date.now to 0 for the span of the handler; queries are forbidden from
+ * relying on real time for correctness anyway.
+ *
+ * Users who explicitly want the real timestamp can still reach it via Effect's
+ * Clock service (Clock.currentTimeMillis/Clock.currentTimeNanos). We provide a
+ * Clock whose user-facing Effects call realDateNow (Convex's tracker) directly,
+ * making Clock an explicit opt-in to cache invalidation. The unsafe methods
+ * used internally by Effect (logging, span events, scheduler) return constants
+ * so they never touch the tracker—caching is not broken by default.
+ */
 const unpatchedClock = (realDateNow: () => number): Clock.Clock => {
-  const bigint1e6 = BigInt(1_000_000);
-  const unsafeCurrentTimeMillis = () => realDateNow();
-  const unsafeCurrentTimeNanos = () => BigInt(realDateNow()) * bigint1e6;
   const defaultClock = Clock.make();
   return {
     ...defaultClock,
-    unsafeCurrentTimeMillis,
-    unsafeCurrentTimeNanos,
-    currentTimeMillis: Effect.sync(unsafeCurrentTimeMillis),
-    currentTimeNanos: Effect.sync(unsafeCurrentTimeNanos),
+    unsafeCurrentTimeMillis: () => 0,
+    unsafeCurrentTimeNanos: () => 0n,
+    currentTimeMillis: Effect.sync(() => realDateNow()),
+    currentTimeNanos: Effect.sync(() => BigInt(realDateNow()) * 1_000_000n),
   };
 };
 
@@ -136,30 +143,31 @@ const queryFunction = <
   Returns,
   ConvexReturns,
   E,
->(
-  databaseSchema: DatabaseSchema_,
-  {
-    args,
-    returns,
-    handler,
-  }: {
-    args: Schema.Schema<Args, ConvexArgs>;
-    returns: Schema.Schema<Returns, ConvexReturns>;
-    handler: (
-      a: Args,
-    ) => Effect.Effect<
-      Returns,
-      E,
-      | DatabaseReader.DatabaseReader<DatabaseSchema_>
-      | Auth.Auth
-      | StorageReader
-      | QueryRunner.QueryRunner
-      | QueryCtx.QueryCtx<
-          DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
-        >
-    >;
-  },
-) => ({
+>({
+  databaseSchema,
+  args,
+  returns,
+  error,
+  handler,
+}: {
+  databaseSchema: DatabaseSchema_;
+  args: Schema.Schema<Args, ConvexArgs>;
+  returns: Schema.Schema<Returns, ConvexReturns>;
+  error: Schema.Schema<Error, Value> | undefined;
+  handler: (
+    a: Args,
+  ) => Effect.Effect<
+    Returns,
+    E,
+    | DatabaseReader.DatabaseReader<DatabaseSchema_>
+    | Auth.Auth
+    | StorageReader
+    | QueryRunner.QueryRunner
+    | QueryCtx.QueryCtx<
+        DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
+      >
+  >;
+}) => ({
   args: SchemaToValidator.compileArgsSchema(args),
   returns: SchemaToValidator.compileReturnsSchema(returns),
   handler: (
@@ -169,35 +177,37 @@ const queryFunction = <
     actualArgs: ConvexArgs,
   ): Promise<ConvexReturns> =>
     withStubbedDateNow((clock) =>
-      pipe(
-        actualArgs,
-        Schema.decode(args),
-        Effect.orDie,
-        Effect.andThen((decodedArgs) =>
-          pipe(
-            handler(decodedArgs),
-            Effect.provide(
-              Layer.mergeAll(
-                DatabaseReader.layer(databaseSchema, ctx.db),
-                Auth.layer(ctx.auth),
-                StorageReader.layer(ctx.storage),
-                QueryRunner.layer(ctx.runQuery),
-                Layer.succeed(
-                  QueryCtx.QueryCtx<
-                    DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
-                  >(),
-                  ctx,
-                ),
-                Layer.setConfigProvider(ConvexConfigProvider.make()),
+      Effect.gen(function* () {
+        const decodedArgs = yield* pipe(
+          actualArgs,
+          Schema.decode(args),
+          Effect.orDie,
+        );
+        const decodedReturns = yield* handler(decodedArgs).pipe(
+          Effect.provide(
+            Layer.mergeAll(
+              DatabaseReader.layer(databaseSchema, ctx.db),
+              Auth.layer(ctx.auth),
+              StorageReader.layer(ctx.storage),
+              QueryRunner.layer(ctx.runQuery),
+              Layer.succeed(
+                QueryCtx.QueryCtx<
+                  DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
+                >(),
+                ctx,
               ),
+              Layer.setConfigProvider(ConvexConfigProvider.make()),
             ),
           ),
-        ),
-        Effect.andThen((convexReturns) =>
-          Schema.encodeUnknown(returns)(convexReturns),
-        ),
+        );
+        return yield* pipe(
+          decodedReturns,
+          Schema.encode(returns),
+          Effect.orDie,
+        );
+      }).pipe(
         Effect.withClock(clock),
-        Effect.runPromise,
+        RegisteredFunction.runHandlerPromise(error),
       ),
     ),
 });
@@ -236,42 +246,46 @@ export type MutationServices<Schema extends DatabaseSchema.AnyWithProps> =
   | MutationCtx.MutationCtx<DataModel.ToConvex<DataModel.FromSchema<Schema>>>;
 
 const mutationFunction = <
-  Schema extends DatabaseSchema.AnyWithProps,
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
   Args,
   ConvexArgs extends DefaultFunctionArgs,
   Returns,
   ConvexReturns,
   E,
->(
-  schema: Schema,
-  {
-    args,
-    returns,
-    handler,
-  }: {
-    args: Schema.Schema<Args, ConvexArgs>;
-    returns: Schema.Schema<Returns, ConvexReturns>;
-    handler: (a: Args) => Effect.Effect<Returns, E, MutationServices<Schema>>;
-  },
-) => ({
+>({
+  databaseSchema,
+  args,
+  returns,
+  error,
+  handler,
+}: {
+  databaseSchema: DatabaseSchema_;
+  args: Schema.Schema<Args, ConvexArgs>;
+  returns: Schema.Schema<Returns, ConvexReturns>;
+  error: Schema.Schema<Error, Value> | undefined;
+  handler: (
+    a: Args,
+  ) => Effect.Effect<Returns, E, MutationServices<DatabaseSchema_>>;
+}) => ({
   args: SchemaToValidator.compileArgsSchema(args),
   returns: SchemaToValidator.compileReturnsSchema(returns),
   handler: (
-    ctx: GenericMutationCtx<DataModel.ToConvex<DataModel.FromSchema<Schema>>>,
+    ctx: GenericMutationCtx<
+      DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
+    >,
     actualArgs: ConvexArgs,
   ): Promise<ConvexReturns> =>
-    pipe(
-      actualArgs,
-      Schema.decode(args),
-      Effect.orDie,
-      Effect.andThen((decodedArgs) =>
-        handler(decodedArgs).pipe(Effect.provide(mutationLayer(schema, 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(mutationLayer(databaseSchema, ctx)),
+      );
+      return yield* pipe(decodedReturns, Schema.encode(returns), Effect.orDie);
+    }).pipe(RegisteredFunction.runHandlerPromise(error)),
 });
 
 const convexActionFunction = <
@@ -286,10 +300,12 @@ const convexActionFunction = <
   {
     args,
     returns,
+    error,
     handler,
   }: {
     args: Schema.Schema<Args, ConvexArgs>;
     returns: Schema.Schema<Returns, ConvexReturns>;
+    error: Schema.Schema.AnyNoContext | undefined;
     handler: (
       a: Args,
     ) => Effect.Effect<
@@ -302,6 +318,7 @@ const convexActionFunction = <
   RegisteredFunction.actionFunctionBase({
     args,
     returns,
+    error,
     handler,
     createLayer: (ctx) =>
       Layer.mergeAll(

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(