@confect/server 5.0.0 → 7.0.0

package/src/MutationRunner.ts

@@ -1,15 +1,22 @@
 import * as Ref from "@confect/core/Ref";
 import { type GenericMutationCtx } from "convex/server";
-import { Context, Layer, Schema } from "effect";
+import type { ParseResult, Effect } from "effect";
+import { Context, Layer } from "effect";
 
 const make =
   (runMutation: GenericMutationCtx<any>["runMutation"]) =>
   <Mutation extends Ref.AnyMutation>(
     mutation: Mutation,
-    args: Ref.Args<Mutation>,
-  ) =>
-    Ref.runWithCodec(mutation, args, (functionReference, encodedArgs) =>
-      runMutation(functionReference, encodedArgs),
+    ...args: Ref.OptionalArgs<Mutation>
+  ): Effect.Effect<
+    Ref.Returns<Mutation>,
+    Ref.Error<Mutation> | ParseResult.ParseError
+  > =>
+    Ref.runWithCodec(
+      mutation,
+      (args[0] ?? {}) as Ref.Args<Mutation>,
+      (functionReference, encodedArgs) =>
+        runMutation(functionReference, encodedArgs),
     );
 
 export const MutationRunner = Context.GenericTag<ReturnType<typeof make>>(
@@ -19,17 +26,3 @@ export type MutationRunner = typeof MutationRunner.Identifier;
 
 export const layer = (runMutation: GenericMutationCtx<any>["runMutation"]) =>
   Layer.succeed(MutationRunner, make(runMutation));
-
-export class MutationRollback extends Schema.TaggedError<MutationRollback>()(
-  "MutationRollback",
-  {
-    mutationName: Schema.String,
-    error: Schema.Unknown,
-  },
-) {
-  /* v8 ignore start */
-  override get message(): string {
-    return `Mutation ${this.mutationName} failed and was rolled back.\n\n${this.error}`;
-  }
-  /* v8 ignore stop */
-}

package/src/QueryRunner.ts

@@ -1,12 +1,22 @@
 import * as Ref from "@confect/core/Ref";
 import { type GenericQueryCtx } from "convex/server";
+import type { ParseResult, Effect } from "effect";
 import { Context, Layer } from "effect";
 
 const make =
   (runQuery: GenericQueryCtx<any>["runQuery"]) =>
-  <Query extends Ref.AnyQuery>(query: Query, args: Ref.Args<Query>) =>
-    Ref.runWithCodec(query, args, (functionReference, encodedArgs) =>
-      runQuery(functionReference, encodedArgs),
+  <Query extends Ref.AnyQuery>(
+    query: Query,
+    ...args: Ref.OptionalArgs<Query>
+  ): Effect.Effect<
+    Ref.Returns<Query>,
+    Ref.Error<Query> | ParseResult.ParseError
+  > =>
+    Ref.runWithCodec(
+      query,
+      (args[0] ?? {}) as Ref.Args<Query>,
+      (functionReference, encodedArgs) =>
+        runQuery(functionReference, encodedArgs),
     );
 
 export const QueryRunner = Context.GenericTag<ReturnType<typeof make>>(

package/src/RegisteredConvexFunction.ts

@@ -10,7 +10,8 @@ import {
   mutationGeneric,
   queryGeneric,
 } from "convex/server";
-import { Effect, Layer, Match, pipe, Schema } from "effect";
+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";
 import * as ConvexConfigProvider from "./ConvexConfigProvider";
@@ -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,6 +98,43 @@ 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.
+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),
+  };
+};
+
+const withStubbedDateNow = async <T>(
+  queryHandler: (clock: Clock.Clock) => Promise<T>,
+): Promise<T> => {
+  const realDateNow = Date.now;
+  const clock = unpatchedClock(realDateNow);
+  Date.now = () => 0;
+  try {
+    return await queryHandler(clock);
+  } finally {
+    Date.now = realDateNow;
+  }
+};
+
 const queryFunction = <
   DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
   Args,
@@ -99,30 +142,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: (
@@ -131,13 +175,14 @@ const queryFunction = <
     >,
     actualArgs: ConvexArgs,
   ): Promise<ConvexReturns> =>
-    pipe(
-      actualArgs,
-      Schema.decode(args),
-      Effect.orDie,
-      Effect.andThen((decodedArgs) =>
-        pipe(
-          handler(decodedArgs),
+    withStubbedDateNow((clock) =>
+      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),
@@ -153,12 +198,16 @@ const queryFunction = <
               Layer.setConfigProvider(ConvexConfigProvider.make()),
             ),
           ),
-        ),
-      ),
-      Effect.andThen((convexReturns) =>
-        Schema.encodeUnknown(returns)(convexReturns),
+        );
+        return yield* pipe(
+          decodedReturns,
+          Schema.encode(returns),
+          Effect.orDie,
+        );
+      }).pipe(
+        Effect.withClock(clock),
+        RegisteredFunction.runHandlerPromise(error),
       ),
-      Effect.runPromise,
     ),
 });
 
@@ -196,42 +245,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 = <
@@ -246,10 +299,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<
@@ -262,6 +317,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(

package/src/Scheduler.ts

@@ -2,16 +2,11 @@ import { Ref } from "@confect/core";
 import type { Scheduler as ConvexScheduler } from "convex/server";
 import { Context, DateTime, Duration, Effect, Layer } from "effect";
 
-type OptionalArgs<Ref_ extends Ref.AnyMutation | Ref.AnyAction> =
-  keyof Ref.Args<Ref_> extends never
-    ? [args?: Ref.Args<Ref_>]
-    : [args: Ref.Args<Ref_>];
-
 const make = (scheduler: ConvexScheduler) => ({
   runAfter: <Ref_ extends Ref.AnyMutation | Ref.AnyAction>(
     delay: Duration.Duration,
     ref: Ref_,
-    ...args: OptionalArgs<Ref_>
+    ...args: Ref.OptionalArgs<Ref_>
   ) => {
     const delayMs = Duration.toMillis(delay);
     const functionReference = Ref.getFunctionReference(ref);
@@ -27,7 +22,7 @@ const make = (scheduler: ConvexScheduler) => ({
   runAt: <Ref_ extends Ref.AnyMutation | Ref.AnyAction>(
     dateTime: DateTime.DateTime,
     ref: Ref_,
-    ...args: OptionalArgs<Ref_>
+    ...args: Ref.OptionalArgs<Ref_>
   ) => {
     const timestamp = DateTime.toEpochMillis(dateTime);
     const functionReference = Ref.getFunctionReference(ref);