@confect/core 5.0.0 → 7.0.0

package/dist/Ref.d.ts

@@ -1,35 +1,39 @@
 import { AnyAction as AnyAction$1, AnyMutation as AnyMutation$1, AnyQuery as AnyQuery$1, GetFunctionType as GetFunctionType$1, GetRuntime as GetRuntime$1, RuntimeAndFunctionType } from "./RuntimeAndFunctionType.js";
-import { AnyWithProps, Args as Args$1, GetFunctionVisibility as GetFunctionVisibility$1, GetRuntimeAndFunctionType as GetRuntimeAndFunctionType$1, Returns as Returns$1 } from "./FunctionSpec.js";
-import { Effect, ParseResult } from "effect";
+import { AnyWithProps, Args as Args$1, Error as Error$1, GetFunctionVisibility as GetFunctionVisibility$1, GetRuntimeAndFunctionType as GetRuntimeAndFunctionType$1, Returns as Returns$1 } from "./FunctionSpec.js";
+import { Effect, Option, ParseResult } from "effect";
 import { FunctionReference as FunctionReference$1, FunctionVisibility } from "convex/server";
+import { ConvexError, Value } from "convex/values";
 
 //#region src/Ref.d.ts
 declare namespace Ref_d_exports {
-  export { Any, AnyAction, AnyInternal, AnyMutation, AnyPublic, AnyPublicAction, AnyPublicMutation, AnyPublicQuery, AnyQuery, Args, FromFunctionSpec, FunctionReference, GetFunctionType, GetFunctionVisibility, GetRuntime, GetRuntimeAndFunctionType, Ref, Returns, decodeReturns, decodeReturnsSync, encodeArgs, encodeArgsSync, getConvexFunctionName, getFunctionReference, make, runWithCodec };
+  export { Any, AnyAction, AnyInternal, AnyMutation, AnyPublic, AnyPublicAction, AnyPublicMutation, AnyPublicQuery, AnyQuery, Args, Error, FromFunctionSpec, FunctionReference, GetFunctionType, GetFunctionVisibility, GetRuntime, GetRuntimeAndFunctionType, OptionalArgs, Ref, Returns, decodeError, decodeErrorOrElse, decodeErrorSync, decodeReturns, decodeReturnsSync, encodeArgs, encodeArgsSync, getConvexFunctionName, getFunctionReference, hasErrorSchema, isConvexError, make, maybeDecodeErrorSync, runWithCodec };
 }
-interface Ref<_RuntimeAndFunctionType extends RuntimeAndFunctionType, _FunctionVisibility extends FunctionVisibility, _Args, _Returns> {
+interface Ref<_RuntimeAndFunctionType extends RuntimeAndFunctionType, _FunctionVisibility extends FunctionVisibility, _Args, _Returns, _Error = never> {
   readonly _RuntimeAndFunctionType?: _RuntimeAndFunctionType;
   readonly _FunctionVisibility?: _FunctionVisibility;
   readonly _Args?: _Args;
   readonly _Returns?: _Returns;
+  readonly _Error?: _Error;
 }
-interface Any extends Ref<any, any, any, any> {}
-interface AnyInternal extends Ref<any, "internal", any, any> {}
-interface AnyPublic extends Ref<any, "public", any, any> {}
-interface AnyQuery extends Ref<AnyQuery$1, FunctionVisibility, any, any> {}
-interface AnyMutation extends Ref<AnyMutation$1, FunctionVisibility, any, any> {}
-interface AnyAction extends Ref<AnyAction$1, FunctionVisibility, any, any> {}
-interface AnyPublicQuery extends Ref<AnyQuery$1, "public", any, any> {}
-interface AnyPublicMutation extends Ref<AnyMutation$1, "public", any, any> {}
-interface AnyPublicAction extends Ref<AnyAction$1, "public", any, any> {}
-type GetRuntimeAndFunctionType<Ref_> = Ref_ extends Ref<infer RuntimeAndFunctionType_, infer _FunctionVisibility, infer _Args, infer _Returns> ? RuntimeAndFunctionType_ : never;
-type GetRuntime<Ref_> = Ref_ extends Ref<infer RuntimeAndFunctionType_, infer _FunctionVisibility, infer _Args, infer _Returns> ? GetRuntime$1<RuntimeAndFunctionType_> : never;
-type GetFunctionType<Ref_> = Ref_ extends Ref<infer RuntimeAndFunctionType_, infer _FunctionVisibility, infer _Args, infer _Returns> ? GetFunctionType$1<RuntimeAndFunctionType_> : never;
-type GetFunctionVisibility<Ref_> = Ref_ extends Ref<infer _RuntimeAndFunctionType, infer FunctionVisibility_, infer _Args, infer _Returns> ? FunctionVisibility_ : never;
-type Args<Ref_> = Ref_ extends Ref<infer _RuntimeAndFunctionType, infer _FunctionVisibility, infer Args_, infer _Returns> ? Args_ : never;
-type Returns<Ref_> = Ref_ extends Ref<infer _RuntimeAndFunctionType, infer _FunctionVisibility, infer _Args, infer Returns_> ? Returns_ : never;
+interface Any extends Ref<any, any, any, any, any> {}
+interface AnyInternal extends Ref<any, "internal", any, any, any> {}
+interface AnyPublic extends Ref<any, "public", any, any, any> {}
+interface AnyQuery extends Ref<AnyQuery$1, FunctionVisibility, any, any, any> {}
+interface AnyMutation extends Ref<AnyMutation$1, FunctionVisibility, any, any, any> {}
+interface AnyAction extends Ref<AnyAction$1, FunctionVisibility, any, any, any> {}
+interface AnyPublicQuery extends Ref<AnyQuery$1, "public", any, any, any> {}
+interface AnyPublicMutation extends Ref<AnyMutation$1, "public", any, any, any> {}
+interface AnyPublicAction extends Ref<AnyAction$1, "public", any, any, any> {}
+type GetRuntimeAndFunctionType<Ref_> = Ref_ extends Ref<infer RuntimeAndFunctionType_, infer _FunctionVisibility, infer _Args, infer _Returns, infer _Error> ? RuntimeAndFunctionType_ : never;
+type GetRuntime<Ref_> = Ref_ extends Ref<infer RuntimeAndFunctionType_, infer _FunctionVisibility, infer _Args, infer _Returns, infer _Error> ? GetRuntime$1<RuntimeAndFunctionType_> : never;
+type GetFunctionType<Ref_> = Ref_ extends Ref<infer RuntimeAndFunctionType_, infer _FunctionVisibility, infer _Args, infer _Returns, infer _Error> ? GetFunctionType$1<RuntimeAndFunctionType_> : never;
+type GetFunctionVisibility<Ref_> = Ref_ extends Ref<infer _RuntimeAndFunctionType, infer FunctionVisibility_, infer _Args, infer _Returns, infer _Error> ? FunctionVisibility_ : never;
+type Args<Ref_> = Ref_ extends Ref<infer _RuntimeAndFunctionType, infer _FunctionVisibility, infer Args_, infer _Returns, infer _Error> ? Args_ : never;
+type OptionalArgs<Ref_ extends Any> = keyof Args<Ref_> extends never ? [args?: Args<Ref_>] : [args: Args<Ref_>];
+type Returns<Ref_> = Ref_ extends Ref<infer _RuntimeAndFunctionType, infer _FunctionVisibility, infer _Args, infer Returns_, infer _Error> ? Returns_ : never;
+type Error<Ref_> = Ref_ extends Ref<infer _RuntimeAndFunctionType, infer _FunctionVisibility, infer _Args, infer _Returns, infer Error_> ? Error_ : never;
 type FunctionReference<Ref_ extends Any> = FunctionReference$1<GetFunctionType<Ref_>, GetFunctionVisibility<Ref_>>;
-type FromFunctionSpec<FunctionSpec_ extends AnyWithProps> = Ref<GetRuntimeAndFunctionType$1<FunctionSpec_>, GetFunctionVisibility$1<FunctionSpec_>, Args$1<FunctionSpec_>, Returns$1<FunctionSpec_>>;
+type FromFunctionSpec<FunctionSpec_ extends AnyWithProps> = Ref<GetRuntimeAndFunctionType$1<FunctionSpec_>, GetFunctionVisibility$1<FunctionSpec_>, Args$1<FunctionSpec_>, Returns$1<FunctionSpec_>, Error$1<FunctionSpec_>>;
 declare const make: <FunctionSpec_ extends AnyWithProps>(
 /**
  * The namespace portion of a Convex function name, i.e. the part before the
@@ -40,14 +44,45 @@ declare const make: <FunctionSpec_ extends AnyWithProps>(
 functionNamespace: string, functionSpec: FunctionSpec_) => FromFunctionSpec<FunctionSpec_>;
 declare const getConvexFunctionName: (ref: Any) => string;
 declare const getFunctionReference: <Ref_ extends Any>(ref: Ref_) => FunctionReference<Ref_>;
+declare const hasErrorSchema: (ref: Any) => boolean;
 declare const encodeArgs: <Ref_ extends Any>(ref: Ref_, args: Args<Ref_>) => Effect.Effect<unknown, ParseResult.ParseError>;
 declare const decodeReturns: <Ref_ extends Any>(ref: Ref_, returns: unknown) => Effect.Effect<Returns<Ref_>, ParseResult.ParseError>;
 declare const encodeArgsSync: <Ref_ extends Any>(ref: Ref_, args: Args<Ref_>) => unknown;
 declare const decodeReturnsSync: <Ref_ extends Any>(ref: Ref_, encodedReturns: unknown) => Returns<Ref_>;
-declare 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>;
-};
+declare const isConvexError: (error: unknown) => error is ConvexError<Value>;
+/**
+ * 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.
+ */
+declare const decodeErrorOrElse: <Ref_ extends Any, E>(ref: Ref_, mapUnknownError: (error: unknown) => E) => (error: unknown) => Error<Ref_> | E;
+/**
+ * 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).
+ */
+declare const decodeError: <Ref_ extends Any>(ref: Ref_, encodedError: unknown) => Effect.Effect<Option.Option<Error<Ref_>>, ParseResult.ParseError>;
+/**
+ * Synchronous counterpart to `decodeError`. Throws on schema decode failure;
+ * returns `None` when the ref doesn't declare a typed error.
+ */
+declare const decodeErrorSync: <Ref_ extends Any>(ref: Ref_, encodedError: unknown) => Option.Option<Error<Ref_>>;
+declare const maybeDecodeErrorSync: <Ref_ extends Any>(ref: Ref_, error: unknown) => unknown;
+/**
+ * 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.
+ */
+declare const runWithCodec: <Ref_ extends Any, E = never>(ref: Ref_, args: Args<Ref_>, call: (functionReference: FunctionReference<Ref_>, encodedArgs: unknown) => PromiseLike<unknown>, mapUnknownError?: (error: unknown) => E) => Effect.Effect<Returns<Ref_>, E | Error<Ref_> | ParseResult.ParseError>;
 //#endregion
-export { Any, AnyAction, AnyInternal, AnyMutation, AnyPublic, AnyPublicAction, AnyPublicMutation, AnyPublicQuery, AnyQuery, Args, FromFunctionSpec, FunctionReference, GetFunctionType, GetFunctionVisibility, GetRuntime, GetRuntimeAndFunctionType, Ref, Ref_d_exports, Returns, decodeReturns, decodeReturnsSync, encodeArgs, encodeArgsSync, getConvexFunctionName, getFunctionReference, make, runWithCodec };
+export { Any, AnyAction, AnyInternal, AnyMutation, AnyPublic, AnyPublicAction, AnyPublicMutation, AnyPublicQuery, AnyQuery, Args, Error, FromFunctionSpec, FunctionReference, GetFunctionType, GetFunctionVisibility, GetRuntime, GetRuntimeAndFunctionType, OptionalArgs, Ref, Ref_d_exports, Returns, decodeError, decodeErrorOrElse, decodeErrorSync, decodeReturns, decodeReturnsSync, encodeArgs, encodeArgsSync, getConvexFunctionName, getFunctionReference, hasErrorSchema, isConvexError, make, maybeDecodeErrorSync, runWithCodec };
 //# sourceMappingURL=Ref.d.ts.map

package/dist/Ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Ref.d.ts","names":[],"sources":["../src/Ref.ts"],"mappings":"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"}
+{"version":3,"file":"Ref.d.ts","names":[],"sources":["../src/Ref.ts"],"mappings":"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"}

package/dist/Ref.js

@@ -1,16 +1,23 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import { Effect, Match, Schema } from "effect";
+import { Effect, Match, Option, Schema } from "effect";
 import { makeFunctionReference } from "convex/server";
+import { ConvexError } from "convex/values";
 
 //#region src/Ref.ts
 var Ref_exports = /* @__PURE__ */ __exportAll({
+	decodeError: () => decodeError,
+	decodeErrorOrElse: () => decodeErrorOrElse,
+	decodeErrorSync: () => decodeErrorSync,
 	decodeReturns: () => decodeReturns,
 	decodeReturnsSync: () => decodeReturnsSync,
 	encodeArgs: () => encodeArgs,
 	encodeArgsSync: () => encodeArgsSync,
 	getConvexFunctionName: () => getConvexFunctionName,
 	getFunctionReference: () => getFunctionReference,
+	hasErrorSchema: () => hasErrorSchema,
+	isConvexError: () => isConvexError,
 	make: () => make,
+	maybeDecodeErrorSync: () => maybeDecodeErrorSync,
 	runWithCodec: () => runWithCodec
 });
 const make = (functionNamespace, functionSpec) => ({
@@ -19,23 +26,71 @@ const make = (functionNamespace, functionSpec) => ({
 });
 const getConvexFunctionName = (ref) => `${ref.functionNamespace}:${ref.functionSpec.name}`;
 const getFunctionReference = (ref) => makeFunctionReference(getConvexFunctionName(ref));
-const encodeArgs = (ref, args) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (c) => Schema.encode(c.args)(args)), Match.tag("Convex", () => Effect.succeed(args)), Match.exhaustive);
-const decodeReturns = (ref, returns) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (c) => Schema.decode(c.returns)(returns)), Match.tag("Convex", () => Effect.succeed(returns)), Match.exhaustive);
-const encodeArgsSync = (ref, args) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (c) => Schema.encodeSync(c.args)(args)), Match.tag("Convex", () => args), Match.exhaustive);
-const decodeReturnsSync = (ref, encodedReturns) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (c) => Schema.decodeSync(c.returns)(encodedReturns)), Match.tag("Convex", () => encodedReturns), Match.exhaustive);
-const runWithCodec = (ref, args, f) => Effect.gen(function* () {
+const hasErrorSchema = (ref) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (confectFunctionProvenance) => confectFunctionProvenance.error !== void 0), Match.tag("Convex", () => false), Match.exhaustive);
+const encodeArgs = (ref, args) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (confectFunctionProvenance) => Schema.encode(confectFunctionProvenance.args)(args)), Match.tag("Convex", () => Effect.succeed(args)), Match.exhaustive);
+const decodeReturns = (ref, returns) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (confectFunctionProvenance) => Schema.decode(confectFunctionProvenance.returns)(returns)), Match.tag("Convex", () => Effect.succeed(returns)), Match.exhaustive);
+const encodeArgsSync = (ref, args) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (confectFunctionProvenance) => Schema.encodeSync(confectFunctionProvenance.args)(args)), Match.tag("Convex", () => args), Match.exhaustive);
+const decodeReturnsSync = (ref, encodedReturns) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (confectFunctionProvenance) => Schema.decodeSync(confectFunctionProvenance.returns)(encodedReturns)), Match.tag("Convex", () => encodedReturns), Match.exhaustive);
+const ConvexErrorIdentifier = Symbol.for("ConvexError");
+const isConvexError = (error) => 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.
+*/
+const decodeErrorOrElse = (ref, mapUnknownError) => (error) => {
+	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).
+*/
+const decodeError = (ref, encodedError) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (confectFunctionProvenance) => confectFunctionProvenance.error !== void 0 ? Effect.map(Schema.decode(confectFunctionProvenance.error)(encodedError), Option.some) : Effect.succeed(Option.none())), Match.tag("Convex", () => Effect.succeed(Option.none())), Match.exhaustive);
+/**
+* Synchronous counterpart to `decodeError`. Throws on schema decode failure;
+* returns `None` when the ref doesn't declare a typed error.
+*/
+const decodeErrorSync = (ref, encodedError) => Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (confectFunctionProvenance) => confectFunctionProvenance.error !== void 0 ? Option.some(Schema.decodeSync(confectFunctionProvenance.error)(encodedError)) : Option.none()), Match.tag("Convex", () => Option.none()), Match.exhaustive);
+const maybeDecodeErrorSync = (ref, error) => isConvexError(error) ? Match.value(ref.functionSpec.functionProvenance).pipe(Match.tag("Confect", (confectFunctionProvenance) => confectFunctionProvenance.error !== void 0 ? 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.
+*/
+const runWithCodec = (ref, args, call, mapUnknownError) => Effect.gen(function* () {
 	const functionReference = getFunctionReference(ref);
 	const functionProvenance = ref.functionSpec.functionProvenance;
-	const call = (encodedArgs) => {
-		const result = f(functionReference, encodedArgs);
-		return Effect.isEffect(result) ? result : Effect.promise(() => result);
-	};
-	return yield* Match.value(functionProvenance).pipe(Match.tag("Confect", (confect) => Effect.gen(function* () {
-		const encodedReturns = yield* call(yield* Schema.encode(confect.args)(args));
-		return yield* Schema.decode(confect.returns)(encodedReturns);
-	})), Match.tag("Convex", () => call(args)), Match.exhaustive);
+	const invoke = (encodedArgs) => Effect.tryPromise({
+		try: () => Promise.resolve(call(functionReference, encodedArgs)),
+		catch: (error) => {
+			if (isConvexError(error)) {
+				const decoded = decodeErrorSync(ref, error.data);
+				if (Option.isSome(decoded)) return decoded.value;
+			}
+			if (mapUnknownError !== void 0) return mapUnknownError(error);
+			throw error;
+		}
+	});
+	return yield* Match.value(functionProvenance).pipe(Match.tag("Confect", (confectFunctionProvenance) => Effect.gen(function* () {
+		const encodedReturns = yield* invoke(yield* Schema.encode(confectFunctionProvenance.args)(args));
+		return yield* Schema.decode(confectFunctionProvenance.returns)(encodedReturns);
+	})), Match.tag("Convex", () => invoke(args)), Match.exhaustive);
 });
 
 //#endregion
-export { Ref_exports, decodeReturns, decodeReturnsSync, encodeArgs, encodeArgsSync, getConvexFunctionName, getFunctionReference, make, runWithCodec };
+export { Ref_exports, decodeError, decodeErrorOrElse, decodeErrorSync, decodeReturns, decodeReturnsSync, encodeArgs, encodeArgsSync, getConvexFunctionName, getFunctionReference, hasErrorSchema, isConvexError, make, maybeDecodeErrorSync, runWithCodec };
 //# sourceMappingURL=Ref.js.map

package/dist/Ref.js.map

@@ -1 +1 @@
-{"version":3,"file":"Ref.js","names":[],"sources":["../src/Ref.ts"],"sourcesContent":["import type {\n  FunctionReference as ConvexFunctionReference,\n  FunctionVisibility,\n} from \"convex/server\";\nimport { makeFunctionReference } from \"convex/server\";\nimport type { ParseResult } from \"effect\";\nimport { Effect, Match, Schema } from \"effect\";\nimport type * as FunctionSpec from \"./FunctionSpec\";\nimport type * as RuntimeAndFunctionType from \"./RuntimeAndFunctionType\";\n\nexport interface Ref<\n  _RuntimeAndFunctionType extends RuntimeAndFunctionType.RuntimeAndFunctionType,\n  _FunctionVisibility extends FunctionVisibility,\n  _Args,\n  _Returns,\n> {\n  readonly _RuntimeAndFunctionType?: _RuntimeAndFunctionType;\n  readonly _FunctionVisibility?: _FunctionVisibility;\n  readonly _Args?: _Args;\n  readonly _Returns?: _Returns;\n  /** @internal */\n  readonly functionSpec: FunctionSpec.AnyWithProps;\n  /** @internal */\n  readonly functionNamespace: string;\n}\n\nexport interface Any extends Ref<any, any, any, any> {}\n\nexport interface AnyInternal extends Ref<any, \"internal\", any, any> {}\n\nexport interface AnyPublic extends Ref<any, \"public\", any, any> {}\n\nexport interface AnyQuery extends Ref<\n  RuntimeAndFunctionType.AnyQuery,\n  FunctionVisibility,\n  any,\n  any\n> {}\n\nexport interface AnyMutation extends Ref<\n  RuntimeAndFunctionType.AnyMutation,\n  FunctionVisibility,\n  any,\n  any\n> {}\n\nexport interface AnyAction extends Ref<\n  RuntimeAndFunctionType.AnyAction,\n  FunctionVisibility,\n  any,\n  any\n> {}\n\nexport interface AnyPublicQuery extends Ref<\n  RuntimeAndFunctionType.AnyQuery,\n  \"public\",\n  any,\n  any\n> {}\n\nexport interface AnyPublicMutation extends Ref<\n  RuntimeAndFunctionType.AnyMutation,\n  \"public\",\n  any,\n  any\n> {}\n\nexport interface AnyPublicAction extends Ref<\n  RuntimeAndFunctionType.AnyAction,\n  \"public\",\n  any,\n  any\n> {}\n\nexport type GetRuntimeAndFunctionType<Ref_> =\n  Ref_ extends Ref<\n    infer RuntimeAndFunctionType_,\n    infer _FunctionVisibility,\n    infer _Args,\n    infer _Returns\n  >\n    ? RuntimeAndFunctionType_\n    : never;\n\nexport type GetRuntime<Ref_> =\n  Ref_ extends Ref<\n    infer RuntimeAndFunctionType_,\n    infer _FunctionVisibility,\n    infer _Args,\n    infer _Returns\n  >\n    ? RuntimeAndFunctionType.GetRuntime<RuntimeAndFunctionType_>\n    : never;\n\nexport type GetFunctionType<Ref_> =\n  Ref_ extends Ref<\n    infer RuntimeAndFunctionType_,\n    infer _FunctionVisibility,\n    infer _Args,\n    infer _Returns\n  >\n    ? RuntimeAndFunctionType.GetFunctionType<RuntimeAndFunctionType_>\n    : never;\n\nexport type GetFunctionVisibility<Ref_> =\n  Ref_ extends Ref<\n    infer _RuntimeAndFunctionType,\n    infer FunctionVisibility_,\n    infer _Args,\n    infer _Returns\n  >\n    ? FunctionVisibility_\n    : never;\n\nexport type Args<Ref_> =\n  Ref_ extends Ref<\n    infer _RuntimeAndFunctionType,\n    infer _FunctionVisibility,\n    infer Args_,\n    infer _Returns\n  >\n    ? Args_\n    : never;\n\nexport type Returns<Ref_> =\n  Ref_ extends Ref<\n    infer _RuntimeAndFunctionType,\n    infer _FunctionVisibility,\n    infer _Args,\n    infer Returns_\n  >\n    ? Returns_\n    : never;\n\nexport type FunctionReference<Ref_ extends Any> = ConvexFunctionReference<\n  GetFunctionType<Ref_>,\n  GetFunctionVisibility<Ref_>\n>;\n\nexport type FromFunctionSpec<FunctionSpec_ extends FunctionSpec.AnyWithProps> =\n  Ref<\n    FunctionSpec.GetRuntimeAndFunctionType<FunctionSpec_>,\n    FunctionSpec.GetFunctionVisibility<FunctionSpec_>,\n    FunctionSpec.Args<FunctionSpec_>,\n    FunctionSpec.Returns<FunctionSpec_>\n  >;\n\nexport const make = <FunctionSpec_ extends FunctionSpec.AnyWithProps>(\n  /**\n   * The namespace portion of a Convex function name, i.e. the part before the\n   * colon. For example, for `myGroupDir/myGroupMod:myFunc` this would be\n   * `myGroupDir/myGroupMod`.\n   */\n  functionNamespace: string,\n  functionSpec: FunctionSpec_,\n): FromFunctionSpec<FunctionSpec_> => ({ functionSpec, functionNamespace });\n\nexport const getConvexFunctionName = (ref: Any): string =>\n  `${ref.functionNamespace}:${ref.functionSpec.name}`;\n\nexport const getFunctionReference = <Ref_ extends Any>(\n  ref: Ref_,\n): FunctionReference<Ref_> =>\n  makeFunctionReference(getConvexFunctionName(ref)) as FunctionReference<Ref_>;\n\nexport const encodeArgs = <Ref_ extends Any>(\n  ref: Ref_,\n  args: Args<Ref_>,\n): Effect.Effect<unknown, ParseResult.ParseError> =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\"Confect\", (c) => Schema.encode(c.args)(args)),\n    Match.tag(\"Convex\", () => Effect.succeed(args)),\n    Match.exhaustive,\n  );\n\nexport const decodeReturns = <Ref_ extends Any>(\n  ref: Ref_,\n  returns: unknown,\n): Effect.Effect<Returns<Ref_>, ParseResult.ParseError> =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\"Confect\", (c) => Schema.decode(c.returns)(returns)),\n    Match.tag(\"Convex\", () => Effect.succeed(returns)),\n    Match.exhaustive,\n  );\n\nexport const encodeArgsSync = <Ref_ extends Any>(\n  ref: Ref_,\n  args: Args<Ref_>,\n): unknown =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\"Confect\", (c) => Schema.encodeSync(c.args)(args)),\n    Match.tag(\"Convex\", () => args),\n    Match.exhaustive,\n  );\n\nexport const decodeReturnsSync = <Ref_ extends Any>(\n  ref: Ref_,\n  encodedReturns: unknown,\n): Returns<Ref_> =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\"Confect\", (c) => Schema.decodeSync(c.returns)(encodedReturns)),\n    Match.tag(\"Convex\", () => encodedReturns),\n    Match.exhaustive,\n  ) as Returns<Ref_>;\n\nexport const runWithCodec: {\n  <Ref_ extends Any, E>(\n    ref: Ref_,\n    args: Args<Ref_>,\n    f: (\n      functionReference: FunctionReference<Ref_>,\n      encodedArgs: unknown,\n    ) => Effect.Effect<unknown, E>,\n  ): Effect.Effect<Returns<Ref_>, E | ParseResult.ParseError>;\n  <Ref_ extends Any>(\n    ref: Ref_,\n    args: Args<Ref_>,\n    f: (\n      functionReference: FunctionReference<Ref_>,\n      encodedArgs: unknown,\n    ) => PromiseLike<unknown>,\n  ): Effect.Effect<Returns<Ref_>, ParseResult.ParseError>;\n} = <Ref_ extends Any, E>(\n  ref: Ref_,\n  args: Args<Ref_>,\n  f: (\n    functionReference: FunctionReference<Ref_>,\n    encodedArgs: unknown,\n  ) => Effect.Effect<unknown, E> | PromiseLike<unknown>,\n): Effect.Effect<Returns<Ref_>, E | ParseResult.ParseError> =>\n  Effect.gen(function* () {\n    const functionReference = getFunctionReference(ref);\n    const functionProvenance = ref.functionSpec.functionProvenance;\n    const call = (encodedArgs: unknown) => {\n      const result = f(functionReference, encodedArgs);\n      return Effect.isEffect(result) ? result : Effect.promise(() => result);\n    };\n    return yield* Match.value(functionProvenance).pipe(\n      Match.tag(\"Confect\", (confect) =>\n        Effect.gen(function* () {\n          const encodedArgs = yield* Schema.encode(confect.args)(args);\n          const encodedReturns = yield* call(encodedArgs);\n          return yield* Schema.decode(confect.returns)(encodedReturns);\n        }),\n      ),\n      Match.tag(\"Convex\", () => call(args)),\n      Match.exhaustive,\n    );\n  });\n"],"mappings":";;;;;;;;;;;;;;;AAmJA,MAAa,QAMX,mBACA,kBACqC;CAAE;CAAc;CAAmB;AAE1E,MAAa,yBAAyB,QACpC,GAAG,IAAI,kBAAkB,GAAG,IAAI,aAAa;AAE/C,MAAa,wBACX,QAEA,sBAAsB,sBAAsB,IAAI,CAAC;AAEnD,MAAa,cACX,KACA,SAEA,MAAM,MAAM,IAAI,aAAa,mBAAmB,CAAC,KAC/C,MAAM,IAAI,YAAY,MAAM,OAAO,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,EACxD,MAAM,IAAI,gBAAgB,OAAO,QAAQ,KAAK,CAAC,EAC/C,MAAM,WACP;AAEH,MAAa,iBACX,KACA,YAEA,MAAM,MAAM,IAAI,aAAa,mBAAmB,CAAC,KAC/C,MAAM,IAAI,YAAY,MAAM,OAAO,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC9D,MAAM,IAAI,gBAAgB,OAAO,QAAQ,QAAQ,CAAC,EAClD,MAAM,WACP;AAEH,MAAa,kBACX,KACA,SAEA,MAAM,MAAM,IAAI,aAAa,mBAAmB,CAAC,KAC/C,MAAM,IAAI,YAAY,MAAM,OAAO,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,EAC5D,MAAM,IAAI,gBAAgB,KAAK,EAC/B,MAAM,WACP;AAEH,MAAa,qBACX,KACA,mBAEA,MAAM,MAAM,IAAI,aAAa,mBAAmB,CAAC,KAC/C,MAAM,IAAI,YAAY,MAAM,OAAO,WAAW,EAAE,QAAQ,CAAC,eAAe,CAAC,EACzE,MAAM,IAAI,gBAAgB,eAAe,EACzC,MAAM,WACP;AAEH,MAAa,gBAkBX,KACA,MACA,MAKA,OAAO,IAAI,aAAa;CACtB,MAAM,oBAAoB,qBAAqB,IAAI;CACnD,MAAM,qBAAqB,IAAI,aAAa;CAC5C,MAAM,QAAQ,gBAAyB;EACrC,MAAM,SAAS,EAAE,mBAAmB,YAAY;AAChD,SAAO,OAAO,SAAS,OAAO,GAAG,SAAS,OAAO,cAAc,OAAO;;AAExE,QAAO,OAAO,MAAM,MAAM,mBAAmB,CAAC,KAC5C,MAAM,IAAI,YAAY,YACpB,OAAO,IAAI,aAAa;EAEtB,MAAM,iBAAiB,OAAO,KADV,OAAO,OAAO,OAAO,QAAQ,KAAK,CAAC,KAAK,CACb;AAC/C,SAAO,OAAO,OAAO,OAAO,QAAQ,QAAQ,CAAC,eAAe;GAC5D,CACH,EACD,MAAM,IAAI,gBAAgB,KAAK,KAAK,CAAC,EACrC,MAAM,WACP;EACD"}
+{"version":3,"file":"Ref.js","names":[],"sources":["../src/Ref.ts"],"sourcesContent":["import type {\n  FunctionReference as ConvexFunctionReference,\n  FunctionVisibility,\n} from \"convex/server\";\nimport { makeFunctionReference } from \"convex/server\";\nimport type { Value } from \"convex/values\";\nimport { ConvexError } from \"convex/values\";\nimport type { ParseResult } from \"effect\";\nimport { Effect, Match, Option, Schema } from \"effect\";\nimport type * as FunctionSpec from \"./FunctionSpec\";\nimport type * as RuntimeAndFunctionType from \"./RuntimeAndFunctionType\";\n\nexport interface Ref<\n  _RuntimeAndFunctionType extends RuntimeAndFunctionType.RuntimeAndFunctionType,\n  _FunctionVisibility extends FunctionVisibility,\n  _Args,\n  _Returns,\n  _Error = never,\n> {\n  readonly _RuntimeAndFunctionType?: _RuntimeAndFunctionType;\n  readonly _FunctionVisibility?: _FunctionVisibility;\n  readonly _Args?: _Args;\n  readonly _Returns?: _Returns;\n  readonly _Error?: _Error;\n  /** @internal */\n  readonly functionSpec: FunctionSpec.AnyWithProps;\n  /** @internal */\n  readonly functionNamespace: string;\n}\n\nexport interface Any extends Ref<any, any, any, any, any> {}\n\nexport interface AnyInternal extends Ref<any, \"internal\", any, any, any> {}\n\nexport interface AnyPublic extends Ref<any, \"public\", any, any, any> {}\n\nexport interface AnyQuery extends Ref<\n  RuntimeAndFunctionType.AnyQuery,\n  FunctionVisibility,\n  any,\n  any,\n  any\n> {}\n\nexport interface AnyMutation extends Ref<\n  RuntimeAndFunctionType.AnyMutation,\n  FunctionVisibility,\n  any,\n  any,\n  any\n> {}\n\nexport interface AnyAction extends Ref<\n  RuntimeAndFunctionType.AnyAction,\n  FunctionVisibility,\n  any,\n  any,\n  any\n> {}\n\nexport interface AnyPublicQuery extends Ref<\n  RuntimeAndFunctionType.AnyQuery,\n  \"public\",\n  any,\n  any,\n  any\n> {}\n\nexport interface AnyPublicMutation extends Ref<\n  RuntimeAndFunctionType.AnyMutation,\n  \"public\",\n  any,\n  any,\n  any\n> {}\n\nexport interface AnyPublicAction extends Ref<\n  RuntimeAndFunctionType.AnyAction,\n  \"public\",\n  any,\n  any,\n  any\n> {}\n\nexport type GetRuntimeAndFunctionType<Ref_> =\n  Ref_ extends Ref<\n    infer RuntimeAndFunctionType_,\n    infer _FunctionVisibility,\n    infer _Args,\n    infer _Returns,\n    infer _Error\n  >\n    ? RuntimeAndFunctionType_\n    : never;\n\nexport type GetRuntime<Ref_> =\n  Ref_ extends Ref<\n    infer RuntimeAndFunctionType_,\n    infer _FunctionVisibility,\n    infer _Args,\n    infer _Returns,\n    infer _Error\n  >\n    ? RuntimeAndFunctionType.GetRuntime<RuntimeAndFunctionType_>\n    : never;\n\nexport type GetFunctionType<Ref_> =\n  Ref_ extends Ref<\n    infer RuntimeAndFunctionType_,\n    infer _FunctionVisibility,\n    infer _Args,\n    infer _Returns,\n    infer _Error\n  >\n    ? RuntimeAndFunctionType.GetFunctionType<RuntimeAndFunctionType_>\n    : never;\n\nexport type GetFunctionVisibility<Ref_> =\n  Ref_ extends Ref<\n    infer _RuntimeAndFunctionType,\n    infer FunctionVisibility_,\n    infer _Args,\n    infer _Returns,\n    infer _Error\n  >\n    ? FunctionVisibility_\n    : never;\n\nexport type Args<Ref_> =\n  Ref_ extends Ref<\n    infer _RuntimeAndFunctionType,\n    infer _FunctionVisibility,\n    infer Args_,\n    infer _Returns,\n    infer _Error\n  >\n    ? Args_\n    : never;\n\nexport type OptionalArgs<Ref_ extends Any> = keyof Args<Ref_> extends never\n  ? [args?: Args<Ref_>]\n  : [args: Args<Ref_>];\n\nexport type Returns<Ref_> =\n  Ref_ extends Ref<\n    infer _RuntimeAndFunctionType,\n    infer _FunctionVisibility,\n    infer _Args,\n    infer Returns_,\n    infer _Error\n  >\n    ? Returns_\n    : never;\n\nexport type Error<Ref_> =\n  Ref_ extends Ref<\n    infer _RuntimeAndFunctionType,\n    infer _FunctionVisibility,\n    infer _Args,\n    infer _Returns,\n    infer Error_\n  >\n    ? Error_\n    : never;\n\nexport type FunctionReference<Ref_ extends Any> = ConvexFunctionReference<\n  GetFunctionType<Ref_>,\n  GetFunctionVisibility<Ref_>\n>;\n\nexport type FromFunctionSpec<FunctionSpec_ extends FunctionSpec.AnyWithProps> =\n  Ref<\n    FunctionSpec.GetRuntimeAndFunctionType<FunctionSpec_>,\n    FunctionSpec.GetFunctionVisibility<FunctionSpec_>,\n    FunctionSpec.Args<FunctionSpec_>,\n    FunctionSpec.Returns<FunctionSpec_>,\n    FunctionSpec.Error<FunctionSpec_>\n  >;\n\nexport const make = <FunctionSpec_ extends FunctionSpec.AnyWithProps>(\n  /**\n   * The namespace portion of a Convex function name, i.e. the part before the\n   * colon. For example, for `myGroupDir/myGroupMod:myFunc` this would be\n   * `myGroupDir/myGroupMod`.\n   */\n  functionNamespace: string,\n  functionSpec: FunctionSpec_,\n): FromFunctionSpec<FunctionSpec_> => ({ functionSpec, functionNamespace });\n\nexport const getConvexFunctionName = (ref: Any): string =>\n  `${ref.functionNamespace}:${ref.functionSpec.name}`;\n\nexport const getFunctionReference = <Ref_ extends Any>(\n  ref: Ref_,\n): FunctionReference<Ref_> =>\n  makeFunctionReference(getConvexFunctionName(ref)) as FunctionReference<Ref_>;\n\nexport const hasErrorSchema = (ref: Any): boolean =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\n      \"Confect\",\n      (confectFunctionProvenance) =>\n        confectFunctionProvenance.error !== undefined,\n    ),\n    Match.tag(\"Convex\", () => false),\n    Match.exhaustive,\n  );\n\nexport const encodeArgs = <Ref_ extends Any>(\n  ref: Ref_,\n  args: Args<Ref_>,\n): Effect.Effect<unknown, ParseResult.ParseError> =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\"Confect\", (confectFunctionProvenance) =>\n      Schema.encode(confectFunctionProvenance.args)(args),\n    ),\n    Match.tag(\"Convex\", () => Effect.succeed(args)),\n    Match.exhaustive,\n  );\n\nexport const decodeReturns = <Ref_ extends Any>(\n  ref: Ref_,\n  returns: unknown,\n): Effect.Effect<Returns<Ref_>, ParseResult.ParseError> =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\"Confect\", (confectFunctionProvenance) =>\n      Schema.decode(confectFunctionProvenance.returns)(returns),\n    ),\n    Match.tag(\"Convex\", () => Effect.succeed(returns)),\n    Match.exhaustive,\n  );\n\nexport const encodeArgsSync = <Ref_ extends Any>(\n  ref: Ref_,\n  args: Args<Ref_>,\n): unknown =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\"Confect\", (confectFunctionProvenance) =>\n      Schema.encodeSync(confectFunctionProvenance.args)(args),\n    ),\n    Match.tag(\"Convex\", () => args),\n    Match.exhaustive,\n  );\n\nexport const decodeReturnsSync = <Ref_ extends Any>(\n  ref: Ref_,\n  encodedReturns: unknown,\n): Returns<Ref_> =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\"Confect\", (confectFunctionProvenance) =>\n      Schema.decodeSync(confectFunctionProvenance.returns)(encodedReturns),\n    ),\n    Match.tag(\"Convex\", () => encodedReturns),\n    Match.exhaustive,\n  ) as Returns<Ref_>;\n\nconst ConvexErrorIdentifier = Symbol.for(\"ConvexError\");\n\nexport const isConvexError = (error: unknown): error is ConvexError<Value> =>\n  error instanceof ConvexError ||\n  (typeof error === \"object\" &&\n    error !== null &&\n    ConvexErrorIdentifier in error);\n\n/**\n * Build a callback-style handler that decodes the ref's typed error from a\n * caught `ConvexError`, or else forwards the value to `mapUnknownError`. The\n * fallback is also invoked when the input *is* a `ConvexError` but the ref\n * doesn't declare a typed-error schema—by definition such a value falls\n * outside the ref's error contract. Useful when adapting non-Effect APIs (e.g.\n * emitter callbacks for streamed subscriptions) to the same error semantics\n * that `runWithCodec` provides.\n */\nexport const decodeErrorOrElse =\n  <Ref_ extends Any, E>(ref: Ref_, mapUnknownError: (error: unknown) => E) =>\n  (error: unknown): Error<Ref_> | E => {\n    if (isConvexError(error)) {\n      const decoded = decodeErrorSync(ref, error.data);\n      if (Option.isSome(decoded)) {\n        return decoded.value;\n      }\n    }\n    return mapUnknownError(error);\n  };\n\n/**\n * Decode `encodedError` against the ref's error schema. Returns `None` if the\n * ref doesn't declare a typed error (Confect ref without an `error` schema, or\n * a Convex-provenance ref)—by definition there's nothing to decode the value\n * into, and the caller is responsible for deciding what to do (typically:\n * surface the original value as a defect).\n */\nexport const decodeError = <Ref_ extends Any>(\n  ref: Ref_,\n  encodedError: unknown,\n): Effect.Effect<Option.Option<Error<Ref_>>, ParseResult.ParseError> =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\"Confect\", (confectFunctionProvenance) =>\n      confectFunctionProvenance.error !== undefined\n        ? Effect.map(\n            Schema.decode(confectFunctionProvenance.error)(encodedError),\n            Option.some,\n          )\n        : Effect.succeed(Option.none<Error<Ref_>>()),\n    ),\n    Match.tag(\"Convex\", () => Effect.succeed(Option.none<Error<Ref_>>())),\n    Match.exhaustive,\n  );\n\n/**\n * Synchronous counterpart to `decodeError`. Throws on schema decode failure;\n * returns `None` when the ref doesn't declare a typed error.\n */\nexport const decodeErrorSync = <Ref_ extends Any>(\n  ref: Ref_,\n  encodedError: unknown,\n): Option.Option<Error<Ref_>> =>\n  Match.value(ref.functionSpec.functionProvenance).pipe(\n    Match.tag(\"Confect\", (confectFunctionProvenance) =>\n      confectFunctionProvenance.error !== undefined\n        ? Option.some(\n            Schema.decodeSync(confectFunctionProvenance.error)(\n              encodedError,\n            ) as Error<Ref_>,\n          )\n        : Option.none<Error<Ref_>>(),\n    ),\n    Match.tag(\"Convex\", () => Option.none<Error<Ref_>>()),\n    Match.exhaustive,\n  );\n\nexport const maybeDecodeErrorSync = <Ref_ extends Any>(\n  ref: Ref_,\n  error: unknown,\n): unknown =>\n  isConvexError(error)\n    ? Match.value(ref.functionSpec.functionProvenance).pipe(\n        Match.tag(\"Confect\", (confectFunctionProvenance) =>\n          confectFunctionProvenance.error !== undefined\n            ? Schema.decodeSync(confectFunctionProvenance.error)(error.data)\n            : error,\n        ),\n        Match.tag(\"Convex\", () => error),\n        Match.exhaustive,\n      )\n    : error;\n\n/**\n * Encode args via the ref's args schema, invoke `call`, decode returns via the\n * ref's returns schema, and translate any thrown `ConvexError` into the ref's\n * typed error. Anything else the Promise rejects with—network failures,\n * server-side runtime errors, validation failures, etc.—is passed to\n * `mapUnknownError` to be turned into a typed `E`, or surfaced as a defect when\n * no handler is provided.\n */\nexport const runWithCodec = <Ref_ extends Any, E = never>(\n  ref: Ref_,\n  args: Args<Ref_>,\n  call: (\n    functionReference: FunctionReference<Ref_>,\n    encodedArgs: unknown,\n  ) => PromiseLike<unknown>,\n  mapUnknownError?: (error: unknown) => E,\n): Effect.Effect<Returns<Ref_>, E | Error<Ref_> | ParseResult.ParseError> =>\n  Effect.gen(function* () {\n    const functionReference = getFunctionReference(ref);\n    const functionProvenance = ref.functionSpec.functionProvenance;\n    const invoke = (\n      encodedArgs: unknown,\n    ): Effect.Effect<unknown, Error<Ref_> | E> =>\n      Effect.tryPromise({\n        try: () => Promise.resolve(call(functionReference, encodedArgs)),\n        catch: (error): Error<Ref_> | E => {\n          if (isConvexError(error)) {\n            const decoded = decodeErrorSync(ref, error.data);\n            if (Option.isSome(decoded)) {\n              return decoded.value;\n            }\n          }\n          if (mapUnknownError !== undefined) {\n            return mapUnknownError(error);\n          }\n          throw error;\n        },\n      });\n    return yield* Match.value(functionProvenance).pipe(\n      Match.tag(\"Confect\", (confectFunctionProvenance) =>\n        Effect.gen(function* () {\n          const encodedArgs = yield* Schema.encode(\n            confectFunctionProvenance.args,\n          )(args);\n          const encodedReturns = yield* invoke(encodedArgs);\n          return yield* Schema.decode(confectFunctionProvenance.returns)(\n            encodedReturns,\n          );\n        }),\n      ),\n      Match.tag(\"Convex\", () => invoke(args)),\n      Match.exhaustive,\n    );\n  });\n"],"mappings":"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"}

package/dist/Spec.d.ts

@@ -10,17 +10,17 @@ type TypeId = typeof TypeId;
 declare const isSpec: (u: unknown) => u is AnyWithProps;
 declare const isConvexSpec: (u: unknown) => u is AnyWithPropsWithRuntime<"Convex">;
 declare const isNodeSpec: (u: unknown) => u is AnyWithPropsWithRuntime<"Node">;
-interface Spec<Runtime$2 extends Runtime, Groups_ extends AnyWithPropsWithRuntime$1<Runtime$2> = never> {
+interface Spec<Runtime$1 extends Runtime, Groups_ extends AnyWithPropsWithRuntime$1<Runtime$1> = never> {
   readonly [TypeId]: TypeId;
-  readonly runtime: Runtime$2;
+  readonly runtime: Runtime$1;
   readonly groups: { [GroupName in Name<Groups_>]: WithName<Groups_, GroupName> };
-  add<Group extends AnyWithPropsWithRuntime$1<Runtime$2>>(group: Group): Spec<Runtime$2, Groups_ | Group>;
+  add<Group extends AnyWithPropsWithRuntime$1<Runtime$1>>(group: Group): Spec<Runtime$1, Groups_ | Group>;
 }
 interface Any {
   readonly [TypeId]: TypeId;
 }
 interface AnyWithProps extends Spec<Runtime, AnyWithProps$1> {}
-interface AnyWithPropsWithRuntime<Runtime$1 extends Runtime> extends Spec<Runtime$1, AnyWithPropsWithRuntime$1<Runtime$1>> {}
+interface AnyWithPropsWithRuntime<Runtime$2 extends Runtime> extends Spec<Runtime$2, AnyWithPropsWithRuntime$1<Runtime$2>> {}
 type Groups<Spec_ extends AnyWithProps> = Spec_["groups"][keyof Spec_["groups"]];
 declare const make: () => Spec<"Convex">;
 declare const makeNode: () => Spec<"Node">;

package/dist/Types.d.ts

@@ -14,11 +14,12 @@ type IsValueLiteral<Vl> = [Vl] extends [never] ? never : IsUnion<Vl> extends tru
  * Only checks for records with string keys.
  */
 type IsRecord<T> = [T] extends [never] ? false : IsUnion<T> extends true ? false : T extends Record<string, infer V> ? string extends keyof T ? keyof T extends string ? T extends Record<string, V> ? Record<string, V> extends T ? true : false : false : false : false : false;
-type DeepMutable<T> = IsAny<T> extends true ? any : T extends Brand.Brand<any> | GenericId<any> ? T : T extends ReadonlyMap<infer K, infer V> ? Map<DeepMutable<K>, DeepMutable<V>> : T extends ReadonlySet<infer V> ? Set<DeepMutable<V>> : [keyof T] extends [never] ? T : { -readonly [K in keyof T]: DeepMutable<T[K]> };
+type DeepMutable<T> = IsAny<T> extends true ? any : T extends NonRecursiveLeaf ? T : T extends ReadonlyMap<infer K, infer V> ? Map<DeepMutable<K>, DeepMutable<V>> : T extends ReadonlySet<infer V> ? Set<DeepMutable<V>> : [keyof T] extends [never] ? T : { -readonly [K in keyof T]: DeepMutable<T[K]> };
 type TypeError<Message extends string, T = never> = [Message, T];
 type TypeDefect<Message extends string, T = never> = [Message, T];
 type IsRecursive<T> = true extends DetectCycle<T> ? true : false;
-type DetectCycle<T, Cache extends any[] = []> = IsAny<T> extends true ? false : [T] extends [any] ? T extends Cache[number] ? true : T extends Array<infer U> ? DetectCycle<U, [...Cache, T]> : T extends Map<infer _U, infer V> ? DetectCycle<V, [...Cache, T]> : T extends Set<infer U> ? DetectCycle<U, [...Cache, T]> : T extends object ? true extends { [K in keyof T]: DetectCycle<T[K], [...Cache, T]> }[keyof T] ? true : false : false : never;
+type NonRecursiveLeaf = Brand.Brand<any> | GenericId<any> | ArrayBuffer;
+type DetectCycle<T, Cache extends any[] = []> = IsAny<T> extends true ? false : [T] extends [any] ? T extends NonRecursiveLeaf ? false : T extends Cache[number] ? true : T extends Array<infer U> ? DetectCycle<U, [...Cache, T]> : T extends Map<infer _U, infer V> ? DetectCycle<V, [...Cache, T]> : T extends Set<infer U> ? DetectCycle<U, [...Cache, T]> : T extends object ? true extends { [K in keyof T]: DetectCycle<T[K], [...Cache, T]> }[keyof T] ? true : false : false : never;
 type UnionToTuple<t> = _unionToTuple<t, []> extends infer result ? conform<result, t[]> : never;
 type _unionToTuple<t, result extends unknown[]> = getLastBranch<t> extends infer current ? [t] extends [never] ? result : _unionToTuple<Exclude<t, current>, [current, ...result]> : never;
 type getLastBranch<t> = intersectUnion<t extends unknown ? (x: t) => void : never> extends ((x: infer branch) => void) ? branch : never;

package/dist/Types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Types.d.ts","names":[],"sources":["../src/Types.ts"],"mappings":";;;;;;;;KAUY,UAAA,oBAA8B,CAAA,eAC7B,IAAA,CAAK,CAAA,EAAG,CAAA;AAAA,KAET,KAAA,oBAAyB,CAAA;AAAA,KAEzB,OAAA,cAAqB,CAAA,GAAI,CAAA,IAAK,CAAA,oBACrC,CAAA,WAAY,CAAA;AAAA,KAML,cAAA,QAAsB,EAAA,4BAE9B,OAAA,CAAQ,EAAA,0BAEL,EAAA,mEACmB,EAAA,8BAEE,EAAA,+BAEG,EAAA,8BAEC,EAAA;;;;KAQpB,QAAA,OAAe,CAAA,4BAEvB,OAAA,CAAQ,CAAA,yBAEN,CAAA,SAAU,MAAA,yCACa,CAAA,SACb,CAAA,kBACJ,CAAA,SAAU,MAAA,SAAe,CAAA,IACvB,MAAA,SAAe,CAAA,UAAW,CAAA;AAAA,KAQ5B,WAAA,MACV,KAAA,CAAM,CAAA,uBAEF,CAAA,SAAU,KAAA,CAAM,KAAA,QAAa,SAAA,QAC3B,CAAA,GACA,CAAA,SAAU,WAAA,qBACR,GAAA,CAAI,WAAA,CAAY,CAAA,GAAI,WAAA,CAAY,CAAA,KAChC,CAAA,SAAU,WAAA,YACR,GAAA,CAAI,WAAA,CAAY,CAAA,YACT,CAAA,oBACL,CAAA,2BACwB,CAAA,GAAI,WAAA,CAAY,CAAA,CAAE,CAAA;AAAA,KAE5C,SAAA,uCAAgD,OAAA,EAAS,CAAA;AAAA,KAEzD,UAAA,uCAAiD,OAAA,EAAS,CAAA;AAAA,KAE1D,WAAA,mBAA8B,WAAA,CAAY,CAAA;AAAA,KAEjD,WAAA,gCACH,KAAA,CAAM,CAAA,0BAED,CAAA,kBACC,CAAA,SAAU,KAAA,kBAER,CAAA,SAAU,KAAA,YACR,WAAA,CAAY,CAAA,MAAO,KAAA,EAAO,CAAA,KAC1B,CAAA,SAAU,GAAA,sBACR,WAAA,CAAY,CAAA,MAAO,KAAA,EAAO,CAAA,KAC1B,CAAA,SAAU,GAAA,YACR,WAAA,CAAY,CAAA,MAAO,KAAA,EAAO,CAAA,KAC1B,CAAA,6CAEgB,CAAA,GAAI,WAAA,CAAY,CAAA,CAAE,CAAA,OAAQ,KAAA,EAAO,CAAA,WACvC,CAAA;AAAA,KAYd,YAAA,MACV,aAAA,CAAc,CAAA,6BAA8B,OAAA,CAAQ,MAAA,EAAQ,CAAA;AAAA,KAEzD,aAAA,gCACH,aAAA,CAAc,CAAA,2BACT,CAAA,oBACC,MAAA,GACA,aAAA,CAAc,OAAA,CAAQ,CAAA,EAAG,OAAA,IAAW,OAAA,KAAY,MAAA;AAAA,KAGnD,aAAA,MACH,cAAA,CAAe,CAAA,oBAAqB,CAAA,EAAG,CAAA,6BACrC,CAAA,2BAEE,MAAA;AAAA,KAGD,cAAA,OAAqB,CAAA,oBAAqB,CAAA,EAAG,CAAA,6BAChD,CAAA,iCAEE,YAAA;AAAA,KAGC,OAAA,YAAmB,CAAA,SAAU,IAAA,GAAO,CAAA,GAAI,IAAA;AAAA,KAMjC,oBAAA,yBACc,gBAAA,gBACV,qBAAA,CAAsB,eAAA,yBAElC,CAAA,yCACA,IAAA,2CAEgB,IAAA,GAAO,sBAAA,CACjB,cAAA,CAAe,eAAA,EAAiB,KAAA,GAChC,IAAA,CAAK,CAAA;AAAA,KAOH,kBAAA,mBAAqC,gBAAA;EAC/C,GAAA,EAAK,qBAAA,CAAsB,SAAA;EAC3B,KAAA,EAAO,qBAAA,CAAsB,SAAA;AAAA"}
+{"version":3,"file":"Types.d.ts","names":[],"sources":["../src/Types.ts"],"mappings":";;;;;;;;KAUY,UAAA,oBAA8B,CAAA,eAC7B,IAAA,CAAK,CAAA,EAAG,CAAA;AAAA,KAET,KAAA,oBAAyB,CAAA;AAAA,KAEzB,OAAA,cAAqB,CAAA,GAAI,CAAA,IAAK,CAAA,oBACrC,CAAA,WAAY,CAAA;AAAA,KAML,cAAA,QAAsB,EAAA,4BAE9B,OAAA,CAAQ,EAAA,0BAEL,EAAA,mEACmB,EAAA,8BAEE,EAAA,+BAEG,EAAA,8BAEC,EAAA;;;;KAQpB,QAAA,OAAe,CAAA,4BAEvB,OAAA,CAAQ,CAAA,yBAEN,CAAA,SAAU,MAAA,yCACa,CAAA,SACb,CAAA,kBACJ,CAAA,SAAU,MAAA,SAAe,CAAA,IACvB,MAAA,SAAe,CAAA,UAAW,CAAA;AAAA,KAQ5B,WAAA,MACV,KAAA,CAAM,CAAA,uBAEF,CAAA,SAAU,gBAAA,GACR,CAAA,GACA,CAAA,SAAU,WAAA,qBACR,GAAA,CAAI,WAAA,CAAY,CAAA,GAAI,WAAA,CAAY,CAAA,KAChC,CAAA,SAAU,WAAA,YACR,GAAA,CAAI,WAAA,CAAY,CAAA,YACT,CAAA,oBACL,CAAA,2BACwB,CAAA,GAAI,WAAA,CAAY,CAAA,CAAE,CAAA;AAAA,KAE5C,SAAA,uCAAgD,OAAA,EAAS,CAAA;AAAA,KAEzD,UAAA,uCAAiD,OAAA,EAAS,CAAA;AAAA,KAE1D,WAAA,mBAA8B,WAAA,CAAY,CAAA;AAAA,KAEjD,gBAAA,GAAmB,KAAA,CAAM,KAAA,QAAa,SAAA,QAAiB,WAAA;AAAA,KAEvD,WAAA,gCACH,KAAA,CAAM,CAAA,0BAED,CAAA,kBACC,CAAA,SAAU,gBAAA,WAER,CAAA,SAAU,KAAA,kBAER,CAAA,SAAU,KAAA,YACR,WAAA,CAAY,CAAA,MAAO,KAAA,EAAO,CAAA,KAC1B,CAAA,SAAU,GAAA,sBACR,WAAA,CAAY,CAAA,MAAO,KAAA,EAAO,CAAA,KAC1B,CAAA,SAAU,GAAA,YACR,WAAA,CAAY,CAAA,MAAO,KAAA,EAAO,CAAA,KAC1B,CAAA,6CAEgB,CAAA,GAAI,WAAA,CAAY,CAAA,CAAE,CAAA,OAAQ,KAAA,EAAO,CAAA,WACvC,CAAA;AAAA,KAYhB,YAAA,MACV,aAAA,CAAc,CAAA,6BAA8B,OAAA,CAAQ,MAAA,EAAQ,CAAA;AAAA,KAEzD,aAAA,gCACH,aAAA,CAAc,CAAA,2BACT,CAAA,oBACC,MAAA,GACA,aAAA,CAAc,OAAA,CAAQ,CAAA,EAAG,OAAA,IAAW,OAAA,KAAY,MAAA;AAAA,KAGnD,aAAA,MACH,cAAA,CAAe,CAAA,oBAAqB,CAAA,EAAG,CAAA,6BACrC,CAAA,2BAEE,MAAA;AAAA,KAGD,cAAA,OAAqB,CAAA,oBAAqB,CAAA,EAAG,CAAA,6BAChD,CAAA,iCAEE,YAAA;AAAA,KAGC,OAAA,YAAmB,CAAA,SAAU,IAAA,GAAO,CAAA,GAAI,IAAA;AAAA,KAMjC,oBAAA,yBACc,gBAAA,gBACV,qBAAA,CAAsB,eAAA,yBAElC,CAAA,yCACA,IAAA,2CAEgB,IAAA,GAAO,sBAAA,CACjB,cAAA,CAAe,eAAA,EAAiB,KAAA,GAChC,IAAA,CAAK,CAAA;AAAA,KAOH,kBAAA,mBAAqC,gBAAA;EAC/C,GAAA,EAAK,qBAAA,CAAsB,SAAA;EAC3B,KAAA,EAAO,qBAAA,CAAsB,SAAA;AAAA"}

package/dist/Types.js.map

@@ -1 +1 @@
-{"version":3,"file":"Types.js","names":[],"sources":["../src/Types.ts"],"sourcesContent":["import type {\n  DocumentByName,\n  FieldTypeFromFieldPath,\n  GenericDatabaseReader,\n  GenericDataModel,\n  TableNamesInDataModel,\n} from \"convex/server\";\nimport type { GenericId } from \"convex/values\";\nimport type { Brand } from \"effect\";\n\nexport type IsOptional<T, K extends keyof T> =\n  {} extends Pick<T, K> ? true : false;\n\nexport type IsAny<T> = 0 extends 1 & T ? true : false;\n\nexport type IsUnion<T, U extends T = T> = T extends unknown\n  ? [U] extends [T]\n    ? false\n    : true\n  : never;\n\n// https://stackoverflow.com/a/52806744\nexport type IsValueLiteral<Vl> = [Vl] extends [never]\n  ? never\n  : IsUnion<Vl> extends true\n    ? false\n    : [Vl] extends [string | number | bigint | boolean]\n      ? [string] extends [Vl]\n        ? false\n        : [number] extends [Vl]\n          ? false\n          : [boolean] extends [Vl]\n            ? false\n            : [bigint] extends [Vl]\n              ? false\n              : true\n      : false;\n\n/**\n * Only checks for records with string keys.\n */\nexport type IsRecord<T> = [T] extends [never]\n  ? false\n  : IsUnion<T> extends true\n    ? false\n    : T extends Record<string, infer V>\n      ? string extends keyof T\n        ? keyof T extends string\n          ? T extends Record<string, V>\n            ? Record<string, V> extends T\n              ? true\n              : false\n            : false\n          : false\n        : false\n      : false;\n\nexport type DeepMutable<T> =\n  IsAny<T> extends true\n    ? any\n    : T extends Brand.Brand<any> | GenericId<any>\n      ? T\n      : T extends ReadonlyMap<infer K, infer V>\n        ? Map<DeepMutable<K>, DeepMutable<V>>\n        : T extends ReadonlySet<infer V>\n          ? Set<DeepMutable<V>>\n          : [keyof T] extends [never]\n            ? T\n            : { -readonly [K in keyof T]: DeepMutable<T[K]> };\n\nexport type TypeError<Message extends string, T = never> = [Message, T];\n\nexport type TypeDefect<Message extends string, T = never> = [Message, T];\n\nexport type IsRecursive<T> = true extends DetectCycle<T> ? true : false;\n\ntype DetectCycle<T, Cache extends any[] = []> =\n  IsAny<T> extends true\n    ? false\n    : [T] extends [any]\n      ? T extends Cache[number]\n        ? true\n        : T extends Array<infer U>\n          ? DetectCycle<U, [...Cache, T]>\n          : T extends Map<infer _U, infer V>\n            ? DetectCycle<V, [...Cache, T]>\n            : T extends Set<infer U>\n              ? DetectCycle<U, [...Cache, T]>\n              : T extends object\n                ? true extends {\n                    [K in keyof T]: DetectCycle<T[K], [...Cache, T]>;\n                  }[keyof T]\n                  ? true\n                  : false\n                : false\n      : never;\n\n//////////////////////////////////\n// START: Vendored from Arktype //\n//////////////////////////////////\n\n// https://github.com/arktypeio/arktype/blob/2e911d01a741ccee7a17e31ee144049817fabbb8/ark/util/unionToTuple.ts#L9\n\nexport type UnionToTuple<t> =\n  _unionToTuple<t, []> extends infer result ? conform<result, t[]> : never;\n\ntype _unionToTuple<t, result extends unknown[]> =\n  getLastBranch<t> extends infer current\n    ? [t] extends [never]\n      ? result\n      : _unionToTuple<Exclude<t, current>, [current, ...result]>\n    : never;\n\ntype getLastBranch<t> =\n  intersectUnion<t extends unknown ? (x: t) => void : never> extends (\n    x: infer branch,\n  ) => void\n    ? branch\n    : never;\n\ntype intersectUnion<t> = (t extends unknown ? (_: t) => void : never) extends (\n  _: infer intersection,\n) => void\n  ? intersection\n  : never;\n\ntype conform<t, base> = t extends base ? t : base;\n\n////////////////////////////////\n// END: Vendored from Arktype //\n////////////////////////////////\n\nexport type IndexFieldTypesForEq<\n  ConvexDataModel extends GenericDataModel,\n  Table extends TableNamesInDataModel<ConvexDataModel>,\n  T extends string[],\n> = T extends readonly [...infer Rest, any]\n  ? Rest extends readonly string[]\n    ? {\n        [K in keyof Rest]: FieldTypeFromFieldPath<\n          DocumentByName<ConvexDataModel, Table>,\n          Rest[K]\n        >;\n      }\n    : never\n  : never;\n\n// Would prefer to use `BaseDatabaseReader` from the `convex` package, but it's not exported.\nexport type BaseDatabaseReader<DataModel extends GenericDataModel> = {\n  get: GenericDatabaseReader<DataModel>[\"get\"];\n  query: GenericDatabaseReader<DataModel>[\"query\"];\n};\n"],"mappings":""}
+{"version":3,"file":"Types.js","names":[],"sources":["../src/Types.ts"],"sourcesContent":["import type {\n  DocumentByName,\n  FieldTypeFromFieldPath,\n  GenericDatabaseReader,\n  GenericDataModel,\n  TableNamesInDataModel,\n} from \"convex/server\";\nimport type { GenericId } from \"convex/values\";\nimport type { Brand } from \"effect\";\n\nexport type IsOptional<T, K extends keyof T> =\n  {} extends Pick<T, K> ? true : false;\n\nexport type IsAny<T> = 0 extends 1 & T ? true : false;\n\nexport type IsUnion<T, U extends T = T> = T extends unknown\n  ? [U] extends [T]\n    ? false\n    : true\n  : never;\n\n// https://stackoverflow.com/a/52806744\nexport type IsValueLiteral<Vl> = [Vl] extends [never]\n  ? never\n  : IsUnion<Vl> extends true\n    ? false\n    : [Vl] extends [string | number | bigint | boolean]\n      ? [string] extends [Vl]\n        ? false\n        : [number] extends [Vl]\n          ? false\n          : [boolean] extends [Vl]\n            ? false\n            : [bigint] extends [Vl]\n              ? false\n              : true\n      : false;\n\n/**\n * Only checks for records with string keys.\n */\nexport type IsRecord<T> = [T] extends [never]\n  ? false\n  : IsUnion<T> extends true\n    ? false\n    : T extends Record<string, infer V>\n      ? string extends keyof T\n        ? keyof T extends string\n          ? T extends Record<string, V>\n            ? Record<string, V> extends T\n              ? true\n              : false\n            : false\n          : false\n        : false\n      : false;\n\nexport type DeepMutable<T> =\n  IsAny<T> extends true\n    ? any\n    : T extends NonRecursiveLeaf\n      ? T\n      : T extends ReadonlyMap<infer K, infer V>\n        ? Map<DeepMutable<K>, DeepMutable<V>>\n        : T extends ReadonlySet<infer V>\n          ? Set<DeepMutable<V>>\n          : [keyof T] extends [never]\n            ? T\n            : { -readonly [K in keyof T]: DeepMutable<T[K]> };\n\nexport type TypeError<Message extends string, T = never> = [Message, T];\n\nexport type TypeDefect<Message extends string, T = never> = [Message, T];\n\nexport type IsRecursive<T> = true extends DetectCycle<T> ? true : false;\n\ntype NonRecursiveLeaf = Brand.Brand<any> | GenericId<any> | ArrayBuffer;\n\ntype DetectCycle<T, Cache extends any[] = []> =\n  IsAny<T> extends true\n    ? false\n    : [T] extends [any]\n      ? T extends NonRecursiveLeaf\n        ? false\n        : T extends Cache[number]\n          ? true\n          : T extends Array<infer U>\n            ? DetectCycle<U, [...Cache, T]>\n            : T extends Map<infer _U, infer V>\n              ? DetectCycle<V, [...Cache, T]>\n              : T extends Set<infer U>\n                ? DetectCycle<U, [...Cache, T]>\n                : T extends object\n                  ? true extends {\n                      [K in keyof T]: DetectCycle<T[K], [...Cache, T]>;\n                    }[keyof T]\n                    ? true\n                    : false\n                  : false\n      : never;\n\n//////////////////////////////////\n// START: Vendored from Arktype //\n//////////////////////////////////\n\n// https://github.com/arktypeio/arktype/blob/2e911d01a741ccee7a17e31ee144049817fabbb8/ark/util/unionToTuple.ts#L9\n\nexport type UnionToTuple<t> =\n  _unionToTuple<t, []> extends infer result ? conform<result, t[]> : never;\n\ntype _unionToTuple<t, result extends unknown[]> =\n  getLastBranch<t> extends infer current\n    ? [t] extends [never]\n      ? result\n      : _unionToTuple<Exclude<t, current>, [current, ...result]>\n    : never;\n\ntype getLastBranch<t> =\n  intersectUnion<t extends unknown ? (x: t) => void : never> extends (\n    x: infer branch,\n  ) => void\n    ? branch\n    : never;\n\ntype intersectUnion<t> = (t extends unknown ? (_: t) => void : never) extends (\n  _: infer intersection,\n) => void\n  ? intersection\n  : never;\n\ntype conform<t, base> = t extends base ? t : base;\n\n////////////////////////////////\n// END: Vendored from Arktype //\n////////////////////////////////\n\nexport type IndexFieldTypesForEq<\n  ConvexDataModel extends GenericDataModel,\n  Table extends TableNamesInDataModel<ConvexDataModel>,\n  T extends string[],\n> = T extends readonly [...infer Rest, any]\n  ? Rest extends readonly string[]\n    ? {\n        [K in keyof Rest]: FieldTypeFromFieldPath<\n          DocumentByName<ConvexDataModel, Table>,\n          Rest[K]\n        >;\n      }\n    : never\n  : never;\n\n// Would prefer to use `BaseDatabaseReader` from the `convex` package, but it's not exported.\nexport type BaseDatabaseReader<DataModel extends GenericDataModel> = {\n  get: GenericDatabaseReader<DataModel>[\"get\"];\n  query: GenericDatabaseReader<DataModel>[\"query\"];\n};\n"],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@confect/core",
-  "version": "5.0.0",
+  "version": "7.0.0",
   "description": "Shared specs and schemas used by all Confect packages",
   "repository": {
     "type": "git",

package/src/FunctionProvenance.ts

@@ -6,6 +6,7 @@ export type FunctionProvenance = Data.TaggedEnum<{
   Confect: {
     args: Schema.Schema.AnyNoContext;
     returns: Schema.Schema.AnyNoContext;
+    error?: Schema.Schema.AnyNoContext;
   };
   Convex: {
     /** @internal */
@@ -18,13 +19,16 @@ export type FunctionProvenance = Data.TaggedEnum<{
 export interface Confect<
   Args extends Schema.Schema.AnyNoContext,
   Returns extends Schema.Schema.AnyNoContext,
+  Error extends Schema.Schema.AnyNoContext = never,
 > {
   readonly _tag: "Confect";
   readonly args: Args;
   readonly returns: Returns;
+  readonly error?: Error;
 }
 
 export interface AnyConfect extends Confect<
+  Schema.Schema.AnyNoContext,
   Schema.Schema.AnyNoContext,
   Schema.Schema.AnyNoContext
 > {}
@@ -42,13 +46,16 @@ export const FunctionProvenance = Data.taggedEnum<FunctionProvenance>();
 export const Confect = <
   Args extends Schema.Schema.AnyNoContext,
   Returns extends Schema.Schema.AnyNoContext,
+  Error extends Schema.Schema.AnyNoContext = never,
 >(
   args: Args,
   returns: Returns,
+  error?: Error,
 ) =>
   FunctionProvenance.Confect({
     args,
     returns,
+    ...(error !== undefined ? { error } : {}),
   });
 
 export const Convex = <_Args extends DefaultFunctionArgs, _Returns>() =>

package/src/FunctionSpec.ts

@@ -145,6 +145,27 @@ export type EncodedReturns<FunctionSpec_ extends AnyWithProps> =
       ? Returns_
       : never;
 
+export type Error<FunctionSpec_ extends AnyWithProps> = FunctionSpec_ extends {
+  functionProvenance: FunctionProvenance.Confect<
+    any,
+    any,
+    infer ErrorSchema_ extends Schema.Schema.AnyNoContext
+  >;
+}
+  ? ErrorSchema_["Type"]
+  : never;
+
+export type EncodedError<FunctionSpec_ extends AnyWithProps> =
+  FunctionSpec_ extends {
+    functionProvenance: FunctionProvenance.Confect<
+      any,
+      any,
+      infer ErrorSchema_ extends Schema.Schema.AnyNoContext
+    >;
+  }
+    ? ErrorSchema_["Encoded"]
+    : never;
+
 export type WithName<
   FunctionSpec_ extends AnyWithProps,
   Name_ extends string,
@@ -196,19 +217,22 @@ const make =
     const Name_ extends string,
     Args_ extends Schema.Schema.AnyNoContext,
     Returns_ extends Schema.Schema.AnyNoContext,
+    Error_ extends Schema.Schema.AnyNoContext = never,
   >({
     name,
     args,
     returns,
+    error,
   }: {
     name: Name_;
     args: Args_;
     returns: Returns_;
+    error?: Error_;
   }): FunctionSpec<
     RuntimeAndFunctionType_,
     FunctionVisibility_,
     Name_,
-    FunctionProvenance.Confect<Args_, Returns_>
+    FunctionProvenance.Confect<Args_, Returns_, Error_>
   > => {
     validateConfectFunctionIdentifier(name);
 
@@ -216,7 +240,7 @@ const make =
       runtimeAndFunctionType,
       functionVisibility,
       name,
-      functionProvenance: FunctionProvenance.Confect(args, returns),
+      functionProvenance: FunctionProvenance.Confect(args, returns, error),
     });
   };