@confect/core 10.0.0-next.18 → 10.0.0-next.19

package/src/PaginationError.ts

@@ -0,0 +1,72 @@
+import { ConvexError } from "convex/values";
+import type { Value } from "convex/values";
+import * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+/** A Convex pagination cursor that no longer describes the current query. */
+export class InvalidCursor extends Schema.TaggedError<InvalidCursor>()(
+  "InvalidCursor",
+  {
+    cause: Schema.Defect(),
+  },
+) {}
+
+interface InvalidCursorData {
+  readonly isConvexSystemError: true;
+  readonly paginationError: "InvalidCursor";
+}
+
+const ConvexErrorIdentifier = Symbol.for("ConvexError");
+
+const isConvexError = (error: unknown): error is ConvexError<Value> =>
+  error instanceof ConvexError ||
+  (typeof error === "object" &&
+    error !== null &&
+    ConvexErrorIdentifier in error);
+
+const isInvalidCursorData = (value: unknown): value is InvalidCursorData =>
+  typeof value === "object" &&
+  value !== null &&
+  "isConvexSystemError" in value &&
+  value.isConvexSystemError === true &&
+  "paginationError" in value &&
+  value.paginationError === "InvalidCursor";
+
+const fromErrorMessage = (
+  error: globalThis.Error,
+): Option.Option<InvalidCursor> =>
+  error.message.includes("InvalidCursor")
+    ? Option.some(new InvalidCursor({ cause: error }))
+    : Option.none();
+
+/** Recognizes an invalid-cursor error emitted by a Convex query. */
+export const fromConvexQueryError = (
+  error: unknown,
+): Option.Option<InvalidCursor> =>
+  Match.value(error).pipe(
+    Match.when(isConvexError, (convexError) =>
+      Match.value(isInvalidCursorData(convexError.data)).pipe(
+        Match.when(true, () =>
+          Option.some(new InvalidCursor({ cause: error })),
+        ),
+        Match.when(false, () => fromErrorMessage(convexError)),
+        Match.exhaustive,
+      ),
+    ),
+    Match.when(Match.instanceOf(globalThis.Error), fromErrorMessage),
+    Match.when(Match.any, () => Option.none<InvalidCursor>()),
+    Match.exhaustive,
+  );
+
+/** Recognizes the error data attached to Convex's invalid-cursor error. */
+export const fromConvexErrorData = (
+  errorData: unknown,
+): Option.Option<InvalidCursor> =>
+  Match.value(errorData).pipe(
+    Match.when(isInvalidCursorData, (cause) =>
+      Option.some(new InvalidCursor({ cause })),
+    ),
+    Match.when(Match.any, () => Option.none<InvalidCursor>()),
+    Match.exhaustive,
+  );

package/src/Ref.ts

@@ -1,4 +1,5 @@
 import type {
+  DefaultFunctionArgs,
   FunctionReference as ConvexFunctionReference,
   FunctionVisibility,
   PaginationOptions,
@@ -20,7 +21,7 @@ import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType";
 export interface Base<
   RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
   FunctionVisibility_ extends FunctionVisibility,
-  Args_,
+  Args_ extends DefaultFunctionArgs,
   Returns_,
   Error_ = never,
 > {
@@ -29,7 +30,6 @@ export interface Base<
   readonly "~Args": Args_;
   readonly "~Returns": Returns_;
   readonly "~Error": Error_;
-  /** @internal */
   readonly convexFunctionName: string;
 }
 
@@ -41,13 +41,14 @@ export interface Base<
 export type Ref<
   RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
   FunctionVisibility_ extends FunctionVisibility,
-  Args_,
+  Args_ extends DefaultFunctionArgs,
   Returns_,
   Error_ = never,
 > =
-  | ConfectRef<
+  | ConfectRefWithTypes<
       RuntimeAndFunctionType_,
       FunctionVisibility_,
+      FunctionProvenance.ArgsFields,
       Args_,
       Returns_,
       Error_
@@ -60,12 +61,35 @@ export type Ref<
       Error_
     >;
 
-export interface ConfectRef<
+export type ConfectRef<
   RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
   FunctionVisibility_ extends FunctionVisibility,
-  Args_,
+  ArgsFields_ extends FunctionProvenance.ArgsFields,
+  ReturnsSchema_ extends Schema.Codec<any, any>,
+  ErrorSchema_ extends Schema.Codec<any, any> = never,
+  MiddlewareError_ = never,
+> = ConfectRefWithTypes<
+  RuntimeAndFunctionType_,
+  FunctionVisibility_,
+  ArgsFields_,
+  Schema.Struct.Type<ArgsFields_>,
+  ReturnsSchema_["Type"],
+  ErrorSchema_["Type"] | MiddlewareError_
+>;
+
+/**
+ * Internal form used while mapping a spec to a ref. Supplying the already
+ * derived value types avoids repeatedly expanding `Schema.Struct` for every
+ * leaf in a generated ref tree; the public `ConfectRef` alias still derives
+ * the same values from its fields and schemas.
+ */
+interface ConfectRefWithTypes<
+  RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  ArgsFields_ extends FunctionProvenance.ArgsFields,
+  Args_ extends DefaultFunctionArgs,
   Returns_,
-  Error_ = never,
+  Error_,
 > extends Base<
   RuntimeAndFunctionType_,
   FunctionVisibility_,
@@ -73,24 +97,18 @@ export interface ConfectRef<
   Returns_,
   Error_
 > {
-  /** @internal */
   readonly _tag: "Confect";
-  /** @internal */
-  readonly args: Schema.Codec<any, any>;
-  /** @internal */
+  readonly args: FunctionProvenance.ArgsSchema<ArgsFields_>;
   readonly returns: Schema.Codec<any, any>;
-  /** @internal */
   readonly kind: FunctionProvenance.ConfectKind;
-  /** @internal */
   readonly middlewareSpecs: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec>;
-  /** @internal */
   readonly error?: Schema.Codec<any, any>;
 }
 
 export interface ConvexRef<
   RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
   FunctionVisibility_ extends FunctionVisibility,
-  Args_,
+  Args_ extends DefaultFunctionArgs,
   Returns_,
   Error_ = never,
 > extends Base<
@@ -100,12 +118,14 @@ export interface ConvexRef<
   Returns_,
   Error_
 > {
-  /** @internal */
   readonly _tag: "Convex";
 }
 
 export type Any = Ref<any, any, any, any, any>;
 
+/** Erased Confect-provenance ref used by provenance-specific APIs. */
+export type AnyConfect = Extract<Any, { readonly _tag: "Confect" }>;
+
 export type AnyInternal = Ref<any, "internal", any, any, any>;
 
 export type AnyPublic = Ref<any, "public", any, any, any>;
@@ -118,16 +138,17 @@ export type AnyQuery = Ref<
   any
 >;
 
-export type AnyPublicPaginatedQuery = Ref<
-  RuntimeAndFunctionType.AnyQuery,
-  "public",
-  {
-    [key: string]: any;
-    paginationOpts: PaginationOptions;
-  },
-  PaginationResult<any>,
-  any
->;
+export type AnyPaginatedQuery = AnyQuery &
+  Base<
+    RuntimeAndFunctionType.AnyQuery,
+    FunctionVisibility,
+    {
+      [key: string]: any;
+      paginationOpts: PaginationOptions;
+    },
+    PaginationResult<any>,
+    any
+  >;
 
 export type AnyMutation = Ref<
   RuntimeAndFunctionType.AnyMutation,
@@ -153,6 +174,13 @@ export type AnyPublicQuery = Ref<
   any
 >;
 
+export type AnyConfectPublicQuery = Extract<AnyPublicQuery, AnyConfect>;
+
+export type AnyPublicPaginatedQuery = AnyPublicQuery & AnyPaginatedQuery;
+
+export type AnyConfectPublicPaginatedQuery = AnyConfectPublicQuery &
+  AnyPublicPaginatedQuery;
+
 export type AnyPublicMutation = Ref<
   RuntimeAndFunctionType.AnyMutation,
   "public",
@@ -161,6 +189,8 @@ export type AnyPublicMutation = Ref<
   any
 >;
 
+export type AnyConfectPublicMutation = Extract<AnyPublicMutation, AnyConfect>;
+
 export type AnyPublicAction = Ref<
   RuntimeAndFunctionType.AnyAction,
   "public",
@@ -169,6 +199,8 @@ export type AnyPublicAction = Ref<
   any
 >;
 
+export type AnyConfectPublicAction = Extract<AnyPublicAction, AnyConfect>;
+
 export type GetRuntimeAndFunctionType<Ref_> = Ref_ extends {
   readonly "~RuntimeAndFunctionType": infer RuntimeAndFunctionType_ extends
     RuntimeAndFunctionType.RuntimeAndFunctionType;
@@ -194,6 +226,24 @@ export type Args<Ref_> = Ref_ extends { readonly "~Args": infer Args_ }
   ? Args_
   : never;
 
+/** The field map captured by a Confect-provenance ref. */
+export type ArgsFields<Ref_> = Ref_ extends {
+  readonly _tag: "Confect";
+  readonly args: {
+    readonly fields: infer ArgsFields_ extends FunctionProvenance.ArgsFields;
+  };
+}
+  ? ArgsFields_
+  : never;
+
+/** The assembled args schema carried by a Confect-provenance ref. */
+export type ArgsSchema<Ref_> = Ref_ extends {
+  readonly _tag: "Confect";
+  readonly args: infer ArgsSchema_ extends FunctionProvenance.AnyArgsSchema;
+}
+  ? ArgsSchema_
+  : never;
+
 export type OptionalArgs<Ref_ extends Any> = keyof Args<Ref_> extends never
   ? [args?: Args<Ref_>]
   : [args: Args<Ref_>];
@@ -218,6 +268,7 @@ export type FromFunctionSpec<
   FunctionSpec_,
   FunctionSpec.GetRuntimeAndFunctionType<FunctionSpec_>,
   FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
+  FunctionSpec.ArgsFields<FunctionSpec_>,
   FunctionSpec.Args<FunctionSpec_>,
   FunctionSpec.Returns<FunctionSpec_>,
   FunctionSpec.Error<FunctionSpec_> | MiddlewareError
@@ -227,7 +278,8 @@ type FromFunctionSpecHelper<
   FunctionSpec_ extends FunctionSpec.AnyWithProps,
   RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
   FunctionVisibility_ extends FunctionVisibility,
-  Args_,
+  ArgsFields_ extends FunctionProvenance.ArgsFields,
+  Args_ extends DefaultFunctionArgs,
   Returns_,
   Error_,
 > =
@@ -238,17 +290,18 @@ type FromFunctionSpecHelper<
     ? ConvexRef<
         RuntimeAndFunctionType_,
         FunctionVisibility_,
-        Args_,
+        Args_ extends DefaultFunctionArgs ? Args_ : never,
         Returns_,
-        Error_
+        never
       >
     : FunctionSpec_ extends FunctionSpec.WithFunctionProvenance<
           FunctionSpec_,
           FunctionProvenance.AnyConfect
         >
-      ? ConfectRef<
+      ? ConfectRefWithTypes<
           RuntimeAndFunctionType_,
           FunctionVisibility_,
+          ArgsFields_,
           Args_,
           Returns_,
           Error_
@@ -517,14 +570,12 @@ const missingPaginatedProvenanceError = (ref: Any) =>
       "those constructors store. Define the function as, e.g.:\n\n" +
       "  FunctionSpec.publicPaginatedQuery({\n" +
       '    name: "...",\n' +
-      "    args: () => Schema.Struct({ ... }), // optional; without paginationOpts\n" +
+      "    args: () => ({ ... }), // optional; without paginationOpts\n" +
       "    item: () => ItemSchema,\n" +
       "  })",
   );
 
-const paginatedKind = (
-  ref: ConfectRef<any, any, any, any, any>,
-): FunctionProvenance.Paginated =>
+const paginatedKind = (ref: AnyConfect): FunctionProvenance.Paginated =>
   Match.value(ref.kind).pipe(
     Match.tag("Paginated", (kind) => kind),
     Match.tag("Standard", () => {

package/src/Refs.ts

@@ -42,6 +42,7 @@ type FunctionSpecMatchesPredicate<
     FunctionSpec.GetRuntimeAndFunctionType<FunctionSpec_>,
     FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
     any,
+    any,
     any
   > extends Predicate
     ? true

package/src/index.ts

@@ -6,6 +6,7 @@ export * as GroupSpec from "./GroupSpec";
 export * as Identifier from "./Identifier";
 export * as Lazy from "./Lazy";
 export * as MiddlewareSpec from "./MiddlewareSpec";
+export * as PaginationError from "./PaginationError";
 export * as PaginationOptions from "./PaginationOptions";
 export * as PaginationResult from "./PaginationResult";
 export * as Ref from "./Ref";