@confect/react 6.0.0 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,132 @@
 # @confect/react
 
+## 7.0.0
+
+### Major Changes
+
+- 90094d0: Add typed errors to Confect functions (queries, mutations, and actions). Declare an optional `error` schema in `FunctionSpec` and recover it as a typed value at every call site—`useQuery`, `useMutation`, `useAction`, `HttpClient`, `WebSocketClient`, and `TestConfect`—without paying for it on functions that don't fail.
+
+  Typed errors travel across the function boundary as Convex's native [`ConvexError`](https://docs.convex.dev/functions/error-handling/application-errors#throwing-application-errors): the encoded error sits in `ConvexError.data`, leaving the `returns` channel unsullied and preserving native Convex semantics for non-Confect callers of the same API.
+
+  ### Authoring a function with typed errors
+
+  `FunctionSpec` constructors now accept an optional `error` schema. To support multiple error shapes, combine them with `Schema.Union`.
+
+  ```ts
+  import { FunctionSpec, GenericId, GroupSpec } from "@confect/core";
+  import { Schema } from "effect";
+
+  export class NoteNotFound extends Schema.TaggedError<NoteNotFound>()(
+    "NoteNotFound",
+    { noteId: GenericId.GenericId("notes") },
+  ) {}
+
+  export const notes = GroupSpec.make("notes").addFunction(
+    FunctionSpec.publicQuery({
+      name: "getOrFail",
+      args: Schema.Struct({ noteId: GenericId.GenericId("notes") }),
+      returns: Notes.Doc,
+      error: NoteNotFound,
+    }),
+  );
+  ```
+
+  The `FunctionImpl` for that ref can now `Effect.fail` (or `mapError` to) any value matching the declared schema. Whichever invocation path the caller takes—`useQuery`/`useMutation`/`useAction`, `HttpClient`, `WebSocketClient`, or `TestConfect`—Confect encodes the failure, transports it via `ConvexError`, and surfaces the decoded value in the appropriate channel for that call site.
+
+  ```ts
+  import { FunctionImpl } from "@confect/server";
+  import { Effect } from "effect";
+  import api from "../_generated/api";
+  import { DatabaseReader } from "../_generated/services";
+  import { NoteNotFound } from "./notes.spec";
+
+  const getOrFail = FunctionImpl.make(api, "notes", "getOrFail", ({ noteId }) =>
+    Effect.gen(function* () {
+      const reader = yield* DatabaseReader;
+      return yield* reader
+        .table("notes")
+        .get(noteId)
+        .pipe(Effect.mapError(() => new NoteNotFound({ noteId })));
+    }),
+  );
+  ```
+
+  ### Consuming a typed error
+
+  `@confect/js` (`HttpClient`, `WebSocketClient`) and `@confect/test` (`TestConfect`) surface the decoded error in the `Effect` error channel alongside the existing `HttpClientError`/`WebSocketClientError`/`ParseError`:
+
+  ```ts
+  HttpClient.query(refs.public.notes.getOrFail, { noteId });
+  // Effect.Effect<Note, NoteNotFound | HttpClientError | ParseError>
+  ```
+
+  ### `@confect/react`—breaking changes
+
+  `useQuery`, `useMutation`, and `useAction` now expose typed errors, and `useQuery` returns a tagged result type instead of `Returns | undefined`.
+
+  **`useQuery` now returns `QueryResult<A, E>`.** Loading and (when an `error` schema is declared) failure are reified as variants alongside success. Match on the result with `QueryResult.match`:
+
+  Before:
+
+  ```tsx
+  const notes = useQuery(refs.public.notes.list, {});
+  if (notes === undefined) return <p>Loading…</p>;
+  return <NoteList notes={notes} />;
+  ```
+
+  After:
+
+  ```tsx
+  import { QueryResult, useQuery } from "@confect/react";
+
+  const notes = useQuery(refs.public.notes.list, {});
+  return QueryResult.match(notes, {
+    onLoading: (skipped) => (skipped ? null : <p>Loading…</p>),
+    onSuccess: (notes) => <NoteList notes={notes} />,
+  });
+  ```
+
+  The `Loading` variant carries a `skipped: boolean` flag, exposed as the argument to `onLoading`. It distinguishes a query that is genuinely in flight (`skipped: false`) from one that is sitting idle because `"skip"` was passed as its args (`skipped: true`)—a distinction `convex/react`'s plain `undefined` return value cannot make. Use it to render a loading indicator only when work is actually happening, and an empty/placeholder state otherwise.
+
+  When the ref declares an `error` schema, `onFailure` becomes required and receives the decoded typed error:
+
+  ```tsx
+  const lookup = useQuery(refs.public.notes.getOrFail, { noteId });
+  QueryResult.match(lookup, {
+    onLoading: (skipped) => (skipped ? null : "Looking up…"),
+    onSuccess: (note) => `Found: ${note.text}`,
+    onFailure: (error) => `Note ${error.noteId} not found.`,
+  });
+  ```
+
+  `QueryResult` is a Confect-native type exported from `@confect/react`.
+
+  **`useMutation` and `useAction` return `Promise<Either<A, E>>` when the ref declares an `error` schema.** Refs without an `error` schema continue to resolve to `Promise<A>`, matching the prior shape and `convex/react`'s behavior.
+
+  ```ts
+  const deleteOrFail = useMutation(refs.public.notes.deleteOrFail);
+  const result = await deleteOrFail({ noteId });
+  // Either.Either<null, NoteNotFound | Forbidden>
+  Either.match(result, {
+    onLeft: (error) => /* typed error */,
+    onRight: (value) => /* success */,
+  });
+
+  const deleteNote = useMutation(refs.public.notes.delete_); // no `error` schema
+  await deleteNote({ noteId }); // Promise<null>, as before
+  ```
+
+  Unspecified failures continue to reject the promise.
+
+  ### Migration
+  - For each `useQuery` call site, replace `result === undefined` checks and direct property access with `QueryResult.match` (or the lower-level `QueryResult.isLoading`/`isSuccess`/`isFailure` predicates).
+  - For each `useMutation`/`useAction` call site whose ref now declares an `error` schema, unwrap the resolved `Either` (e.g. with `Either.match`); call sites against refs without an `error` schema need no change.
+
+### Patch Changes
+
+- Updated dependencies [90094d0]
+  - @confect/core@7.0.0
+
 ## 6.0.0
 
 ### Minor Changes

package/dist/QueryResult.d.ts

@@ -0,0 +1,71 @@
+import { Pipeable } from "effect";
+
+//#region src/QueryResult.d.ts
+declare namespace QueryResult_d_exports {
+  export { Failure, Loading, QueryResult, Success, fail, isFailure, isLoading, isQueryResult, isSuccess, load, match, succeed };
+}
+declare const TypeId = "@confect/react/QueryResult";
+type TypeId = typeof TypeId;
+/**
+ * A `QueryResult` represents the result of a Confect query.
+ *
+ * @typeParam A - The type of the decoded `returns` value in the `Success` variant.
+ * @typeParam E - The type of the decoded typed error in the `Failure` variant.
+ */
+type QueryResult<A, E = never> = Loading<A, E> | Success<A, E> | Failure<A, E>;
+declare namespace QueryResult {
+  interface Proto<A, E> extends Pipeable.Pipeable {
+    readonly [TypeId]: {
+      readonly E: (_: never) => E;
+      readonly A: (_: never) => A;
+    };
+  }
+  type Success<R> = R extends QueryResult<infer A, infer _E> ? A : never;
+  type Failure<R> = R extends QueryResult<infer _A, infer E> ? E : never;
+}
+interface Loading<A, E = never> extends QueryResult.Proto<A, E> {
+  readonly _tag: "Loading";
+  readonly skipped: boolean;
+}
+interface Success<A, E = never> extends QueryResult.Proto<A, E> {
+  readonly _tag: "Success";
+  readonly value: A;
+}
+interface Failure<A, E = never> extends QueryResult.Proto<A, E> {
+  readonly _tag: "Failure";
+  readonly error: E;
+}
+declare const isQueryResult: (u: unknown) => u is QueryResult<unknown, unknown>;
+declare const load: <A = never, E = never>(skipped: boolean) => Loading<A, E>;
+declare const succeed: <A, E = never>(value: A) => Success<A, E>;
+declare const fail: <E, A = never>(error: E) => Failure<A, E>;
+declare const isLoading: <A, E>(queryResult: QueryResult<A, E>) => queryResult is Loading<A, E>;
+declare const isSuccess: <A, E>(queryResult: QueryResult<A, E>) => queryResult is Success<A, E>;
+declare const isFailure: <A, E>(queryResult: QueryResult<A, E>) => queryResult is Failure<A, E>;
+type MatchOptions<A, E, X, Y, Z> = {
+  readonly onLoading: (skipped: boolean) => X;
+  readonly onSuccess: (value: A) => Y;
+} & ([E] extends [never] ? {} : {
+  readonly onFailure: (error: E) => Z;
+});
+type MatchReturns<E, X, Y, Z> = [E] extends [never] ? X | Y : X | Y | Z;
+/**
+ * Matches a {@link QueryResult} to the appropriate handler based on its tag. If
+ * the provided `QueryResult` cannot fail (i.e. `E` is `never`), `onFailure` is
+ * not required.
+ *
+ * @example
+ * ```tsx
+ * const result = QueryResult.match(queryResult, {
+ *   onLoading: (skipped) => skipped ? null : <p>Loading…</p>,
+ *   onSuccess: (value) => <p>{value.text}</p>,
+ *   onFailure: (error) => <p>Error: {error.message}</p>,
+ * });
+ */
+declare const match: {
+  <A, E, X, Y, Z = never>(options: MatchOptions<A, E, X, Y, Z>): (self: QueryResult<A, E>) => MatchReturns<E, X, Y, Z>;
+  <A, E, X, Y, Z = never>(self: QueryResult<A, E>, options: MatchOptions<A, E, X, Y, Z>): MatchReturns<E, X, Y, Z>;
+};
+//#endregion
+export { QueryResult, QueryResult_d_exports };
+//# sourceMappingURL=QueryResult.d.ts.map

package/dist/QueryResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryResult.d.ts","names":[],"sources":["../src/QueryResult.ts"],"mappings":";;;;;;cAEM,MAAA;AAAA,KACD,MAAA,UAAgB,MAAA;;;;;;;KAQT,WAAA,iBACR,OAAA,CAAQ,CAAA,EAAG,CAAA,IACX,OAAA,CAAQ,CAAA,EAAG,CAAA,IACX,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,kBAEU,WAAA;EAAA,UACN,KAAA,eAAoB,QAAA,CAAS,QAAA;IAAA,UAClC,MAAA;MAAA,SACC,CAAA,GAAI,CAAA,YAAa,CAAA;MAAA,SACjB,CAAA,GAAI,CAAA,YAAa,CAAA;IAAA;EAAA;EAAA,KAKlB,OAAA,MAAa,CAAA,SAAU,WAAA,sBAAiC,CAAA;EAAA,KAGxD,OAAA,MAAa,CAAA,SAAU,WAAA,sBAAiC,CAAA;AAAA;AAAA,UAGrD,OAAA,uBAA8B,WAAA,CAAY,KAAA,CAAM,CAAA,EAAG,CAAA;EAAA,SACzD,IAAA;EAAA,SACA,OAAA;AAAA;AAAA,UAGM,OAAA,uBAA8B,WAAA,CAAY,KAAA,CAAM,CAAA,EAAG,CAAA;EAAA,SACzD,IAAA;EAAA,SACA,KAAA,EAAO,CAAA;AAAA;AAAA,UAGD,OAAA,uBAA8B,WAAA,CAAY,KAAA,CAAM,CAAA,EAAG,CAAA;EAAA,SACzD,IAAA;EAAA,SACA,KAAA,EAAO,CAAA;AAAA;AAAA,cAGL,aAAA,GAAiB,CAAA,cAAa,CAAA,IAAK,WAAA;AAAA,cA8CnC,IAAA,yBAA8B,OAAA,cAAmB,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,cAM5D,OAAA,iBAAyB,KAAA,EAAO,CAAA,KAAI,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,cAM/C,IAAA,iBAAsB,KAAA,EAAO,CAAA,KAAI,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,cAM5C,SAAA,SACX,WAAA,EAAa,WAAA,CAAY,CAAA,EAAG,CAAA,MAC3B,WAAA,IAAe,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,cAEhB,SAAA,SACX,WAAA,EAAa,WAAA,CAAY,CAAA,EAAG,CAAA,MAC3B,WAAA,IAAe,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,cAEhB,SAAA,SACX,WAAA,EAAa,WAAA,CAAY,CAAA,EAAG,CAAA,MAC3B,WAAA,IAAe,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,KAExB,YAAA;EAAA,SACM,SAAA,GAAY,OAAA,cAAqB,CAAA;EAAA,SACjC,SAAA,GAAY,KAAA,EAAO,CAAA,KAAM,CAAA;AAAA,MAC9B,CAAA;EAAA,SAAqC,SAAA,GAAY,KAAA,EAAO,CAAA,KAAM,CAAA;AAAA;AAAA,KAE/D,YAAA,gBAA4B,CAAA,oBAAqB,CAAA,GAAI,CAAA,GAAI,CAAA,GAAI,CAAA,GAAI,CAAA;;;;;;;;;;AA/GtE;;;;cA8Ha,KAAA;EAAA,wBAET,OAAA,EAAS,YAAA,CAAa,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA,KAChC,IAAA,EAAM,WAAA,CAAY,CAAA,EAAG,CAAA,MAAO,YAAA,CAAa,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA;EAAA,wBAEpD,IAAA,EAAM,WAAA,CAAY,CAAA,EAAG,CAAA,GACrB,OAAA,EAAS,YAAA,CAAa,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA,IACjC,YAAA,CAAa,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA;AAAA"}

package/dist/QueryResult.js

@@ -0,0 +1,82 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { Equal, Function, Hash, Pipeable, Predicate, identity } from "effect";
+
+//#region src/QueryResult.ts
+var QueryResult_exports = /* @__PURE__ */ __exportAll({
+	fail: () => fail,
+	isFailure: () => isFailure,
+	isLoading: () => isLoading,
+	isQueryResult: () => isQueryResult,
+	isSuccess: () => isSuccess,
+	load: () => load,
+	match: () => match,
+	succeed: () => succeed
+});
+const TypeId = "@confect/react/QueryResult";
+const isQueryResult = (u) => Predicate.hasProperty(u, TypeId);
+const QueryResultProto = {
+	[TypeId]: {
+		E: identity,
+		A: identity
+	},
+	pipe(...args) {
+		return Pipeable.pipeArguments(this, args);
+	},
+	[Equal.symbol](that) {
+		if (this._tag !== that._tag) return false;
+		switch (this._tag) {
+			case "Loading": return this.skipped === that.skipped;
+			case "Success": return Equal.equals(this.value, that.value);
+			case "Failure": return Equal.equals(this.error, that.error);
+		}
+	},
+	[Hash.symbol]() {
+		const tagHash = Hash.string(this._tag);
+		switch (this._tag) {
+			case "Loading": return Hash.cached(this, Hash.combine(tagHash)(Hash.hash(this.skipped)));
+			case "Success": return Hash.cached(this, Hash.combine(tagHash)(Hash.hash(this.value)));
+			case "Failure": return Hash.cached(this, Hash.combine(tagHash)(Hash.hash(this.error)));
+		}
+	}
+};
+const load = (skipped) => Object.assign(Object.create(QueryResultProto), {
+	_tag: "Loading",
+	skipped
+});
+const succeed = (value) => Object.assign(Object.create(QueryResultProto), {
+	_tag: "Success",
+	value
+});
+const fail = (error) => Object.assign(Object.create(QueryResultProto), {
+	_tag: "Failure",
+	error
+});
+const isLoading = (queryResult) => queryResult._tag === "Loading";
+const isSuccess = (queryResult) => queryResult._tag === "Success";
+const isFailure = (queryResult) => queryResult._tag === "Failure";
+/**
+* Matches a {@link QueryResult} to the appropriate handler based on its tag. If
+* the provided `QueryResult` cannot fail (i.e. `E` is `never`), `onFailure` is
+* not required.
+*
+* @example
+* ```tsx
+* const result = QueryResult.match(queryResult, {
+*   onLoading: (skipped) => skipped ? null : <p>Loading…</p>,
+*   onSuccess: (value) => <p>{value.text}</p>,
+*   onFailure: (error) => <p>Error: {error.message}</p>,
+* });
+*/
+const match = Function.dual(2, (self, options) => {
+	switch (self._tag) {
+		case "Loading": return options.onLoading(self.skipped);
+		case "Success": return options.onSuccess(self.value);
+		case "Failure":
+			if (Predicate.hasProperty(options, "onFailure")) return options.onFailure(self.error);
+			throw new Error("`onFailure` is required when error schema is provided");
+	}
+});
+
+//#endregion
+export { QueryResult_exports, fail, load, succeed };
+//# sourceMappingURL=QueryResult.js.map

package/dist/QueryResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryResult.js","names":[],"sources":["../src/QueryResult.ts"],"sourcesContent":["import { Equal, Function, Hash, identity, Pipeable, Predicate } from \"effect\";\n\nconst TypeId = \"@confect/react/QueryResult\";\ntype TypeId = typeof TypeId;\n\n/**\n * A `QueryResult` represents the result of a Confect query.\n *\n * @typeParam A - The type of the decoded `returns` value in the `Success` variant.\n * @typeParam E - The type of the decoded typed error in the `Failure` variant.\n */\nexport type QueryResult<A, E = never> =\n  | Loading<A, E>\n  | Success<A, E>\n  | Failure<A, E>;\n\nexport declare namespace QueryResult {\n  export interface Proto<A, E> extends Pipeable.Pipeable {\n    readonly [TypeId]: {\n      readonly E: (_: never) => E;\n      readonly A: (_: never) => A;\n    };\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-shadow\n  export type Success<R> = R extends QueryResult<infer A, infer _E> ? A : never;\n\n  // eslint-disable-next-line @typescript-eslint/no-shadow\n  export type Failure<R> = R extends QueryResult<infer _A, infer E> ? E : never;\n}\n\nexport interface Loading<A, E = never> extends QueryResult.Proto<A, E> {\n  readonly _tag: \"Loading\";\n  readonly skipped: boolean;\n}\n\nexport interface Success<A, E = never> extends QueryResult.Proto<A, E> {\n  readonly _tag: \"Success\";\n  readonly value: A;\n}\n\nexport interface Failure<A, E = never> extends QueryResult.Proto<A, E> {\n  readonly _tag: \"Failure\";\n  readonly error: E;\n}\n\nexport const isQueryResult = (u: unknown): u is QueryResult<unknown, unknown> =>\n  Predicate.hasProperty(u, TypeId);\n\nconst QueryResultProto = {\n  [TypeId]: {\n    E: identity,\n    A: identity,\n  },\n  pipe(this: QueryResult<any, any>, ...args: ReadonlyArray<unknown>) {\n    return Pipeable.pipeArguments(\n      this,\n      args as unknown as Parameters<typeof Pipeable.pipeArguments>[1],\n    );\n  },\n  [Equal.symbol](\n    this: QueryResult<any, any>,\n    that: QueryResult<any, any>,\n  ): boolean {\n    if (this._tag !== that._tag) {\n      return false;\n    }\n    switch (this._tag) {\n      case \"Loading\":\n        return this.skipped === (that as Loading<any, any>).skipped;\n      case \"Success\":\n        return Equal.equals(this.value, (that as Success<any, any>).value);\n      case \"Failure\":\n        return Equal.equals(this.error, (that as Failure<any, any>).error);\n    }\n  },\n  [Hash.symbol](this: QueryResult<any, any>): number {\n    const tagHash = Hash.string(this._tag);\n    switch (this._tag) {\n      case \"Loading\":\n        return Hash.cached(\n          this,\n          Hash.combine(tagHash)(Hash.hash(this.skipped)),\n        );\n      case \"Success\":\n        return Hash.cached(this, Hash.combine(tagHash)(Hash.hash(this.value)));\n      case \"Failure\":\n        return Hash.cached(this, Hash.combine(tagHash)(Hash.hash(this.error)));\n    }\n  },\n};\n\nexport const load = <A = never, E = never>(skipped: boolean): Loading<A, E> =>\n  Object.assign(Object.create(QueryResultProto), {\n    _tag: \"Loading\" as const,\n    skipped,\n  });\n\nexport const succeed = <A, E = never>(value: A): Success<A, E> =>\n  Object.assign(Object.create(QueryResultProto), {\n    _tag: \"Success\" as const,\n    value,\n  });\n\nexport const fail = <E, A = never>(error: E): Failure<A, E> =>\n  Object.assign(Object.create(QueryResultProto), {\n    _tag: \"Failure\" as const,\n    error,\n  });\n\nexport const isLoading = <A, E>(\n  queryResult: QueryResult<A, E>,\n): queryResult is Loading<A, E> => queryResult._tag === \"Loading\";\n\nexport const isSuccess = <A, E>(\n  queryResult: QueryResult<A, E>,\n): queryResult is Success<A, E> => queryResult._tag === \"Success\";\n\nexport const isFailure = <A, E>(\n  queryResult: QueryResult<A, E>,\n): queryResult is Failure<A, E> => queryResult._tag === \"Failure\";\n\ntype MatchOptions<A, E, X, Y, Z> = {\n  readonly onLoading: (skipped: boolean) => X;\n  readonly onSuccess: (value: A) => Y;\n} & ([E] extends [never] ? {} : { readonly onFailure: (error: E) => Z });\n\ntype MatchReturns<E, X, Y, Z> = [E] extends [never] ? X | Y : X | Y | Z;\n\n/**\n * Matches a {@link QueryResult} to the appropriate handler based on its tag. If\n * the provided `QueryResult` cannot fail (i.e. `E` is `never`), `onFailure` is\n * not required.\n *\n * @example\n * ```tsx\n * const result = QueryResult.match(queryResult, {\n *   onLoading: (skipped) => skipped ? null : <p>Loading…</p>,\n *   onSuccess: (value) => <p>{value.text}</p>,\n *   onFailure: (error) => <p>Error: {error.message}</p>,\n * });\n */\nexport const match: {\n  <A, E, X, Y, Z = never>(\n    options: MatchOptions<A, E, X, Y, Z>,\n  ): (self: QueryResult<A, E>) => MatchReturns<E, X, Y, Z>;\n  <A, E, X, Y, Z = never>(\n    self: QueryResult<A, E>,\n    options: MatchOptions<A, E, X, Y, Z>,\n  ): MatchReturns<E, X, Y, Z>;\n} = Function.dual(\n  2,\n  <A, E, X, Y, Z = never>(\n    self: QueryResult<A, E>,\n    options: MatchOptions<A, E, X, Y, Z>,\n  ): MatchReturns<E, X, Y, Z> => {\n    switch (self._tag) {\n      case \"Loading\":\n        return options.onLoading(self.skipped);\n      case \"Success\":\n        return options.onSuccess(self.value);\n      case \"Failure\": {\n        if (Predicate.hasProperty(options, \"onFailure\")) {\n          return options.onFailure(self.error) as MatchReturns<E, X, Y, Z>;\n        }\n        throw new Error(\n          \"`onFailure` is required when error schema is provided\",\n        );\n      }\n    }\n  },\n);\n"],"mappings":";;;;;;;;;;;;;;AAEA,MAAM,SAAS;AA4Cf,MAAa,iBAAiB,MAC5B,UAAU,YAAY,GAAG,OAAO;AAElC,MAAM,mBAAmB;EACtB,SAAS;EACR,GAAG;EACH,GAAG;EACJ;CACD,KAAkC,GAAG,MAA8B;AACjE,SAAO,SAAS,cACd,MACA,KACD;;CAEH,CAAC,MAAM,QAEL,MACS;AACT,MAAI,KAAK,SAAS,KAAK,KACrB,QAAO;AAET,UAAQ,KAAK,MAAb;GACE,KAAK,UACH,QAAO,KAAK,YAAa,KAA2B;GACtD,KAAK,UACH,QAAO,MAAM,OAAO,KAAK,OAAQ,KAA2B,MAAM;GACpE,KAAK,UACH,QAAO,MAAM,OAAO,KAAK,OAAQ,KAA2B,MAAM;;;CAGxE,CAAC,KAAK,UAA6C;EACjD,MAAM,UAAU,KAAK,OAAO,KAAK,KAAK;AACtC,UAAQ,KAAK,MAAb;GACE,KAAK,UACH,QAAO,KAAK,OACV,MACA,KAAK,QAAQ,QAAQ,CAAC,KAAK,KAAK,KAAK,QAAQ,CAAC,CAC/C;GACH,KAAK,UACH,QAAO,KAAK,OAAO,MAAM,KAAK,QAAQ,QAAQ,CAAC,KAAK,KAAK,KAAK,MAAM,CAAC,CAAC;GACxE,KAAK,UACH,QAAO,KAAK,OAAO,MAAM,KAAK,QAAQ,QAAQ,CAAC,KAAK,KAAK,KAAK,MAAM,CAAC,CAAC;;;CAG7E;AAED,MAAa,QAA8B,YACzC,OAAO,OAAO,OAAO,OAAO,iBAAiB,EAAE;CAC7C,MAAM;CACN;CACD,CAAC;AAEJ,MAAa,WAAyB,UACpC,OAAO,OAAO,OAAO,OAAO,iBAAiB,EAAE;CAC7C,MAAM;CACN;CACD,CAAC;AAEJ,MAAa,QAAsB,UACjC,OAAO,OAAO,OAAO,OAAO,iBAAiB,EAAE;CAC7C,MAAM;CACN;CACD,CAAC;AAEJ,MAAa,aACX,gBACiC,YAAY,SAAS;AAExD,MAAa,aACX,gBACiC,YAAY,SAAS;AAExD,MAAa,aACX,gBACiC,YAAY,SAAS;;;;;;;;;;;;;;AAsBxD,MAAa,QAQT,SAAS,KACX,IAEE,MACA,YAC6B;AAC7B,SAAQ,KAAK,MAAb;EACE,KAAK,UACH,QAAO,QAAQ,UAAU,KAAK,QAAQ;EACxC,KAAK,UACH,QAAO,QAAQ,UAAU,KAAK,MAAM;EACtC,KAAK;AACH,OAAI,UAAU,YAAY,SAAS,YAAY,CAC7C,QAAO,QAAQ,UAAU,KAAK,MAAM;AAEtC,SAAM,IAAI,MACR,wDACD;;EAIR"}

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,18 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll };

package/dist/index.d.ts

@@ -1,10 +1,39 @@
+import { QueryResult, QueryResult_d_exports } from "./QueryResult.js";
 import { Ref } from "@confect/core";
+import { Either } from "effect";
 
 //#region src/index.d.ts
+type InvokeReturn<Ref_ extends Ref.Any> = [Ref.Error<Ref_>] extends [never] ? Promise<Ref.Returns<Ref_>> : Promise<Either.Either<Ref.Returns<Ref_>, Ref.Error<Ref_>>>;
 type UseQueryArgs<Query extends Ref.AnyPublicQuery> = keyof Ref.Args<Query> extends never ? [args?: Ref.Args<Query> | "skip"] : [args: Ref.Args<Query> | "skip"];
-declare const useQuery: <Query extends Ref.AnyPublicQuery>(ref: Query, ...rest: UseQueryArgs<Query>) => Ref.Returns<Query> | undefined;
-declare const useMutation: <Mutation extends Ref.AnyPublicMutation>(ref: Mutation) => (...args: Ref.OptionalArgs<Mutation>) => Promise<Ref.Returns<Mutation>>;
-declare const useAction: <Action extends Ref.AnyPublicAction>(ref: Action) => (...args: Ref.OptionalArgs<Action>) => Promise<Ref.Returns<Action>>;
+declare const useQuery: <Query extends Ref.AnyPublicQuery>(ref: Query, ...rest: UseQueryArgs<Query>) => QueryResult<Ref.Returns<Query>, Ref.Error<Query>>;
+/**
+ * Returns a function that invokes the provided `Ref`'s mutation.
+ *
+ * If the `Ref` declares an `error` schema, the returned promise resolves to an
+ * `Either` with the decoded `returns` value on the right and the decoded error
+ * on the left.
+ *
+ * If the `Ref` does not declare an `error` schema, the promise resolves
+ * directly to the decoded `returns` value, matching the behavior of
+ * `useMutation` from `convex/react`.
+ *
+ * Any other failure rejects the promise.
+ */
+declare const useMutation: <Mutation extends Ref.AnyPublicMutation>(ref: Mutation) => ((...args: Ref.OptionalArgs<Mutation>) => InvokeReturn<Mutation>);
+/**
+ * Returns a function that invokes the provided `Ref`'s action.
+ *
+ * If the `Ref` declares an `error` schema, the returned promise resolves to an
+ * `Either` with the decoded `returns` value on the right and the decoded error
+ * on the left.
+ *
+ * If the `Ref` does not declare an `error` schema, the promise resolves
+ * directly to the decoded `returns` value, matching the behavior of
+ * `useMutation` from `convex/react`.
+ *
+ * Any other failure rejects the promise.
+ */
+declare const useAction: <Action extends Ref.AnyPublicAction>(ref: Action) => ((...args: Ref.OptionalArgs<Action>) => InvokeReturn<Action>);
 //#endregion
-export { useAction, useMutation, useQuery };
+export { InvokeReturn, QueryResult_d_exports as QueryResult, useAction, useMutation, useQuery };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;KAOK,YAAA,eAA2B,GAAA,CAAI,cAAA,UAC5B,GAAA,CAAI,IAAA,CAAK,KAAA,mBACV,IAAA,GAAO,GAAA,CAAI,IAAA,CAAK,KAAA,eAChB,IAAA,EAAM,GAAA,CAAI,IAAA,CAAK,KAAA;AAAA,cAET,QAAA,iBAA0B,GAAA,CAAI,cAAA,EACzC,GAAA,EAAK,KAAA,KACF,IAAA,EAAM,YAAA,CAAa,KAAA,MACrB,GAAA,CAAI,OAAA,CAAQ,KAAA;AAAA,cAoBF,WAAA,oBAAgC,GAAA,CAAI,iBAAA,EAC/C,GAAA,EAAK,QAAA,SAMA,IAAA,EAAM,GAAA,CAAI,YAAA,CAAa,QAAA,MACzB,OAAA,CAAQ,GAAA,CAAI,OAAA,CAAQ,QAAA;AAAA,cAWZ,SAAA,kBAA4B,GAAA,CAAI,eAAA,EAAiB,GAAA,EAAK,MAAA,SAItD,IAAA,EAAM,GAAA,CAAI,YAAA,CAAa,MAAA,MAAU,OAAA,CAAQ,GAAA,CAAI,OAAA,CAAQ,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;KAYY,YAAA,cAA0B,GAAA,CAAI,GAAA,KAAQ,GAAA,CAAI,KAAA,CAAM,IAAA,qBAGxD,OAAA,CAAQ,GAAA,CAAI,OAAA,CAAQ,IAAA,KACpB,OAAA,CAAQ,MAAA,CAAO,MAAA,CAAO,GAAA,CAAI,OAAA,CAAQ,IAAA,GAAO,GAAA,CAAI,KAAA,CAAM,IAAA;AAAA,KAElD,YAAA,eAA2B,GAAA,CAAI,cAAA,UAC5B,GAAA,CAAI,IAAA,CAAK,KAAA,mBACV,IAAA,GAAO,GAAA,CAAI,IAAA,CAAK,KAAA,eAChB,IAAA,EAAM,GAAA,CAAI,IAAA,CAAK,KAAA;AAAA,cAET,QAAA,iBAA0B,GAAA,CAAI,cAAA,EACzC,GAAA,EAAK,KAAA,KACF,IAAA,EAAM,YAAA,CAAa,KAAA,MACrB,WAAA,CAAwB,GAAA,CAAI,OAAA,CAAQ,KAAA,GAAQ,GAAA,CAAI,KAAA,CAAM,KAAA;;;;;;;;;;;;;;cA6C5C,WAAA,oBAAgC,GAAA,CAAI,iBAAA,EAC/C,GAAA,EAAK,QAAA,UACC,IAAA,EAAM,GAAA,CAAI,YAAA,CAAa,QAAA,MAAc,YAAA,CAAa,QAAA;;;;;;;;;;;;;;cA2B7C,SAAA,kBAA4B,GAAA,CAAI,eAAA,EAC3C,GAAA,EAAK,MAAA,UACC,IAAA,EAAM,GAAA,CAAI,YAAA,CAAa,MAAA,MAAY,YAAA,CAAa,MAAA"}

package/dist/index.js

@@ -1,27 +1,65 @@
+import { QueryResult_exports, fail, load, succeed } from "./QueryResult.js";
 import { Ref } from "@confect/core";
 import { useAction as useAction$1, useMutation as useMutation$1, useQuery as useQuery$1 } from "convex/react";
+import { Cause, Effect, Either, Exit, Option } from "effect";
 
 //#region src/index.ts
 const useQuery = (ref, ...rest) => {
 	const functionReference = Ref.getFunctionReference(ref);
 	const args = rest[0];
-	const encodedReturnsOrUndefined = useQuery$1(functionReference, args === "skip" ? "skip" : Ref.encodeArgsSync(ref, args ?? {}));
-	if (encodedReturnsOrUndefined === void 0) return;
-	return Ref.decodeReturnsSync(ref, encodedReturnsOrUndefined);
+	const encodedArgs = args === "skip" ? "skip" : Ref.encodeArgsSync(ref, args ?? {});
+	try {
+		const encodedReturnsOrUndefined = useQuery$1(functionReference, encodedArgs);
+		if (encodedReturnsOrUndefined === void 0) return load(args === "skip");
+		return succeed(Ref.decodeReturnsSync(ref, encodedReturnsOrUndefined));
+	} catch (error) {
+		if (Ref.isConvexError(error)) {
+			const decoded = Ref.decodeErrorSync(ref, error.data);
+			if (Option.isSome(decoded)) return fail(decoded.value);
+		}
+		throw error;
+	}
 };
+/**
+* Returns a function that invokes the provided `Ref`'s mutation.
+*
+* If the `Ref` declares an `error` schema, the returned promise resolves to an
+* `Either` with the decoded `returns` value on the right and the decoded error
+* on the left.
+*
+* If the `Ref` does not declare an `error` schema, the promise resolves
+* directly to the decoded `returns` value, matching the behavior of
+* `useMutation` from `convex/react`.
+*
+* Any other failure rejects the promise.
+*/
 const useMutation = (ref) => {
 	const actualMutation = useMutation$1(Ref.getFunctionReference(ref));
-	return (...args) => {
-		return actualMutation(Ref.encodeArgsSync(ref, args[0] ?? {})).then((result) => Ref.decodeReturnsSync(ref, result));
-	};
+	return ((...args) => invokeAsEither(ref, (_, encodedArgs) => actualMutation(encodedArgs), args).then((either) => Ref.hasErrorSchema(ref) ? either : Either.getOrThrow(either)));
 };
+/**
+* Returns a function that invokes the provided `Ref`'s action.
+*
+* If the `Ref` declares an `error` schema, the returned promise resolves to an
+* `Either` with the decoded `returns` value on the right and the decoded error
+* on the left.
+*
+* If the `Ref` does not declare an `error` schema, the promise resolves
+* directly to the decoded `returns` value, matching the behavior of
+* `useMutation` from `convex/react`.
+*
+* Any other failure rejects the promise.
+*/
 const useAction = (ref) => {
 	const actualAction = useAction$1(Ref.getFunctionReference(ref));
-	return (...args) => {
-		return actualAction(Ref.encodeArgsSync(ref, args[0] ?? {})).then((result) => Ref.decodeReturnsSync(ref, result));
-	};
+	return ((...args) => invokeAsEither(ref, (_, encodedArgs) => actualAction(encodedArgs), args).then((either) => Ref.hasErrorSchema(ref) ? either : Either.getOrThrow(either)));
+};
+const invokeAsEither = async (ref, invoke, args) => {
+	const exit = await Effect.runPromiseExit(Ref.runWithCodec(ref, args[0] ?? {}, invoke).pipe(Effect.catchTag("ParseError", Effect.die), Effect.either));
+	if (Exit.isSuccess(exit)) return exit.value;
+	throw Cause.squash(exit.cause);
 };
 
 //#endregion
-export { useAction, useMutation, useQuery };
+export { QueryResult_exports as QueryResult, useAction, useMutation, useQuery };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["useConvexQuery","useConvexMutation","useConvexAction"],"sources":["../src/index.ts"],"sourcesContent":["import { Ref } from \"@confect/core\";\nimport {\n  useAction as useConvexAction,\n  useMutation as useConvexMutation,\n  useQuery as useConvexQuery,\n} from \"convex/react\";\n\ntype UseQueryArgs<Query extends Ref.AnyPublicQuery> =\n  keyof Ref.Args<Query> extends never\n    ? [args?: Ref.Args<Query> | \"skip\"]\n    : [args: Ref.Args<Query> | \"skip\"];\n\nexport const useQuery = <Query extends Ref.AnyPublicQuery>(\n  ref: Query,\n  ...rest: UseQueryArgs<Query>\n): Ref.Returns<Query> | undefined => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const args = rest[0];\n  const encodedArgs =\n    args === \"skip\"\n      ? \"skip\"\n      : Ref.encodeArgsSync(ref, (args ?? {}) as Ref.Args<Query>);\n\n  const encodedReturnsOrUndefined = useConvexQuery(\n    functionReference,\n    encodedArgs,\n  );\n\n  if (encodedReturnsOrUndefined === undefined) {\n    return undefined;\n  }\n\n  return Ref.decodeReturnsSync(ref, encodedReturnsOrUndefined);\n};\n\nexport const useMutation = <Mutation extends Ref.AnyPublicMutation>(\n  ref: Mutation,\n) => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const actualMutation = useConvexMutation(functionReference);\n\n  return (\n    ...args: Ref.OptionalArgs<Mutation>\n  ): Promise<Ref.Returns<Mutation>> => {\n    const encodedArgs = Ref.encodeArgsSync(\n      ref,\n      (args[0] ?? {}) as Ref.Args<Mutation>,\n    );\n    return actualMutation(encodedArgs).then((result) =>\n      Ref.decodeReturnsSync(ref, result),\n    );\n  };\n};\n\nexport const useAction = <Action extends Ref.AnyPublicAction>(ref: Action) => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const actualAction = useConvexAction(functionReference);\n\n  return (...args: Ref.OptionalArgs<Action>): Promise<Ref.Returns<Action>> => {\n    const encodedArgs = Ref.encodeArgsSync(\n      ref,\n      (args[0] ?? {}) as Ref.Args<Action>,\n    );\n    return actualAction(encodedArgs).then((result) =>\n      Ref.decodeReturnsSync(ref, result),\n    );\n  };\n};\n"],"mappings":";;;;AAYA,MAAa,YACX,KACA,GAAG,SACgC;CACnC,MAAM,oBAAoB,IAAI,qBAAqB,IAAI;CACvD,MAAM,OAAO,KAAK;CAMlB,MAAM,4BAA4BA,WAChC,mBALA,SAAS,SACL,SACA,IAAI,eAAe,KAAM,QAAQ,EAAE,CAAqB,CAK7D;AAED,KAAI,8BAA8B,OAChC;AAGF,QAAO,IAAI,kBAAkB,KAAK,0BAA0B;;AAG9D,MAAa,eACX,QACG;CAEH,MAAM,iBAAiBC,cADG,IAAI,qBAAqB,IAAI,CACI;AAE3D,SACE,GAAG,SACgC;AAKnC,SAAO,eAJa,IAAI,eACtB,KACC,KAAK,MAAM,EAAE,CACf,CACiC,CAAC,MAAM,WACvC,IAAI,kBAAkB,KAAK,OAAO,CACnC;;;AAIL,MAAa,aAAiD,QAAgB;CAE5E,MAAM,eAAeC,YADK,IAAI,qBAAqB,IAAI,CACA;AAEvD,SAAQ,GAAG,SAAiE;AAK1E,SAAO,aAJa,IAAI,eACtB,KACC,KAAK,MAAM,EAAE,CACf,CAC+B,CAAC,MAAM,WACrC,IAAI,kBAAkB,KAAK,OAAO,CACnC"}
+{"version":3,"file":"index.js","names":["useConvexQuery","QueryResult.load","QueryResult.succeed","QueryResult.fail","useConvexMutation","useConvexAction"],"sources":["../src/index.ts"],"sourcesContent":["import { Ref } from \"@confect/core\";\nimport {\n  useAction as useConvexAction,\n  useMutation as useConvexMutation,\n  useQuery as useConvexQuery,\n} from \"convex/react\";\nimport { Cause, Effect, Either, Exit, Option } from \"effect\";\n\nimport * as QueryResult from \"./QueryResult\";\n\nexport { QueryResult };\n\nexport type InvokeReturn<Ref_ extends Ref.Any> = [Ref.Error<Ref_>] extends [\n  never,\n]\n  ? Promise<Ref.Returns<Ref_>>\n  : Promise<Either.Either<Ref.Returns<Ref_>, Ref.Error<Ref_>>>;\n\ntype UseQueryArgs<Query extends Ref.AnyPublicQuery> =\n  keyof Ref.Args<Query> extends never\n    ? [args?: Ref.Args<Query> | \"skip\"]\n    : [args: Ref.Args<Query> | \"skip\"];\n\nexport const useQuery = <Query extends Ref.AnyPublicQuery>(\n  ref: Query,\n  ...rest: UseQueryArgs<Query>\n): QueryResult.QueryResult<Ref.Returns<Query>, Ref.Error<Query>> => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const args = rest[0];\n  const encodedArgs =\n    args === \"skip\"\n      ? \"skip\"\n      : Ref.encodeArgsSync(ref, (args ?? {}) as Ref.Args<Query>);\n\n  try {\n    const encodedReturnsOrUndefined = useConvexQuery(\n      functionReference,\n      encodedArgs,\n    );\n\n    if (encodedReturnsOrUndefined === undefined) {\n      return QueryResult.load(args === \"skip\");\n    }\n\n    return QueryResult.succeed(\n      Ref.decodeReturnsSync(ref, encodedReturnsOrUndefined),\n    );\n  } catch (error) {\n    if (Ref.isConvexError(error)) {\n      const decoded = Ref.decodeErrorSync(ref, error.data);\n      if (Option.isSome(decoded)) {\n        return QueryResult.fail(decoded.value);\n      }\n    }\n    throw error;\n  }\n};\n\n/**\n * Returns a function that invokes the provided `Ref`'s mutation.\n *\n * If the `Ref` declares an `error` schema, the returned promise resolves to an\n * `Either` with the decoded `returns` value on the right and the decoded error\n * on the left.\n *\n * If the `Ref` does not declare an `error` schema, the promise resolves\n * directly to the decoded `returns` value, matching the behavior of\n * `useMutation` from `convex/react`.\n *\n * Any other failure rejects the promise.\n */\nexport const useMutation = <Mutation extends Ref.AnyPublicMutation>(\n  ref: Mutation,\n): ((...args: Ref.OptionalArgs<Mutation>) => InvokeReturn<Mutation>) => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const actualMutation = useConvexMutation(functionReference);\n\n  return ((...args: Ref.OptionalArgs<Mutation>) =>\n    invokeAsEither(\n      ref,\n      (_, encodedArgs) => actualMutation(encodedArgs),\n      args,\n    ).then((either) =>\n      Ref.hasErrorSchema(ref) ? either : Either.getOrThrow(either),\n    )) as (...args: Ref.OptionalArgs<Mutation>) => InvokeReturn<Mutation>;\n};\n\n/**\n * Returns a function that invokes the provided `Ref`'s action.\n *\n * If the `Ref` declares an `error` schema, the returned promise resolves to an\n * `Either` with the decoded `returns` value on the right and the decoded error\n * on the left.\n *\n * If the `Ref` does not declare an `error` schema, the promise resolves\n * directly to the decoded `returns` value, matching the behavior of\n * `useMutation` from `convex/react`.\n *\n * Any other failure rejects the promise.\n */\nexport const useAction = <Action extends Ref.AnyPublicAction>(\n  ref: Action,\n): ((...args: Ref.OptionalArgs<Action>) => InvokeReturn<Action>) => {\n  const functionReference = Ref.getFunctionReference(ref);\n  const actualAction = useConvexAction(functionReference);\n\n  return ((...args: Ref.OptionalArgs<Action>) =>\n    invokeAsEither(\n      ref,\n      (_, encodedArgs) => actualAction(encodedArgs),\n      args,\n    ).then((either) =>\n      Ref.hasErrorSchema(ref) ? either : Either.getOrThrow(either),\n    )) as (...args: Ref.OptionalArgs<Action>) => InvokeReturn<Action>;\n};\n\nconst invokeAsEither = async <Ref_ extends Ref.Any>(\n  ref: Ref_,\n  invoke: (\n    fnRef: Ref.FunctionReference<Ref_>,\n    encodedArgs: unknown,\n  ) => PromiseLike<unknown>,\n  args: Ref.OptionalArgs<Ref_>,\n): Promise<Either.Either<Ref.Returns<Ref_>, Ref.Error<Ref_>>> => {\n  const exit = await Effect.runPromiseExit(\n    Ref.runWithCodec(ref, (args[0] ?? {}) as Ref.Args<Ref_>, invoke).pipe(\n      Effect.catchTag(\"ParseError\", Effect.die),\n      Effect.either,\n    ),\n  );\n  if (Exit.isSuccess(exit)) return exit.value;\n  throw Cause.squash(exit.cause);\n};\n"],"mappings":";;;;;;AAuBA,MAAa,YACX,KACA,GAAG,SAC+D;CAClE,MAAM,oBAAoB,IAAI,qBAAqB,IAAI;CACvD,MAAM,OAAO,KAAK;CAClB,MAAM,cACJ,SAAS,SACL,SACA,IAAI,eAAe,KAAM,QAAQ,EAAE,CAAqB;AAE9D,KAAI;EACF,MAAM,4BAA4BA,WAChC,mBACA,YACD;AAED,MAAI,8BAA8B,OAChC,QAAOC,KAAiB,SAAS,OAAO;AAG1C,SAAOC,QACL,IAAI,kBAAkB,KAAK,0BAA0B,CACtD;UACM,OAAO;AACd,MAAI,IAAI,cAAc,MAAM,EAAE;GAC5B,MAAM,UAAU,IAAI,gBAAgB,KAAK,MAAM,KAAK;AACpD,OAAI,OAAO,OAAO,QAAQ,CACxB,QAAOC,KAAiB,QAAQ,MAAM;;AAG1C,QAAM;;;;;;;;;;;;;;;;AAiBV,MAAa,eACX,QACsE;CAEtE,MAAM,iBAAiBC,cADG,IAAI,qBAAqB,IAAI,CACI;AAE3D,UAAS,GAAG,SACV,eACE,MACC,GAAG,gBAAgB,eAAe,YAAY,EAC/C,KACD,CAAC,MAAM,WACN,IAAI,eAAe,IAAI,GAAG,SAAS,OAAO,WAAW,OAAO,CAC7D;;;;;;;;;;;;;;;AAgBL,MAAa,aACX,QACkE;CAElE,MAAM,eAAeC,YADK,IAAI,qBAAqB,IAAI,CACA;AAEvD,UAAS,GAAG,SACV,eACE,MACC,GAAG,gBAAgB,aAAa,YAAY,EAC7C,KACD,CAAC,MAAM,WACN,IAAI,eAAe,IAAI,GAAG,SAAS,OAAO,WAAW,OAAO,CAC7D;;AAGL,MAAM,iBAAiB,OACrB,KACA,QAIA,SAC+D;CAC/D,MAAM,OAAO,MAAM,OAAO,eACxB,IAAI,aAAa,KAAM,KAAK,MAAM,EAAE,EAAqB,OAAO,CAAC,KAC/D,OAAO,SAAS,cAAc,OAAO,IAAI,EACzC,OAAO,OACR,CACF;AACD,KAAI,KAAK,UAAU,KAAK,CAAE,QAAO,KAAK;AACtC,OAAM,MAAM,OAAO,KAAK,MAAM"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@confect/react",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "Client-side bindings for React apps",
   "repository": {
     "type": "git",
@@ -25,6 +25,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
     "./package.json": "./package.json"
   },
   "keywords": [
@@ -35,19 +39,24 @@
   "author": "RJ Dellecese",
   "license": "ISC",
   "devDependencies": {
+    "@effect/vitest": "0.27.0",
     "@eslint/js": "10.0.1",
     "@types/node": "25.3.3",
+    "convex": "1.33.1",
+    "effect": "3.19.19",
     "eslint": "10.0.2",
     "prettier": "3.8.1",
     "tsdown": "0.20.3",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.56.1"
+    "typescript-eslint": "8.56.1",
+    "vite": "7.3.1",
+    "vitest": "3.2.4"
   },
   "peerDependencies": {
     "convex": "^1.30.0",
     "effect": "^3.19.16",
     "react": "^18.0.0 || ^19.0.0",
-    "@confect/core": "6.0.0"
+    "@confect/core": "7.0.0"
   },
   "engines": {
     "node": ">=22",

package/src/QueryResult.ts

@@ -0,0 +1,172 @@
+import { Equal, Function, Hash, identity, Pipeable, Predicate } from "effect";
+
+const TypeId = "@confect/react/QueryResult";
+type TypeId = typeof TypeId;
+
+/**
+ * A `QueryResult` represents the result of a Confect query.
+ *
+ * @typeParam A - The type of the decoded `returns` value in the `Success` variant.
+ * @typeParam E - The type of the decoded typed error in the `Failure` variant.
+ */
+export type QueryResult<A, E = never> =
+  | Loading<A, E>
+  | Success<A, E>
+  | Failure<A, E>;
+
+export declare namespace QueryResult {
+  export interface Proto<A, E> extends Pipeable.Pipeable {
+    readonly [TypeId]: {
+      readonly E: (_: never) => E;
+      readonly A: (_: never) => A;
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-shadow
+  export type Success<R> = R extends QueryResult<infer A, infer _E> ? A : never;
+
+  // eslint-disable-next-line @typescript-eslint/no-shadow
+  export type Failure<R> = R extends QueryResult<infer _A, infer E> ? E : never;
+}
+
+export interface Loading<A, E = never> extends QueryResult.Proto<A, E> {
+  readonly _tag: "Loading";
+  readonly skipped: boolean;
+}
+
+export interface Success<A, E = never> extends QueryResult.Proto<A, E> {
+  readonly _tag: "Success";
+  readonly value: A;
+}
+
+export interface Failure<A, E = never> extends QueryResult.Proto<A, E> {
+  readonly _tag: "Failure";
+  readonly error: E;
+}
+
+export const isQueryResult = (u: unknown): u is QueryResult<unknown, unknown> =>
+  Predicate.hasProperty(u, TypeId);
+
+const QueryResultProto = {
+  [TypeId]: {
+    E: identity,
+    A: identity,
+  },
+  pipe(this: QueryResult<any, any>, ...args: ReadonlyArray<unknown>) {
+    return Pipeable.pipeArguments(
+      this,
+      args as unknown as Parameters<typeof Pipeable.pipeArguments>[1],
+    );
+  },
+  [Equal.symbol](
+    this: QueryResult<any, any>,
+    that: QueryResult<any, any>,
+  ): boolean {
+    if (this._tag !== that._tag) {
+      return false;
+    }
+    switch (this._tag) {
+      case "Loading":
+        return this.skipped === (that as Loading<any, any>).skipped;
+      case "Success":
+        return Equal.equals(this.value, (that as Success<any, any>).value);
+      case "Failure":
+        return Equal.equals(this.error, (that as Failure<any, any>).error);
+    }
+  },
+  [Hash.symbol](this: QueryResult<any, any>): number {
+    const tagHash = Hash.string(this._tag);
+    switch (this._tag) {
+      case "Loading":
+        return Hash.cached(
+          this,
+          Hash.combine(tagHash)(Hash.hash(this.skipped)),
+        );
+      case "Success":
+        return Hash.cached(this, Hash.combine(tagHash)(Hash.hash(this.value)));
+      case "Failure":
+        return Hash.cached(this, Hash.combine(tagHash)(Hash.hash(this.error)));
+    }
+  },
+};
+
+export const load = <A = never, E = never>(skipped: boolean): Loading<A, E> =>
+  Object.assign(Object.create(QueryResultProto), {
+    _tag: "Loading" as const,
+    skipped,
+  });
+
+export const succeed = <A, E = never>(value: A): Success<A, E> =>
+  Object.assign(Object.create(QueryResultProto), {
+    _tag: "Success" as const,
+    value,
+  });
+
+export const fail = <E, A = never>(error: E): Failure<A, E> =>
+  Object.assign(Object.create(QueryResultProto), {
+    _tag: "Failure" as const,
+    error,
+  });
+
+export const isLoading = <A, E>(
+  queryResult: QueryResult<A, E>,
+): queryResult is Loading<A, E> => queryResult._tag === "Loading";
+
+export const isSuccess = <A, E>(
+  queryResult: QueryResult<A, E>,
+): queryResult is Success<A, E> => queryResult._tag === "Success";
+
+export const isFailure = <A, E>(
+  queryResult: QueryResult<A, E>,
+): queryResult is Failure<A, E> => queryResult._tag === "Failure";
+
+type MatchOptions<A, E, X, Y, Z> = {
+  readonly onLoading: (skipped: boolean) => X;
+  readonly onSuccess: (value: A) => Y;
+} & ([E] extends [never] ? {} : { readonly onFailure: (error: E) => Z });
+
+type MatchReturns<E, X, Y, Z> = [E] extends [never] ? X | Y : X | Y | Z;
+
+/**
+ * Matches a {@link QueryResult} to the appropriate handler based on its tag. If
+ * the provided `QueryResult` cannot fail (i.e. `E` is `never`), `onFailure` is
+ * not required.
+ *
+ * @example
+ * ```tsx
+ * const result = QueryResult.match(queryResult, {
+ *   onLoading: (skipped) => skipped ? null : <p>Loading…</p>,
+ *   onSuccess: (value) => <p>{value.text}</p>,
+ *   onFailure: (error) => <p>Error: {error.message}</p>,
+ * });
+ */
+export const match: {
+  <A, E, X, Y, Z = never>(
+    options: MatchOptions<A, E, X, Y, Z>,
+  ): (self: QueryResult<A, E>) => MatchReturns<E, X, Y, Z>;
+  <A, E, X, Y, Z = never>(
+    self: QueryResult<A, E>,
+    options: MatchOptions<A, E, X, Y, Z>,
+  ): MatchReturns<E, X, Y, Z>;
+} = Function.dual(
+  2,
+  <A, E, X, Y, Z = never>(
+    self: QueryResult<A, E>,
+    options: MatchOptions<A, E, X, Y, Z>,
+  ): MatchReturns<E, X, Y, Z> => {
+    switch (self._tag) {
+      case "Loading":
+        return options.onLoading(self.skipped);
+      case "Success":
+        return options.onSuccess(self.value);
+      case "Failure": {
+        if (Predicate.hasProperty(options, "onFailure")) {
+          return options.onFailure(self.error) as MatchReturns<E, X, Y, Z>;
+        }
+        throw new Error(
+          "`onFailure` is required when error schema is provided",
+        );
+      }
+    }
+  },
+);

package/src/index.ts

@@ -4,6 +4,17 @@ import {
   useMutation as useConvexMutation,
   useQuery as useConvexQuery,
 } from "convex/react";
+import { Cause, Effect, Either, Exit, Option } from "effect";
+
+import * as QueryResult from "./QueryResult";
+
+export { QueryResult };
+
+export type InvokeReturn<Ref_ extends Ref.Any> = [Ref.Error<Ref_>] extends [
+  never,
+]
+  ? Promise<Ref.Returns<Ref_>>
+  : Promise<Either.Either<Ref.Returns<Ref_>, Ref.Error<Ref_>>>;
 
 type UseQueryArgs<Query extends Ref.AnyPublicQuery> =
   keyof Ref.Args<Query> extends never
@@ -13,7 +24,7 @@ type UseQueryArgs<Query extends Ref.AnyPublicQuery> =
 export const useQuery = <Query extends Ref.AnyPublicQuery>(
   ref: Query,
   ...rest: UseQueryArgs<Query>
-): Ref.Returns<Query> | undefined => {
+): QueryResult.QueryResult<Ref.Returns<Query>, Ref.Error<Query>> => {
   const functionReference = Ref.getFunctionReference(ref);
   const args = rest[0];
   const encodedArgs =
@@ -21,48 +32,102 @@ export const useQuery = <Query extends Ref.AnyPublicQuery>(
       ? "skip"
       : Ref.encodeArgsSync(ref, (args ?? {}) as Ref.Args<Query>);
 
-  const encodedReturnsOrUndefined = useConvexQuery(
-    functionReference,
-    encodedArgs,
-  );
+  try {
+    const encodedReturnsOrUndefined = useConvexQuery(
+      functionReference,
+      encodedArgs,
+    );
 
-  if (encodedReturnsOrUndefined === undefined) {
-    return undefined;
-  }
+    if (encodedReturnsOrUndefined === undefined) {
+      return QueryResult.load(args === "skip");
+    }
 
-  return Ref.decodeReturnsSync(ref, encodedReturnsOrUndefined);
+    return QueryResult.succeed(
+      Ref.decodeReturnsSync(ref, encodedReturnsOrUndefined),
+    );
+  } catch (error) {
+    if (Ref.isConvexError(error)) {
+      const decoded = Ref.decodeErrorSync(ref, error.data);
+      if (Option.isSome(decoded)) {
+        return QueryResult.fail(decoded.value);
+      }
+    }
+    throw error;
+  }
 };
 
+/**
+ * Returns a function that invokes the provided `Ref`'s mutation.
+ *
+ * If the `Ref` declares an `error` schema, the returned promise resolves to an
+ * `Either` with the decoded `returns` value on the right and the decoded error
+ * on the left.
+ *
+ * If the `Ref` does not declare an `error` schema, the promise resolves
+ * directly to the decoded `returns` value, matching the behavior of
+ * `useMutation` from `convex/react`.
+ *
+ * Any other failure rejects the promise.
+ */
 export const useMutation = <Mutation extends Ref.AnyPublicMutation>(
   ref: Mutation,
-) => {
+): ((...args: Ref.OptionalArgs<Mutation>) => InvokeReturn<Mutation>) => {
   const functionReference = Ref.getFunctionReference(ref);
   const actualMutation = useConvexMutation(functionReference);
 
-  return (
-    ...args: Ref.OptionalArgs<Mutation>
-  ): Promise<Ref.Returns<Mutation>> => {
-    const encodedArgs = Ref.encodeArgsSync(
+  return ((...args: Ref.OptionalArgs<Mutation>) =>
+    invokeAsEither(
       ref,
-      (args[0] ?? {}) as Ref.Args<Mutation>,
-    );
-    return actualMutation(encodedArgs).then((result) =>
-      Ref.decodeReturnsSync(ref, result),
-    );
-  };
+      (_, encodedArgs) => actualMutation(encodedArgs),
+      args,
+    ).then((either) =>
+      Ref.hasErrorSchema(ref) ? either : Either.getOrThrow(either),
+    )) as (...args: Ref.OptionalArgs<Mutation>) => InvokeReturn<Mutation>;
 };
 
-export const useAction = <Action extends Ref.AnyPublicAction>(ref: Action) => {
+/**
+ * Returns a function that invokes the provided `Ref`'s action.
+ *
+ * If the `Ref` declares an `error` schema, the returned promise resolves to an
+ * `Either` with the decoded `returns` value on the right and the decoded error
+ * on the left.
+ *
+ * If the `Ref` does not declare an `error` schema, the promise resolves
+ * directly to the decoded `returns` value, matching the behavior of
+ * `useMutation` from `convex/react`.
+ *
+ * Any other failure rejects the promise.
+ */
+export const useAction = <Action extends Ref.AnyPublicAction>(
+  ref: Action,
+): ((...args: Ref.OptionalArgs<Action>) => InvokeReturn<Action>) => {
   const functionReference = Ref.getFunctionReference(ref);
   const actualAction = useConvexAction(functionReference);
 
-  return (...args: Ref.OptionalArgs<Action>): Promise<Ref.Returns<Action>> => {
-    const encodedArgs = Ref.encodeArgsSync(
+  return ((...args: Ref.OptionalArgs<Action>) =>
+    invokeAsEither(
       ref,
-      (args[0] ?? {}) as Ref.Args<Action>,
-    );
-    return actualAction(encodedArgs).then((result) =>
-      Ref.decodeReturnsSync(ref, result),
-    );
-  };
+      (_, encodedArgs) => actualAction(encodedArgs),
+      args,
+    ).then((either) =>
+      Ref.hasErrorSchema(ref) ? either : Either.getOrThrow(either),
+    )) as (...args: Ref.OptionalArgs<Action>) => InvokeReturn<Action>;
+};
+
+const invokeAsEither = async <Ref_ extends Ref.Any>(
+  ref: Ref_,
+  invoke: (
+    fnRef: Ref.FunctionReference<Ref_>,
+    encodedArgs: unknown,
+  ) => PromiseLike<unknown>,
+  args: Ref.OptionalArgs<Ref_>,
+): Promise<Either.Either<Ref.Returns<Ref_>, Ref.Error<Ref_>>> => {
+  const exit = await Effect.runPromiseExit(
+    Ref.runWithCodec(ref, (args[0] ?? {}) as Ref.Args<Ref_>, invoke).pipe(
+      Effect.catchTag("ParseError", Effect.die),
+      Effect.either,
+    ),
+  );
+  if (Exit.isSuccess(exit)) return exit.value;
+  throw Cause.squash(exit.cause);
 };