@emeryld/keyset

@emeryld/keyset

Small, reusable keyset cursor utilities with a Prisma adapter.

Core concepts

• createKeyset(spec):

  • validates & decodes an incoming cursor for a given sortBy + dir
  • generates the next cursor from the last row
  • exposes field(sortBy) for adapters

• Prisma adapter:

  • default whereWithCursor implements:
    • asc: (field > value) OR (field = value AND id > cursorId)
    • desc: (field < value) OR (field = value AND id < cursorId)
  • you can substitute whereWithCursor via createPrismaKeysetAdapter({ whereWithCursor })

Installation (monorepo)

Add the package under packages/keyset, then:

pnpm -C packages/keyset build

Consume it from your app:

import { createKeyset } from '@emeryld/keyset/core'
import { createPrismaKeysetAdapter } from '@emeryld/keyset/adapters/prisma'

Usage

Define a keyset spec per feed (domain-owned, close to the repo code):

import { createKeyset } from '@emeryld/keyset/core'

export const orgKeyset = createKeyset({
  name: {
    field: 'name',
    cursorValueKey: 'name',
    rowValue: (r: { name: string }) => r.name,
    isRaw: (v): v is string => typeof v === 'string',
    fromRaw: (v: string) => v,
    toRaw: (v: string) => v,
  },
  createdAt: {
    field: 'createdAt',
    cursorValueKey: 'dt',
    rowValue: (r: { createdAt: Date }) => r.createdAt,
    isRaw: (v): v is string => typeof v === 'string',
    fromRaw: (v: string) => new Date(v),
    toRaw: (d: Date) => d.toISOString(),
  },
} as const)

Use it in your repository with the Prisma adapter:

import { createPrismaKeysetAdapter } from '@emeryld/keyset/adapters/prisma'

const prismaKeyset = createPrismaKeysetAdapter()

const cursor = orgKeyset.decode(query.cursor, sortBy, sortDir)

const where = prismaKeyset.whereWithCursor({
  baseWhere,
  field: orgKeyset.field(sortBy),
  dir: sortDir,
  cursor,
})

const orderBy = prismaKeyset.orderBy({
  field: orgKeyset.field(sortBy),
  dir: sortDir,
})

const rows = await ctx.prisma.organization.findMany({
  where,
  orderBy,
  select: { id: true, name: true, createdAt: true },
  take: limit + 1,
})

const page = rows.slice(0, limit)
const hasMore = rows.length > limit

const nextCursor = orgKeyset.nextCursor(page, hasMore, sortBy, sortDir)

Customizing the Prisma where builder

You can override the default whereWithCursor for special cases (nullable sort fields, computed fields, non-standard tie-breakers, etc.).

import {
  createPrismaKeysetAdapter,
  prismaWhereWithCursorDefault,
} from '@emeryld/keyset/adapters/prisma'

const prismaKeyset = createPrismaKeysetAdapter({
  whereWithCursor: (args) => {
    // delegate for most fields
    const where = prismaWhereWithCursorDefault(args)

    // example: require non-null values for a nullable sort field
    if (args.field === 'someNullableColumn') {
      return { ...where, [args.field]: { not: null } }
    }

    return where
  },
})

Notes

• Cursor format is base64url JSON with v: 1 for versioning. You can bump v later.
• nextCursor assumes each row contains an id property.
• For raw SQL / computed sorts, keep the special-case branch in your repo or implement a custom whereWithCursor in the adapter.