@confect/core 10.0.0-next.2 → 10.0.0-next.21

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/PaginationOptions.ts

@@ -0,0 +1,23 @@
+import * as Schema from "effect/Schema";
+
+/**
+ * Schema for the `paginationOpts` argument that every paginated query
+ * receives. Mirrors `paginationOptsValidator` from `convex/server`.
+ *
+ * Use this as the `paginationOpts` field of a paginated query's args schema.
+ * Beyond `numItems` and `cursor`, Convex's pagination protocol sends the
+ * optional fields (`endCursor`, `id`, `maximumRowsRead`, `maximumBytesRead`)
+ * with real requests — most notably `usePaginatedQuery` from `convex/react`
+ * always includes `id`, and includes `endCursor` when splitting pages.
+ * Declaring them is required for the generated Convex argument validator to
+ * accept those requests and for the fields to survive decoding and reach
+ * `paginate`.
+ */
+export const PaginationOptions = Schema.Struct({
+  numItems: Schema.Finite,
+  cursor: Schema.Union([Schema.String, Schema.Null]),
+  endCursor: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  id: Schema.optionalKey(Schema.Finite),
+  maximumRowsRead: Schema.optionalKey(Schema.Finite),
+  maximumBytesRead: Schema.optionalKey(Schema.Finite),
+});

package/src/PaginationResult.ts

@@ -1,5 +1,9 @@
 import * as Schema from "effect/Schema";
 
+export type PaginationResult<Doc extends Schema.Codec<any, any>> = ReturnType<
+  typeof PaginationResult<Doc>
+>;
+
 export const PaginationResult = <Doc extends Schema.Codec<any, any>>(
   Doc: Doc,
 ) =>