@vantreeseba/drizzle-graphql 5.2.0 → 5.3.0

package/README.md

@@ -405,6 +405,53 @@ supplies no `orderBy`:
 An explicit `orderBy` always takes precedence, composite primary keys are ordered by every
 key column, and an unpaginated list query is left unordered so no sort is paid for.
 
+## Cursor pagination
+
+`OFFSET` pagination degrades linearly and shifts under concurrent writes. List queries also
+support keyset pagination: every row returned by a list query exposes an opaque `cursor`
+field, and passing it back as `after` resumes strictly after that row.
+
+```graphql
+{
+    posts(orderBy: { createdAt: { direction: desc, priority: 1 } }, limit: 10) {
+        id
+        createdAt
+        cursor
+    }
+}
+
+# next page — same orderBy, plus the last row's cursor
+{
+    posts(
+        orderBy: { createdAt: { direction: desc, priority: 1 } }
+        limit: 10
+        after: "eyJvIjogW1siY3JlYXRlZEF0IiwgImRlc2MiXSwgWyJpZCIsICJhc2MiXV0sIC4uLn0"
+    ) {
+        id
+        createdAt
+        cursor
+    }
+}
+```
+
+-   The cursor encodes the row's position in the query's **total order** — your `orderBy`
+    columns plus the primary key as an ascending tiebreak — so pages are stable even when
+    the ordered columns aren't unique, and inserts or deletes mid-scroll don't shift the
+    window
+-   `after` compiles to a keyset predicate built from drizzle's `and`/`or`/`gt`/`lt`
+    comparisons (not SQL row-value syntax), so mixed-direction `orderBy` works
+-   `NULL`s in ordered columns follow each dialect's native `ORDER BY` placement —
+    PostgreSQL sorts them largest (last in `asc`), MySQL and SQLite smallest (first in
+    `asc`) — and the predicate matches, so rows with `NULL` in an ordered column are paged
+    through, not skipped
+-   Dates and bigints round-trip losslessly through the cursor
+-   A cursor is only valid under the ordering it was issued for — reusing it with a
+    different `orderBy` (or a malformed/corrupted cursor) returns a `GraphQLError`
+-   `after` cannot be combined with `distinct`, and a table with no primary key cannot use
+    cursor pagination (its `cursor` field resolves to `null`)
+-   If a table has a real column named `cursor`, the column wins and the meta field is
+    skipped
+
 ## Upsert
 
 `features.upsert` adds a pair of mutations per table that insert rows, or update the ones

package/dist/README.md

@@ -405,6 +405,53 @@ supplies no `orderBy`:
 An explicit `orderBy` always takes precedence, composite primary keys are ordered by every
 key column, and an unpaginated list query is left unordered so no sort is paid for.
 
+## Cursor pagination
+
+`OFFSET` pagination degrades linearly and shifts under concurrent writes. List queries also
+support keyset pagination: every row returned by a list query exposes an opaque `cursor`
+field, and passing it back as `after` resumes strictly after that row.
+
+```graphql
+{
+    posts(orderBy: { createdAt: { direction: desc, priority: 1 } }, limit: 10) {
+        id
+        createdAt
+        cursor
+    }
+}
+
+# next page — same orderBy, plus the last row's cursor
+{
+    posts(
+        orderBy: { createdAt: { direction: desc, priority: 1 } }
+        limit: 10
+        after: "eyJvIjogW1siY3JlYXRlZEF0IiwgImRlc2MiXSwgWyJpZCIsICJhc2MiXV0sIC4uLn0"
+    ) {
+        id
+        createdAt
+        cursor
+    }
+}
+```
+
+-   The cursor encodes the row's position in the query's **total order** — your `orderBy`
+    columns plus the primary key as an ascending tiebreak — so pages are stable even when
+    the ordered columns aren't unique, and inserts or deletes mid-scroll don't shift the
+    window
+-   `after` compiles to a keyset predicate built from drizzle's `and`/`or`/`gt`/`lt`
+    comparisons (not SQL row-value syntax), so mixed-direction `orderBy` works
+-   `NULL`s in ordered columns follow each dialect's native `ORDER BY` placement —
+    PostgreSQL sorts them largest (last in `asc`), MySQL and SQLite smallest (first in
+    `asc`) — and the predicate matches, so rows with `NULL` in an ordered column are paged
+    through, not skipped
+-   Dates and bigints round-trip losslessly through the cursor
+-   A cursor is only valid under the ordering it was issued for — reusing it with a
+    different `orderBy` (or a malformed/corrupted cursor) returns a `GraphQLError`
+-   `after` cannot be combined with `distinct`, and a table with no primary key cannot use
+    cursor pagination (its `cursor` field resolves to `null`)
+-   If a table has a real column named `cursor`, the column wins and the meta field is
+    skipped
+
 ## Upsert
 
 `features.upsert` adds a pair of mutations per table that insert rows, or update the ones

package/dist/index.cjs

@@ -1013,6 +1013,13 @@ var generateTableSelectTypeFieldsCached = (table, tableName) => {
       drizzleColumnToGraphQLType(columnDescription, columnName, tableName)
     ])
   );
+  if (!remapped[CURSOR_FIELD_NAME]) {
+    remapped[CURSOR_FIELD_NAME] = {
+      type: import_graphql4.GraphQLString,
+      description: "Opaque cursor of this row's position in the query's ordering. Pass it as `after` to resume from here. Only set on rows returned by a list query.",
+      resolve: rowCursorResolver
+    };
+  }
   fieldMap.set(table, remapped);
   return remapped;
 };
@@ -1840,6 +1847,117 @@ var primaryKeyOrderExprs = (table, pkNames) => {
   const cols = (0, import_drizzle_orm3.getColumns)(table);
   return pkNames.map((n) => cols[n]).filter(Boolean).map((col) => (0, import_drizzle_orm3.asc)(col));
 };
+var CURSOR_FIELD_NAME = "cursor";
+var ROW_CURSOR_PROP = "__drizzle_graphql_cursor";
+var orderByHasRelationEntry = (orderBy) => !!orderBy && Object.values(orderBy).some((config) => config && typeof config === "object" && config.direction === void 0);
+var cursorOrderingEntries = (orderBy, pkNames) => {
+  const entries = orderBy ? orderByEntries(orderBy) : [];
+  const seen = new Set(entries.map(([column]) => column));
+  for (const pk of pkNames) {
+    if (!seen.has(pk)) {
+      entries.push([pk, "asc"]);
+    }
+  }
+  return entries;
+};
+var cursorOrderExprs = (table, entries) => {
+  const cols = (0, import_drizzle_orm3.getColumns)(table);
+  return entries.flatMap(
+    ([column, direction, nulls]) => orderExpressions(cols[column], direction, nulls ?? void 0, cols[column])
+  );
+};
+var encodeCursorValue = (value) => {
+  if (value instanceof Date) {
+    return { $type: "date", value: value.toISOString() };
+  }
+  if (typeof value === "bigint") {
+    return { $type: "bigint", value: value.toString() };
+  }
+  return value;
+};
+var decodeCursorValue = (value) => {
+  if (value && typeof value === "object" && typeof value.$type === "string") {
+    if (value.$type === "date") {
+      return new Date(value.value);
+    }
+    if (value.$type === "bigint") {
+      return BigInt(value.value);
+    }
+  }
+  return value;
+};
+var encodeCursor = (entries, row) => {
+  const payload = {
+    o: entries,
+    v: entries.map(([column]) => encodeCursorValue(row[column] ?? null))
+  };
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+};
+var decodeCursor = (after, entries) => {
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(after, "base64url").toString("utf8"));
+  } catch (_e) {
+    throw new import_graphql4.GraphQLError("Invalid cursor: unable to decode it. Pass a cursor returned by a previous page.");
+  }
+  if (!payload || typeof payload !== "object" || !Array.isArray(payload.o) || !Array.isArray(payload.v) || payload.o.length !== payload.v.length) {
+    throw new import_graphql4.GraphQLError("Invalid cursor: malformed payload. Pass a cursor returned by a previous page.");
+  }
+  const matchesOrdering = payload.o.length === entries.length && payload.o.every(
+    (entry, i) => Array.isArray(entry) && entry[0] === entries[i][0] && entry[1] === entries[i][1] && // The nulls override changes where NULLs sort, so it is part of the ordering identity.
+    // JSON round-trips undefined as null — compare the normalized forms.
+    (entry[2] ?? null) === (entries[i][2] ?? null)
+  );
+  if (!matchesOrdering) {
+    throw new import_graphql4.GraphQLError(
+      "Invalid cursor: it was issued for a different ordering. Pass the same orderBy the cursor's page used."
+    );
+  }
+  return payload.v.map(decodeCursorValue);
+};
+var buildCursorCondition = (table, entries, values, nullOrdering) => {
+  const cols = (0, import_drizzle_orm3.getColumns)(table);
+  const disjuncts = [];
+  const equalities = [];
+  entries.forEach(([column, direction, nulls], i) => {
+    const col = cols[column];
+    if (!col) {
+      throw new import_graphql4.GraphQLError(`Invalid cursor: unknown column '${column}'.`);
+    }
+    const value = values[i];
+    const nullsSortLast = nulls != null ? nulls === "last" : direction === "asc" === (nullOrdering === "nulls-largest");
+    let strictlyAfter;
+    if (value === null || value === void 0) {
+      strictlyAfter = nullsSortLast ? void 0 : (0, import_drizzle_orm3.isNotNull)(col);
+    } else {
+      const comparison = direction === "asc" ? (0, import_drizzle_orm3.gt)(col, value) : (0, import_drizzle_orm3.lt)(col, value);
+      strictlyAfter = nullsSortLast ? (0, import_drizzle_orm3.or)(comparison, (0, import_drizzle_orm3.isNull)(col)) : comparison;
+    }
+    if (strictlyAfter) {
+      disjuncts.push(equalities.length ? (0, import_drizzle_orm3.and)(...equalities, strictlyAfter) : strictlyAfter);
+    }
+    equalities.push(value === null || value === void 0 ? (0, import_drizzle_orm3.isNull)(col) : (0, import_drizzle_orm3.eq)(col, value));
+  });
+  if (!disjuncts.length) {
+    return import_drizzle_orm3.sql`1 = 0`;
+  }
+  return disjuncts.length > 1 ? (0, import_drizzle_orm3.or)(...disjuncts) : disjuncts[0];
+};
+var isCursorFieldSelected = (tree, table) => {
+  if (!tree) {
+    return false;
+  }
+  if ((0, import_drizzle_orm3.getColumns)(table)[CURSOR_FIELD_NAME]) {
+    return false;
+  }
+  return Object.values(tree).some((field) => field.name === CURSOR_FIELD_NAME);
+};
+var attachRowCursors = (rows, entries) => {
+  for (const row of rows) {
+    row[ROW_CURSOR_PROP] = encodeCursor(entries, row);
+  }
+};
+var rowCursorResolver = (source) => source?.[ROW_CURSOR_PROP] ?? null;
 var getUniqueColumnSets = (table, getTableConfig4) => {
   const cols = (0, import_drizzle_orm3.getColumns)(table);
   const propNameByColumnName = new Map(Object.entries(cols).map(([propName, col]) => [col.name, propName]));
@@ -2164,6 +2282,10 @@ var selectArrayArgs = (orderArgs, filterArgs, distinctEnum) => ({
   limit: { type: import_graphql4.GraphQLInt },
   orderBy: { type: orderArgs },
   where: { type: filterArgs },
+  after: {
+    type: import_graphql4.GraphQLString,
+    description: "Keyset pagination: only return rows strictly after this cursor (a row's `cursor` field from a previous page, under the same orderBy)."
+  },
   ...distinctEnum ? { distinct: { type: new import_graphql4.GraphQLList(new import_graphql4.GraphQLNonNull(distinctEnum)) } } : {}
 });
 var selectSingleArgs = (orderArgs, filterArgs) => ({
@@ -2186,9 +2308,31 @@ var runRelationalSelect = async (opts) => {
     where,
     single,
     filterCtx,
-    pkNames
+    pkNames,
+    after
   } = opts;
   const distinct = opts.distinct?.length ? opts.distinct : void 0;
+  const cursorSelected = !single && isCursorFieldSelected(parsedInfo.fieldsByTypeName[typeName], table);
+  let cursorEntries;
+  if (!single && (after != null || cursorSelected)) {
+    if (after != null && distinct) {
+      throw new import_graphql4.GraphQLError("'after' cannot be combined with 'distinct'.");
+    }
+    if (orderByHasRelationEntry(orderBy)) {
+      if (after != null) {
+        throw new import_graphql4.GraphQLError(
+          "'after' cannot be combined with an orderBy that orders through a relation \u2014 a related row's value cannot be encoded into a cursor."
+        );
+      }
+    } else if (!pkNames?.length) {
+      if (after != null) {
+        throw new import_graphql4.GraphQLError(`Table ${tableName} has no primary key, so cursor pagination cannot be used on it.`);
+      }
+    } else {
+      cursorEntries = cursorOrderingEntries(orderBy, pkNames);
+    }
+  }
+  const cursorValues = after != null && cursorEntries ? decodeCursor(after, cursorEntries) : void 0;
   const needsDefaultOrder = single || offset != null || opts.limit != null;
   let distinctKeys;
   if (distinct) {
@@ -2219,9 +2363,21 @@ var runRelationalSelect = async (opts) => {
     orderBy: distinctKeys ? (aliasedTable2) => [
       ...orderBy ? extractOrderBy(aliasedTable2, orderBy, relationFilterCtx(filterCtx, tableName)) : [],
       ...primaryKeyOrderExprs(aliasedTable2, pkNames)
-    ] : orderBy ? (aliasedTable2) => extractOrderBy(aliasedTable2, orderBy, relationFilterCtx(filterCtx, tableName)) : needsDefaultOrder && pkNames?.length ? (aliasedTable2) => primaryKeyOrderExprs(aliasedTable2, pkNames) : void 0,
-    where: distinctKeys ? { RAW: (aliasedTable2) => primaryKeyRestriction(aliasedTable2, pkNames, distinctKeys) } : where ? {
-      RAW: (aliasedTable2) => extractFilters(aliasedTable2, tableName, where, relationFilterCtx(filterCtx, tableName))
+    ] : cursorEntries ? (
+      // Cursor pagination needs a total order: the request's orderBy plus the PK tiebreak,
+      // exactly the ordering the cursor encodes and the keyset predicate compares against.
+      (aliasedTable2) => cursorOrderExprs(aliasedTable2, cursorEntries)
+    ) : orderBy ? (aliasedTable2) => extractOrderBy(aliasedTable2, orderBy, relationFilterCtx(filterCtx, tableName)) : needsDefaultOrder && pkNames?.length ? (aliasedTable2) => primaryKeyOrderExprs(aliasedTable2, pkNames) : void 0,
+    where: distinctKeys ? { RAW: (aliasedTable2) => primaryKeyRestriction(aliasedTable2, pkNames, distinctKeys) } : where || cursorValues ? {
+      RAW: (aliasedTable2) => (0, import_drizzle_orm3.and)(
+        where ? extractFilters(aliasedTable2, tableName, where, relationFilterCtx(filterCtx, tableName)) : void 0,
+        cursorValues ? buildCursorCondition(
+          aliasedTable2,
+          cursorEntries,
+          cursorValues,
+          opts.nullOrdering ?? "nulls-smallest"
+        ) : void 0
+      )
     } : void 0,
     with: relationMap[tableName] ? extractRelationsParams(relationMap, tables, tableName, parsedInfo, typeName, typeNameMapper, filterCtx) : void 0
   };
@@ -2229,8 +2385,16 @@ var runRelationalSelect = async (opts) => {
     const result2 = await queryBase.findFirst(params);
     return result2 ? remapToGraphQLSingleOutput(result2, tableName, table, relationMap) : void 0;
   }
+  if (cursorEntries && cursorSelected) {
+    for (const [column] of cursorEntries) {
+      params.columns[column] = true;
+    }
+  }
   params.limit = distinctKeys ? void 0 : opts.limit;
   const result = await queryBase.findMany(params);
+  if (cursorEntries && cursorSelected) {
+    attachRowCursors(result, cursorEntries);
+  }
   return remapToGraphQLArrayOutput(result, tableName, table, relationMap);
 };
 var eagerLoadMutationRelations = async (db, tableName, rows, pkNames, withParams) => {
@@ -2778,7 +2942,9 @@ var generateSelectArray = (db, tableName, tables, relationMap, orderArgs, filter
           single: false,
           filterCtx,
           pkNames,
-          db: executor
+          db: executor,
+          // MySQL sorts NULLs as the smallest values (first in ASC).
+          nullOrdering: "nulls-smallest"
         });
       } catch (e) {
         throw toGraphQLError(e);
@@ -3276,16 +3442,48 @@ var generateSelectArray2 = (db, tableName, tables, relationMap, orderArgs, filte
             single: false,
             filterCtx,
             pkNames,
-            db: executor
+            db: executor,
+            // PostgreSQL sorts NULLs as the largest values (last in ASC).
+            nullOrdering: "nulls-largest"
           });
         }
-        const { offset, limit, orderBy, where, distinct } = args;
+        const { offset, limit, orderBy, where, distinct, after } = args;
         const selectedColumnsSql = extractSelectedColumnsFromTreeSQLFormat(
           parsedInfo.fieldsByTypeName[typeName],
           table,
           { tableName, relationMap, tables }
         );
-        const whereSql = where ? extractFilters(table, tableName, where, relationFilterCtx(filterCtx, tableName)) : void 0;
+        const cursorSelected = isCursorFieldSelected(parsedInfo.fieldsByTypeName[typeName], table);
+        let cursorEntries;
+        if (after != null || cursorSelected) {
+          if (after != null && distinct?.length) {
+            throw new import_graphql7.GraphQLError("'after' cannot be combined with 'distinct'.");
+          }
+          if (orderByHasRelationEntry(orderBy)) {
+            if (after != null) {
+              throw new import_graphql7.GraphQLError(
+                "'after' cannot be combined with an orderBy that orders through a relation \u2014 a related row's value cannot be encoded into a cursor."
+              );
+            }
+          } else if (!pkNames.length) {
+            if (after != null) {
+              throw new import_graphql7.GraphQLError(
+                `Table ${tableName} has no primary key, so cursor pagination cannot be used on it.`
+              );
+            }
+          } else {
+            cursorEntries = cursorOrderingEntries(orderBy, pkNames);
+            if (cursorSelected) {
+              const allColumns = (0, import_drizzle_orm6.getColumns)(table);
+              for (const [column] of cursorEntries) {
+                selectedColumnsSql[column] ??= allColumns[column];
+              }
+            }
+          }
+        }
+        const cursorCondition = after != null && cursorEntries ? buildCursorCondition(table, cursorEntries, decodeCursor(after, cursorEntries), "nulls-largest") : void 0;
+        const baseWhereSql = where ? extractFilters(table, tableName, where, relationFilterCtx(filterCtx, tableName)) : void 0;
+        const whereSql = cursorCondition ? (0, import_drizzle_orm6.and)(baseWhereSql, cursorCondition) : baseWhereSql;
         let distinctKeys;
         if (distinct?.length) {
           distinctKeys = await selectDistinctKeys({
@@ -3309,7 +3507,9 @@ var generateSelectArray2 = (db, tableName, tables, relationMap, orderArgs, filte
         } else if (whereSql) {
           q = q.where(whereSql);
         }
-        if (orderBy) {
+        if (cursorEntries && !distinctKeys) {
+          q = q.orderBy(...cursorOrderExprs(table, cursorEntries));
+        } else if (orderBy) {
           q = q.orderBy(
             ...extractOrderBy(table, orderBy, relationFilterCtx(filterCtx, tableName)),
             ...distinctKeys ? primaryKeyOrderExprs(table, pkNames) : []
@@ -3325,7 +3525,11 @@ var generateSelectArray2 = (db, tableName, tables, relationMap, orderArgs, filte
             q = q.limit(limit);
           }
         }
-        return remapToGraphQLArrayOutput(await q, tableName, table, relationMap);
+        const rows = await q;
+        if (cursorEntries && cursorSelected) {
+          attachRowCursors(rows, cursorEntries);
+        }
+        return remapToGraphQLArrayOutput(rows, tableName, table, relationMap);
       } catch (e) {
         throw toGraphQLError(e);
       }
@@ -4037,7 +4241,9 @@ var generateSelectArray3 = (db, tableName, tables, relationMap, orderArgs, filte
           single: false,
           filterCtx,
           pkNames,
-          db: executor
+          db: executor,
+          // SQLite sorts NULLs as the smallest values (first in ASC).
+          nullOrdering: "nulls-smallest"
         });
       } catch (e) {
         throw toGraphQLError(e);