@confect/core 6.0.0 → 7.0.0

package/src/Ref.ts

@@ -3,8 +3,10 @@ import type {
   FunctionVisibility,
 } from "convex/server";
 import { makeFunctionReference } from "convex/server";
+import type { Value } from "convex/values";
+import { ConvexError } from "convex/values";
 import type { ParseResult } from "effect";
-import { Effect, Match, Schema } from "effect";
+import { Effect, Match, Option, Schema } from "effect";
 import type * as FunctionSpec from "./FunctionSpec";
 import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType";
 
@@ -13,27 +15,30 @@ export interface Ref<
   _FunctionVisibility extends FunctionVisibility,
   _Args,
   _Returns,
+  _Error = never,
 > {
   readonly _RuntimeAndFunctionType?: _RuntimeAndFunctionType;
   readonly _FunctionVisibility?: _FunctionVisibility;
   readonly _Args?: _Args;
   readonly _Returns?: _Returns;
+  readonly _Error?: _Error;
   /** @internal */
   readonly functionSpec: FunctionSpec.AnyWithProps;
   /** @internal */
   readonly functionNamespace: string;
 }
 
-export interface Any extends Ref<any, any, any, any> {}
+export interface Any extends Ref<any, any, any, any, any> {}
 
-export interface AnyInternal extends Ref<any, "internal", any, any> {}
+export interface AnyInternal extends Ref<any, "internal", any, any, any> {}
 
-export interface AnyPublic extends Ref<any, "public", any, any> {}
+export interface AnyPublic extends Ref<any, "public", any, any, any> {}
 
 export interface AnyQuery extends Ref<
   RuntimeAndFunctionType.AnyQuery,
   FunctionVisibility,
   any,
+  any,
   any
 > {}
 
@@ -41,6 +46,7 @@ export interface AnyMutation extends Ref<
   RuntimeAndFunctionType.AnyMutation,
   FunctionVisibility,
   any,
+  any,
   any
 > {}
 
@@ -48,6 +54,7 @@ export interface AnyAction extends Ref<
   RuntimeAndFunctionType.AnyAction,
   FunctionVisibility,
   any,
+  any,
   any
 > {}
 
@@ -55,6 +62,7 @@ export interface AnyPublicQuery extends Ref<
   RuntimeAndFunctionType.AnyQuery,
   "public",
   any,
+  any,
   any
 > {}
 
@@ -62,6 +70,7 @@ export interface AnyPublicMutation extends Ref<
   RuntimeAndFunctionType.AnyMutation,
   "public",
   any,
+  any,
   any
 > {}
 
@@ -69,6 +78,7 @@ export interface AnyPublicAction extends Ref<
   RuntimeAndFunctionType.AnyAction,
   "public",
   any,
+  any,
   any
 > {}
 
@@ -77,7 +87,8 @@ export type GetRuntimeAndFunctionType<Ref_> =
     infer RuntimeAndFunctionType_,
     infer _FunctionVisibility,
     infer _Args,
-    infer _Returns
+    infer _Returns,
+    infer _Error
   >
     ? RuntimeAndFunctionType_
     : never;
@@ -87,7 +98,8 @@ export type GetRuntime<Ref_> =
     infer RuntimeAndFunctionType_,
     infer _FunctionVisibility,
     infer _Args,
-    infer _Returns
+    infer _Returns,
+    infer _Error
   >
     ? RuntimeAndFunctionType.GetRuntime<RuntimeAndFunctionType_>
     : never;
@@ -97,7 +109,8 @@ export type GetFunctionType<Ref_> =
     infer RuntimeAndFunctionType_,
     infer _FunctionVisibility,
     infer _Args,
-    infer _Returns
+    infer _Returns,
+    infer _Error
   >
     ? RuntimeAndFunctionType.GetFunctionType<RuntimeAndFunctionType_>
     : never;
@@ -107,7 +120,8 @@ export type GetFunctionVisibility<Ref_> =
     infer _RuntimeAndFunctionType,
     infer FunctionVisibility_,
     infer _Args,
-    infer _Returns
+    infer _Returns,
+    infer _Error
   >
     ? FunctionVisibility_
     : never;
@@ -117,7 +131,8 @@ export type Args<Ref_> =
     infer _RuntimeAndFunctionType,
     infer _FunctionVisibility,
     infer Args_,
-    infer _Returns
+    infer _Returns,
+    infer _Error
   >
     ? Args_
     : never;
@@ -131,11 +146,23 @@ export type Returns<Ref_> =
     infer _RuntimeAndFunctionType,
     infer _FunctionVisibility,
     infer _Args,
-    infer Returns_
+    infer Returns_,
+    infer _Error
   >
     ? Returns_
     : never;
 
+export type Error<Ref_> =
+  Ref_ extends Ref<
+    infer _RuntimeAndFunctionType,
+    infer _FunctionVisibility,
+    infer _Args,
+    infer _Returns,
+    infer Error_
+  >
+    ? Error_
+    : never;
+
 export type FunctionReference<Ref_ extends Any> = ConvexFunctionReference<
   GetFunctionType<Ref_>,
   GetFunctionVisibility<Ref_>
@@ -146,7 +173,8 @@ export type FromFunctionSpec<FunctionSpec_ extends FunctionSpec.AnyWithProps> =
     FunctionSpec.GetRuntimeAndFunctionType<FunctionSpec_>,
     FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
     FunctionSpec.Args<FunctionSpec_>,
-    FunctionSpec.Returns<FunctionSpec_>
+    FunctionSpec.Returns<FunctionSpec_>,
+    FunctionSpec.Error<FunctionSpec_>
   >;
 
 export const make = <FunctionSpec_ extends FunctionSpec.AnyWithProps>(
@@ -167,12 +195,25 @@ export const getFunctionReference = <Ref_ extends Any>(
 ): FunctionReference<Ref_> =>
   makeFunctionReference(getConvexFunctionName(ref)) as FunctionReference<Ref_>;
 
+export const hasErrorSchema = (ref: Any): boolean =>
+  Match.value(ref.functionSpec.functionProvenance).pipe(
+    Match.tag(
+      "Confect",
+      (confectFunctionProvenance) =>
+        confectFunctionProvenance.error !== undefined,
+    ),
+    Match.tag("Convex", () => false),
+    Match.exhaustive,
+  );
+
 export const encodeArgs = <Ref_ extends Any>(
   ref: Ref_,
   args: Args<Ref_>,
 ): Effect.Effect<unknown, ParseResult.ParseError> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (c) => Schema.encode(c.args)(args)),
+    Match.tag("Confect", (confectFunctionProvenance) =>
+      Schema.encode(confectFunctionProvenance.args)(args),
+    ),
     Match.tag("Convex", () => Effect.succeed(args)),
     Match.exhaustive,
   );
@@ -182,7 +223,9 @@ export const decodeReturns = <Ref_ extends Any>(
   returns: unknown,
 ): Effect.Effect<Returns<Ref_>, ParseResult.ParseError> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (c) => Schema.decode(c.returns)(returns)),
+    Match.tag("Confect", (confectFunctionProvenance) =>
+      Schema.decode(confectFunctionProvenance.returns)(returns),
+    ),
     Match.tag("Convex", () => Effect.succeed(returns)),
     Match.exhaustive,
   );
@@ -192,7 +235,9 @@ export const encodeArgsSync = <Ref_ extends Any>(
   args: Args<Ref_>,
 ): unknown =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (c) => Schema.encodeSync(c.args)(args)),
+    Match.tag("Confect", (confectFunctionProvenance) =>
+      Schema.encodeSync(confectFunctionProvenance.args)(args),
+    ),
     Match.tag("Convex", () => args),
     Match.exhaustive,
   );
@@ -202,52 +247,155 @@ export const decodeReturnsSync = <Ref_ extends Any>(
   encodedReturns: unknown,
 ): Returns<Ref_> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (c) => Schema.decodeSync(c.returns)(encodedReturns)),
+    Match.tag("Confect", (confectFunctionProvenance) =>
+      Schema.decodeSync(confectFunctionProvenance.returns)(encodedReturns),
+    ),
     Match.tag("Convex", () => encodedReturns),
     Match.exhaustive,
   ) as Returns<Ref_>;
 
-export const runWithCodec: {
-  <Ref_ extends Any, E>(
-    ref: Ref_,
-    args: Args<Ref_>,
-    f: (
-      functionReference: FunctionReference<Ref_>,
-      encodedArgs: unknown,
-    ) => Effect.Effect<unknown, E>,
-  ): Effect.Effect<Returns<Ref_>, E | ParseResult.ParseError>;
-  <Ref_ extends Any>(
-    ref: Ref_,
-    args: Args<Ref_>,
-    f: (
-      functionReference: FunctionReference<Ref_>,
-      encodedArgs: unknown,
-    ) => PromiseLike<unknown>,
-  ): Effect.Effect<Returns<Ref_>, ParseResult.ParseError>;
-} = <Ref_ extends Any, E>(
+const ConvexErrorIdentifier = Symbol.for("ConvexError");
+
+export const isConvexError = (error: unknown): error is ConvexError<Value> =>
+  error instanceof ConvexError ||
+  (typeof error === "object" &&
+    error !== null &&
+    ConvexErrorIdentifier in error);
+
+/**
+ * Build a callback-style handler that decodes the ref's typed error from a
+ * caught `ConvexError`, or else forwards the value to `mapUnknownError`. The
+ * fallback is also invoked when the input *is* a `ConvexError` but the ref
+ * doesn't declare a typed-error schema—by definition such a value falls
+ * outside the ref's error contract. Useful when adapting non-Effect APIs (e.g.
+ * emitter callbacks for streamed subscriptions) to the same error semantics
+ * that `runWithCodec` provides.
+ */
+export const decodeErrorOrElse =
+  <Ref_ extends Any, E>(ref: Ref_, mapUnknownError: (error: unknown) => E) =>
+  (error: unknown): Error<Ref_> | E => {
+    if (isConvexError(error)) {
+      const decoded = decodeErrorSync(ref, error.data);
+      if (Option.isSome(decoded)) {
+        return decoded.value;
+      }
+    }
+    return mapUnknownError(error);
+  };
+
+/**
+ * Decode `encodedError` against the ref's error schema. Returns `None` if the
+ * ref doesn't declare a typed error (Confect ref without an `error` schema, or
+ * a Convex-provenance ref)—by definition there's nothing to decode the value
+ * into, and the caller is responsible for deciding what to do (typically:
+ * surface the original value as a defect).
+ */
+export const decodeError = <Ref_ extends Any>(
+  ref: Ref_,
+  encodedError: unknown,
+): Effect.Effect<Option.Option<Error<Ref_>>, ParseResult.ParseError> =>
+  Match.value(ref.functionSpec.functionProvenance).pipe(
+    Match.tag("Confect", (confectFunctionProvenance) =>
+      confectFunctionProvenance.error !== undefined
+        ? Effect.map(
+            Schema.decode(confectFunctionProvenance.error)(encodedError),
+            Option.some,
+          )
+        : Effect.succeed(Option.none<Error<Ref_>>()),
+    ),
+    Match.tag("Convex", () => Effect.succeed(Option.none<Error<Ref_>>())),
+    Match.exhaustive,
+  );
+
+/**
+ * Synchronous counterpart to `decodeError`. Throws on schema decode failure;
+ * returns `None` when the ref doesn't declare a typed error.
+ */
+export const decodeErrorSync = <Ref_ extends Any>(
+  ref: Ref_,
+  encodedError: unknown,
+): Option.Option<Error<Ref_>> =>
+  Match.value(ref.functionSpec.functionProvenance).pipe(
+    Match.tag("Confect", (confectFunctionProvenance) =>
+      confectFunctionProvenance.error !== undefined
+        ? Option.some(
+            Schema.decodeSync(confectFunctionProvenance.error)(
+              encodedError,
+            ) as Error<Ref_>,
+          )
+        : Option.none<Error<Ref_>>(),
+    ),
+    Match.tag("Convex", () => Option.none<Error<Ref_>>()),
+    Match.exhaustive,
+  );
+
+export const maybeDecodeErrorSync = <Ref_ extends Any>(
+  ref: Ref_,
+  error: unknown,
+): unknown =>
+  isConvexError(error)
+    ? Match.value(ref.functionSpec.functionProvenance).pipe(
+        Match.tag("Confect", (confectFunctionProvenance) =>
+          confectFunctionProvenance.error !== undefined
+            ? Schema.decodeSync(confectFunctionProvenance.error)(error.data)
+            : error,
+        ),
+        Match.tag("Convex", () => error),
+        Match.exhaustive,
+      )
+    : error;
+
+/**
+ * Encode args via the ref's args schema, invoke `call`, decode returns via the
+ * ref's returns schema, and translate any thrown `ConvexError` into the ref's
+ * typed error. Anything else the Promise rejects with—network failures,
+ * server-side runtime errors, validation failures, etc.—is passed to
+ * `mapUnknownError` to be turned into a typed `E`, or surfaced as a defect when
+ * no handler is provided.
+ */
+export const runWithCodec = <Ref_ extends Any, E = never>(
   ref: Ref_,
   args: Args<Ref_>,
-  f: (
+  call: (
     functionReference: FunctionReference<Ref_>,
     encodedArgs: unknown,
-  ) => Effect.Effect<unknown, E> | PromiseLike<unknown>,
-): Effect.Effect<Returns<Ref_>, E | ParseResult.ParseError> =>
+  ) => PromiseLike<unknown>,
+  mapUnknownError?: (error: unknown) => E,
+): Effect.Effect<Returns<Ref_>, E | Error<Ref_> | ParseResult.ParseError> =>
   Effect.gen(function* () {
     const functionReference = getFunctionReference(ref);
     const functionProvenance = ref.functionSpec.functionProvenance;
-    const call = (encodedArgs: unknown) => {
-      const result = f(functionReference, encodedArgs);
-      return Effect.isEffect(result) ? result : Effect.promise(() => result);
-    };
+    const invoke = (
+      encodedArgs: unknown,
+    ): Effect.Effect<unknown, Error<Ref_> | E> =>
+      Effect.tryPromise({
+        try: () => Promise.resolve(call(functionReference, encodedArgs)),
+        catch: (error): Error<Ref_> | E => {
+          if (isConvexError(error)) {
+            const decoded = decodeErrorSync(ref, error.data);
+            if (Option.isSome(decoded)) {
+              return decoded.value;
+            }
+          }
+          if (mapUnknownError !== undefined) {
+            return mapUnknownError(error);
+          }
+          throw error;
+        },
+      });
     return yield* Match.value(functionProvenance).pipe(
-      Match.tag("Confect", (confect) =>
+      Match.tag("Confect", (confectFunctionProvenance) =>
         Effect.gen(function* () {
-          const encodedArgs = yield* Schema.encode(confect.args)(args);
-          const encodedReturns = yield* call(encodedArgs);
-          return yield* Schema.decode(confect.returns)(encodedReturns);
+          const encodedArgs = yield* Schema.encode(
+            confectFunctionProvenance.args,
+          )(args);
+          const encodedReturns = yield* invoke(encodedArgs);
+          return yield* Schema.decode(confectFunctionProvenance.returns)(
+            encodedReturns,
+          );
         }),
       ),
-      Match.tag("Convex", () => call(args)),
+      Match.tag("Convex", () => invoke(args)),
       Match.exhaustive,
     );
   });