drizzle-cursor

library0.7.2jsnpmunverified

Cursor-based pagination utility for Drizzle ORM supporting any number of cursors (primary + n secondary) with custom serialization, Base64 tokens, SQL expressions, and both query-builder and relational query APIs. Current stable version is 0.7.2, maintained actively with releases matching Drizzle ORM updates. Differentiators: multiple cursor support (beyond simple ID-based), flexible serialization, and compatibility with Drizzle 0.x and 1.0.0-beta (both query-builder and RQB v1/v2). Requires drizzle-orm >=0.33.0. Ships TypeScript types.

database

npm install drizzle-cursor

package ↗

INSTALL

IMPORT

SIG · DRIZZLE-CURSOR

drizzle-cursor

databasejavascriptv0.7.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

generateCursor

✓ import { generateCursor } from 'drizzle-cursor'

✗ const { generateCursor } = require('drizzle-cursor')

ESM-only package; CommonJS require will fail. Use dynamic import if needed in CJS.

CursorConfig

✓ import type { CursorConfig } from 'drizzle-cursor'

✗ import { CursorConfig } from 'drizzle-cursor'

CursorConfig is a TypeScript type; use `import type` for type-only imports to avoid bundler issues.

default

✓ import drizzleCursor from 'drizzle-cursor'

✗ Does not have a default export; use named exports only.

Package only exports named symbols; there is no default export.

Shows basic usage: cursor generation, first page query, subsequent page using last record, and token-based pagination for frontend.

import { generateCursor } from 'drizzle-cursor'; import { sql } from 'drizzle-orm'; import { db, schema } from './db'; const cursorConfig = { cursors: [ { order: 'ASC', key: 'lastName', schema: schema.users.lastName }, { order: 'ASC', key: 'firstName', schema: schema.users.firstName }, ], primaryCursor: { order: 'ASC', key: 'id', schema: schema.users.id }, }; const cursor = generateCursor(cursorConfig); // First page const page1 = await db .select() .from(schema.users) .orderBy(...cursor.orderBy) .where(cursor.where()) .limit(10); // Second page using last record from page1 const page2 = await db .select() .from(schema.users) .orderBy(...cursor.orderBy) .where(cursor.where(page1.at(-1))) .limit(10); // Serialize last record to token for frontend const token = cursor.serialize(page2.at(-1)); // Later, deserialize and query const pageFromToken = await db .select() .from(schema.users) .orderBy(...cursor.orderBy) .where(cursor.where(cursor.deserialize(token))) .limit(10);

Debug

Known issues

breakingdrizzle-orm peer dependency must be >= 0.33.0; older versions are incompatible.

fix

Upgrade drizzle-orm to >=0.33.0

affects: >=0.7.0

gotchaNullable cursor columns are discouraged; behavior varies across databases/drivers.

fix

Avoid nullable columns in cursor config; use COALESCE or ensure NOT NULL constraints.

affects: *

gotchacursor.where() returns empty when called with no argument (first page); ensure you handle undefined/null correctly.

fix

Call cursor.where() without argument for first page, pass last record for subsequent pages.

affects: *

gotchaorderBy spread must include all cursors in the order defined in config; omitting any breaks pagination.

fix

Always use `...cursor.orderBy` in the `.orderBy()` call.

affects: *

deprecatedDrizzle RQB v1 (`db._query`) support may be removed in future versions; prefer RQB v2 (`db.query`) or query-builder.

fix

Migrate to `db.query` (RQB v2) or use query-builder directly.

affects: >=0.6.0

Errors

Common errors & fixes

Cannot find module 'drizzle-cursor'

Package not installed or not using ESM imports in CommonJS project.

fix

Run `npm install drizzle-cursor` and use dynamic import: `const { generateCursor } = await import('drizzle-cursor')` in CJS.

TypeError: cursor.where is not a function

Calling cursor.where before generating the cursor or using wrong import.

fix

Ensure you call `generateCursor(config)` first and that the returned object has `where` method.

Property 'serialize' does not exist on type '{ ... }'

Using an older version of drizzle-cursor or TypeScript type definitions not matching installed version.

fix

Upgrade to latest drizzle-cursor (`npm install drizzle-cursor@latest`) and ensure types are resolved.

Argument of type 'undefined' is not assignable to parameter of type 'Record<string, any>'

Passing `undefined` to `cursor.where()` instead of using no argument or a valid record.

fix

Call `cursor.where()` without argument for first page, or pass the last record object.

Upgrade

Version history

0.7.2latest on npm

Audit

Dependencies

drizzle-ormrequiredPeer dependency required for cursor generation and query building. Must be >= 0.33.0

Agent activity

7 hits · last 30 days

node

Resources

packagedrizzle-cursor ↗