@svgrid/enterprise 1.2.0 → 2.0.0

package/src/sources/realtime-supabase.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createSupabaseRealtime } from './realtime-supabase'
+
+/** A supabase-js-like realtime client that captures the wiring and can fire payloads. */
+function makeClient() {
+  const state: {
+    name?: string
+    filter?: Record<string, unknown>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    cb?: (payload: any) => void
+    status?: (s: string) => void
+    removed: unknown[]
+  } = { removed: [] }
+
+  const channel: any = {
+    on(_type: string, filter: Record<string, unknown>, cb: (p: unknown) => void) {
+      state.filter = filter
+      state.cb = cb
+      return channel
+    },
+    subscribe(cb?: (s: string) => void) {
+      state.status = cb
+      return channel
+    },
+  }
+  const client = {
+    channel(name: string) { state.name = name; return channel },
+    removeChannel(ch: unknown) { state.removed.push(ch) },
+  }
+  return { client, channel, state }
+}
+
+afterEach(() => vi.useRealTimers())
+
+describe('createSupabaseRealtime', () => {
+  it('subscribes to postgres_changes for the table with defaults', () => {
+    const { client, state } = makeClient()
+    createSupabaseRealtime({ client, table: 'customers', onChange: () => {} })
+    expect(state.name).toBe('svgrid:public:customers')
+    expect(state.filter).toEqual({ event: '*', schema: 'public', table: 'customers' })
+  })
+
+  it('honors schema, event, filter, and channelName', () => {
+    const { client, state } = makeClient()
+    createSupabaseRealtime({
+      client, table: 't', schema: 'app', event: 'INSERT', filter: 'tier=eq.pro', channelName: 'c', onChange: () => {},
+    })
+    expect(state.name).toBe('c')
+    expect(state.filter).toEqual({ event: 'INSERT', schema: 'app', table: 't', filter: 'tier=eq.pro' })
+  })
+
+  it('normalizes a change payload', () => {
+    const { client, state } = makeClient()
+    const onChange = vi.fn()
+    createSupabaseRealtime({ client, table: 't', onChange })
+    state.cb!({ eventType: 'UPDATE', new: { id: 1, name: 'X' }, old: { id: 1 } })
+    expect(onChange).toHaveBeenCalledWith({ type: 'UPDATE', new: { id: 1, name: 'X' }, old: { id: 1 } })
+  })
+
+  it('passes status through', () => {
+    const { client, state } = makeClient()
+    const onStatus = vi.fn()
+    createSupabaseRealtime({ client, table: 't', onChange: () => {}, onStatus })
+    state.status!('SUBSCRIBED')
+    expect(onStatus).toHaveBeenCalledWith('SUBSCRIBED')
+  })
+
+  it('coalesces a burst into one call when debounced', () => {
+    vi.useFakeTimers()
+    const { client, state } = makeClient()
+    const onChange = vi.fn()
+    createSupabaseRealtime({ client, table: 't', debounceMs: 200, onChange })
+    state.cb!({ eventType: 'INSERT', new: { id: 1 } })
+    state.cb!({ eventType: 'INSERT', new: { id: 2 } })
+    state.cb!({ eventType: 'INSERT', new: { id: 3 } })
+    expect(onChange).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(200)
+    expect(onChange).toHaveBeenCalledTimes(1)
+    expect(onChange).toHaveBeenCalledWith({ type: 'INSERT', new: { id: 3 }, old: null })
+  })
+
+  it('unsubscribe removes the channel and cancels a pending debounce', () => {
+    vi.useFakeTimers()
+    const { client, state, channel } = makeClient()
+    const onChange = vi.fn()
+    const live = createSupabaseRealtime({ client, table: 't', debounceMs: 200, onChange })
+    state.cb!({ eventType: 'DELETE', old: { id: 9 } })
+    live.unsubscribe()
+    vi.advanceTimersByTime(500)
+    expect(onChange).not.toHaveBeenCalled()
+    expect(state.removed).toEqual([channel])
+  })
+})

package/src/sources/realtime-supabase.ts

@@ -0,0 +1,99 @@
+/**
+ * createSupabaseRealtime - live updates for a Studio screen via Supabase
+ * Realtime (Postgres change streams). Subscribe to a table's INSERT / UPDATE /
+ * DELETE events and react - typically by refreshing the current page so the grid
+ * stays in sync with the database, no polling.
+ *
+ *     const live = createSupabaseRealtime({
+ *       client, table: 'customers',
+ *       debounceMs: 200,
+ *       onChange: () => controller.refresh(),  // re-fetch the current page
+ *     })
+ *     // later: live.unsubscribe()
+ *
+ * You bring the same `supabase-js` client used for reads (BYO, no dependency).
+ * Because the server model is paged, the correct default is to `refresh()` on a
+ * change - that respects the active sort / filter / page. Use `debounceMs` to
+ * coalesce bursts into a single refetch. For per-row effects (e.g. flashing a
+ * changed row) read the normalized event passed to `onChange`.
+ */
+import { nudgeEnterprise } from '../license'
+
+/** A normalized change event. `new` is the row after the change (INSERT/UPDATE); `old` its prior identity (UPDATE/DELETE). */
+export type RealtimeChange<TData> = {
+  type: 'INSERT' | 'UPDATE' | 'DELETE'
+  new: TData | null
+  old: Partial<TData> | null
+}
+
+/** The slice of a `supabase-js` client + channel this needs. */
+export type RealtimeChannelLike = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  on(type: 'postgres_changes', filter: Record<string, unknown>, cb: (payload: any) => void): RealtimeChannelLike
+  subscribe(cb?: (status: string) => void): RealtimeChannelLike
+}
+export type SupabaseRealtimeClientLike = {
+  channel(name: string): RealtimeChannelLike
+  removeChannel(channel: RealtimeChannelLike): void
+}
+
+export type SupabaseRealtimeConfig<TData> = {
+  client: SupabaseRealtimeClientLike
+  table: string
+  /** Postgres schema. Default `'public'`. */
+  schema?: string
+  /** Only these events. Default `'*'` (all). */
+  event?: 'INSERT' | 'UPDATE' | 'DELETE' | '*'
+  /** PostgREST-style row filter, e.g. `'tier=eq.pro'`. */
+  filter?: string
+  /** Unique channel name. Default `svgrid:{schema}:{table}`. */
+  channelName?: string
+  /** Coalesce bursts: call `onChange` at most once per this window (trailing). */
+  debounceMs?: number
+  /** Called for each change (or the last of a debounced burst). */
+  onChange: (change: RealtimeChange<TData>) => void
+  /** Subscription status callback (`SUBSCRIBED`, `CHANNEL_ERROR`, ...). */
+  onStatus?: (status: string) => void
+}
+
+export type SupabaseRealtimeHandle = { unsubscribe(): void }
+
+export function createSupabaseRealtime<TData = Record<string, unknown>>(
+  config: SupabaseRealtimeConfig<TData>,
+): SupabaseRealtimeHandle {
+  nudgeEnterprise('Studio') // soft-gate; never blocks
+  const schema = config.schema ?? 'public'
+  const channelName = config.channelName ?? `svgrid:${schema}:${config.table}`
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const emit = (change: RealtimeChange<TData>) => {
+    if (!config.debounceMs) {
+      config.onChange(change)
+      return
+    }
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => config.onChange(change), config.debounceMs)
+  }
+
+  const channel = config.client
+    .channel(channelName)
+    .on(
+      'postgres_changes',
+      { event: config.event ?? '*', schema, table: config.table, ...(config.filter ? { filter: config.filter } : {}) },
+      (payload) => {
+        emit({
+          type: payload.eventType,
+          new: (payload.new ?? null) as TData | null,
+          old: (payload.old ?? null) as Partial<TData> | null,
+        })
+      },
+    )
+    .subscribe(config.onStatus)
+
+  return {
+    unsubscribe() {
+      if (timer) clearTimeout(timer)
+      config.client.removeChannel(channel)
+    },
+  }
+}

package/src/sources/relation-lookup.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { ServerRequest } from '@svgrid/grid'
+import type { EntitySchema } from '../schema'
+import { createRelationLookup } from './relation-lookup'
+
+type Company = { id: number; name: string }
+
+const companies: Company[] = [
+  { id: 1, name: 'Acme Inc' },
+  { id: 2, name: 'Globex' },
+  { id: 3, name: 'Initech' },
+]
+
+const schema: EntitySchema<Company> = {
+  name: 'companies',
+  idField: 'id',
+  fields: [
+    { field: 'id', type: 'number', primaryKey: true },
+    { field: 'name', type: 'text' },
+  ],
+}
+
+/** Minimal getRows over the array: honors global search + an equals filter on id. */
+function source() {
+  const getRows = vi.fn(async (req: ServerRequest) => {
+    let rows = companies
+    const g = req.filterModel.global?.toLowerCase()
+    if (g) rows = rows.filter((c) => c.name.toLowerCase().includes(g))
+    const idCol = req.filterModel.columns?.id
+    if (idCol?.selectedValues) rows = rows.filter((c) => idCol.selectedValues!.includes(String(c.id)))
+    else if (idCol) rows = rows.filter((c) => String(c.id) === idCol.value)
+    return { rows: rows.slice(req.startRow, req.endRow), rowCount: rows.length }
+  })
+  return { getRows }
+}
+
+describe('createRelationLookup', () => {
+  it('searches and maps rows to { value, label }', async () => {
+    const lookup = createRelationLookup({ source: source(), schema, labelField: 'name' })
+    expect(await lookup.search('in')).toEqual([
+      { value: '1', label: 'Acme Inc', row: { id: 1, name: 'Acme Inc' } },
+      { value: '3', label: 'Initech', row: { id: 3, name: 'Initech' } },
+    ])
+  })
+
+  it('returns a full page for an empty query', async () => {
+    const lookup = createRelationLookup({ source: source(), schema, labelField: 'name' })
+    expect((await lookup.search('')).map((o) => o.label)).toEqual(['Acme Inc', 'Globex', 'Initech'])
+  })
+
+  it('resolves a stored key to its label', async () => {
+    const lookup = createRelationLookup({ source: source(), schema, labelField: 'name' })
+    expect(await lookup.labelFor(2)).toBe('Globex')
+  })
+
+  it('caches labels seen during search (no extra getRows for labelFor)', async () => {
+    const src = source()
+    const lookup = createRelationLookup({ source: src, schema, labelField: 'name' })
+    await lookup.search('acme') // caches value 1 -> Acme Inc
+    src.getRows.mockClear()
+    expect(await lookup.labelFor(1)).toBe('Acme Inc')
+    expect(src.getRows).not.toHaveBeenCalled()
+  })
+
+  it('returns null for an empty value and the key itself when unresolved', async () => {
+    const lookup = createRelationLookup({ source: source(), schema, labelField: 'name' })
+    expect(await lookup.labelFor('')).toBeNull()
+    expect(await lookup.labelFor(999)).toBe('999')
+  })
+
+  it('honors an explicit valueField over the schema id', async () => {
+    const lookup = createRelationLookup({ source: source(), labelField: 'name', valueField: 'name' })
+    const opts = await lookup.search('glob')
+    expect(opts[0]).toMatchObject({ value: 'Globex', label: 'Globex' })
+  })
+
+  describe('labelsFor (batch)', () => {
+    it('resolves many keys in a single request (no N+1), deduping', async () => {
+      const src = source()
+      const lookup = createRelationLookup({ source: src, schema, labelField: 'name' })
+      const map = await lookup.labelsFor([1, 2, 2, 3, null, ''])
+      expect(map.get('1')).toBe('Acme Inc')
+      expect(map.get('2')).toBe('Globex')
+      expect(map.get('3')).toBe('Initech')
+      expect(src.getRows).toHaveBeenCalledTimes(1) // one query for all misses
+    })
+
+    it('serves cached keys without a request, and maps unresolved keys to themselves', async () => {
+      const src = source()
+      const lookup = createRelationLookup({ source: src, schema, labelField: 'name' })
+      await lookup.labelsFor([1]) // warm the cache
+      src.getRows.mockClear()
+      const map = await lookup.labelsFor([1, 999])
+      expect(map.get('1')).toBe('Acme Inc') // cached
+      expect(map.get('999')).toBe('999') // unresolved -> itself
+      expect(src.getRows).toHaveBeenCalledTimes(1) // only the miss (999)
+    })
+  })
+})

package/src/sources/relation-lookup.ts

@@ -0,0 +1,128 @@
+/**
+ * createRelationLookup - powers a foreign-key "lookup" field: search the related
+ * entity for options, and resolve a stored key back to its human label. It runs
+ * over the SAME `ServerDataSource` contract as everything else, so the related
+ * options can come from Supabase, REST, SQL, or in-memory - whatever backs the
+ * related table.
+ *
+ *     const companyLookup = createRelationLookup({
+ *       source: companiesSource,     // the related entity's ServerDataSource
+ *       schema: companiesSchema,     // resolves the related primary key
+ *       labelField: 'name',          // what the user sees
+ *     })
+ *     await companyLookup.search('acme')   // -> [{ value: '12', label: 'Acme Inc' }, ...]
+ *     await companyLookup.labelFor('12')   // -> 'Acme Inc'
+ *
+ * Pass it to `<SvGridEditPanel lookups={{ companyId: companyLookup }} />` and the
+ * `companyId` relation field renders a searchable picker instead of a raw input.
+ */
+import type { RowData, ServerDataSource, ServerRequest } from '@svgrid/grid'
+import { resolveIdField, type EntitySchema } from '../schema'
+
+export type RelationOption = { value: string; label: string; row: RowData }
+
+export type RelationLookup = {
+  /** Search the related entity (global search); returns a page of options. */
+  search(query: string): Promise<RelationOption[]>
+  /** Resolve a stored key to its label (cached). Returns the key itself if not found. */
+  labelFor(value: unknown): Promise<string | null>
+  /**
+   * Resolve many keys at once (cached), fetching only the misses in a SINGLE
+   * request (a set / `IN` filter) - avoids the N+1 of calling `labelFor` per
+   * row. Returns a `value -> label` map (unresolved keys map to themselves).
+   */
+  labelsFor(values: ReadonlyArray<unknown>): Promise<Map<string, string>>
+}
+
+export type RelationLookupConfig<TRelated extends RowData> = {
+  /** The related entity's read source (only `getRows` is used). */
+  source: Pick<ServerDataSource<TRelated>, 'getRows'>
+  /** Field on the related row shown to the user. */
+  labelField: string
+  /** Related primary-key field. Default: resolved from `schema`, else `'id'`. */
+  valueField?: string
+  /** Related schema, used to resolve the key when `valueField` is omitted. */
+  schema?: EntitySchema<TRelated>
+  /** Options fetched per search. Default 20. */
+  pageSize?: number
+}
+
+export function createRelationLookup<TRelated extends RowData>(
+  config: RelationLookupConfig<TRelated>,
+): RelationLookup {
+  const pageSize = config.pageSize ?? 20
+  const valueField = config.valueField ?? (config.schema ? resolveIdField(config.schema) : 'id')
+  const { labelField, source } = config
+  const cache = new Map<string, string>() // value -> label
+
+  const toOption = (row: RowData): RelationOption => {
+    const value = String(row[valueField] ?? '')
+    const label = String(row[labelField] ?? value)
+    cache.set(value, label)
+    return { value, label, row }
+  }
+
+  const request = (over: Partial<ServerRequest>): ServerRequest => ({
+    startRow: 0,
+    endRow: pageSize,
+    pageIndex: 0,
+    pageSize,
+    sortModel: [],
+    filterModel: {},
+    ...over,
+  })
+
+  return {
+    async search(query: string): Promise<RelationOption[]> {
+      const term = query.trim()
+      const { rows } = await source.getRows(request({ filterModel: term ? { global: term } : {} }))
+      return rows.map((r) => toOption(r as RowData))
+    },
+
+    async labelFor(value: unknown): Promise<string | null> {
+      if (value == null || value === '') return null
+      const key = String(value)
+      const cached = cache.get(key)
+      if (cached != null) return cached
+      const { rows } = await source.getRows(
+        request({
+          endRow: 1,
+          pageSize: 1,
+          filterModel: { columns: { [valueField]: { operator: 'equals', value: key } } },
+        }),
+      )
+      const row = rows[0] as RowData | undefined
+      return row ? toOption(row).label : key
+    },
+
+    async labelsFor(values: ReadonlyArray<unknown>): Promise<Map<string, string>> {
+      const result = new Map<string, string>()
+      const missing: string[] = []
+      for (const v of values) {
+        if (v == null || v === '') continue
+        const key = String(v)
+        if (result.has(key)) continue
+        const cached = cache.get(key)
+        if (cached != null) result.set(key, cached)
+        else if (!missing.includes(key)) missing.push(key)
+      }
+      if (missing.length > 0) {
+        // One request for every miss: a set (`IN`) filter on the key field.
+        const { rows } = await source.getRows(
+          request({
+            endRow: missing.length,
+            pageSize: missing.length,
+            filterModel: { columns: { [valueField]: { operator: 'in', value: '', selectedValues: missing } } },
+          }),
+        )
+        for (const row of rows) {
+          const opt = toOption(row as RowData)
+          result.set(opt.value, opt.label)
+        }
+        // Anything still unresolved maps to the key itself.
+        for (const key of missing) if (!result.has(key)) result.set(key, key)
+      }
+      return result
+    },
+  }
+}

package/src/sources/rest-adapters.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+import type { ServerRequest } from '@svgrid/grid'
+import { createRestDataSource } from './rest'
+import { offsetLimitAdapter, dummyJsonAdapter, jsonServerAdapter } from './rest-adapters'
+
+type Row = { id: string; name: string }
+
+function jsonResponse(body: unknown, opts: { status?: number; headers?: Record<string, string> } = {}) {
+  const status = opts.status ?? 200
+  const headers = opts.headers ?? {}
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: 'OK',
+    headers: { get: (k: string) => headers[k.toLowerCase()] ?? null },
+    json: async () => body,
+  } as unknown as Response
+}
+
+function mockFetch(handler: (url: string) => Response) {
+  const calls: string[] = []
+  const fetch = (async (url: string | URL) => {
+    calls.push(String(url))
+    return handler(String(url))
+  }) as unknown as typeof globalThis.fetch
+  return { fetch, calls }
+}
+
+const req = (p: Partial<ServerRequest>): ServerRequest => ({
+  startRow: 0, endRow: 10, pageIndex: 0, pageSize: 10, sortModel: [], filterModel: {}, ...p,
+})
+const paramsOf = (url: string) => new URLSearchParams(url.split('?')[1])
+
+describe('dummyJsonAdapter', () => {
+  it('maps paging to skip/limit, sort to sortBy/order, and reads products/total', async () => {
+    const { fetch, calls } = mockFetch(() =>
+      jsonResponse({ products: [{ id: '1', name: 'Phone' }], total: 194, skip: 20, limit: 10 }),
+    )
+    const src = createRestDataSource<Row>({ url: 'https://dummyjson.com/products', fetch, ...dummyJsonAdapter<Row>() })
+    const out = await src.getRows(req({ startRow: 20, endRow: 30, sortModel: [{ id: 'price', desc: true }] }))
+    const p = paramsOf(calls[0]!)
+    expect(p.get('skip')).toBe('20')
+    expect(p.get('limit')).toBe('10')
+    expect(p.get('sortBy')).toBe('price')
+    expect(p.get('order')).toBe('desc')
+    expect(out).toEqual({ rows: [{ id: '1', name: 'Phone' }], rowCount: 194 })
+  })
+
+  it('reads a non-default collection key (e.g. users)', async () => {
+    const { fetch } = mockFetch(() => jsonResponse({ users: [{ id: '7', name: 'Ada' }], total: 30 }))
+    const src = createRestDataSource<Row>({ url: 'https://dummyjson.com/users', fetch, ...dummyJsonAdapter<Row>('users') })
+    expect(await src.getRows(req({}))).toEqual({ rows: [{ id: '7', name: 'Ada' }], rowCount: 30 })
+  })
+})
+
+describe('jsonServerAdapter', () => {
+  it('maps paging to _start/_limit, multi-sort to _sort/_order, total from X-Total-Count', async () => {
+    const { fetch, calls } = mockFetch(() =>
+      jsonResponse([{ id: '1', name: 'Ada' }], { headers: { 'x-total-count': '240' } }),
+    )
+    const src = createRestDataSource<Row>({ url: 'https://x.test/posts', fetch, ...jsonServerAdapter<Row>() })
+    const out = await src.getRows(
+      req({ startRow: 0, endRow: 25, sortModel: [{ id: 'title', desc: false }, { id: 'views', desc: true }] }),
+    )
+    const p = paramsOf(calls[0]!)
+    expect(p.get('_start')).toBe('0')
+    expect(p.get('_limit')).toBe('25')
+    expect(p.get('_sort')).toBe('title,views')
+    expect(p.get('_order')).toBe('asc,desc')
+    expect(out).toEqual({ rows: [{ id: '1', name: 'Ada' }], rowCount: 240 })
+  })
+
+  it('falls back to array length when no X-Total-Count header', async () => {
+    const { fetch } = mockFetch(() => jsonResponse([{ id: '1', name: 'A' }, { id: '2', name: 'B' }]))
+    const src = createRestDataSource<Row>({ url: 'https://x.test/posts', fetch, ...jsonServerAdapter<Row>() })
+    expect((await src.getRows(req({}))).rowCount).toBe(2)
+  })
+})
+
+describe('offsetLimitAdapter', () => {
+  it('is fully configurable and sends the search term under the named param', async () => {
+    const { fetch, calls } = mockFetch(() => jsonResponse({ data: [{ id: '1', name: 'x' }], count: 3 }))
+    const src = createRestDataSource<Row>({
+      url: 'https://x.test/items',
+      fetch,
+      ...offsetLimitAdapter<Row>({ offsetParam: 'from', limitParam: 'size', searchParam: 'q', rowsKey: 'data', totalKey: 'count' }),
+    })
+    const out = await src.getRows(req({ startRow: 5, endRow: 15, filterModel: { global: 'ada', columns: {} } }))
+    const p = paramsOf(calls[0]!)
+    expect(p.get('from')).toBe('5')
+    expect(p.get('size')).toBe('10')
+    expect(p.get('q')).toBe('ada')
+    expect(out).toEqual({ rows: [{ id: '1', name: 'x' }], rowCount: 3 })
+  })
+})

package/src/sources/rest-adapters.ts

@@ -0,0 +1,120 @@
+/**
+ * Wire-format adapters for `createRestDataSource`. A public / third-party API
+ * rarely speaks our default `offset&limit&sort` dialect - it uses `skip`, or
+ * `page`, or `_start`, and wraps its rows under `products` / `data` / a bare
+ * array with an `X-Total-Count` header. An adapter is just the `{ buildQuery,
+ * parse }` pair that teaches the REST source that dialect:
+ *
+ *     createRestDataSource({ url: 'https://dummyjson.com/products',
+ *                            ...dummyJsonAdapter() })
+ *
+ * `offsetLimitAdapter` is the configurable base; `dummyJsonAdapter` and
+ * `jsonServerAdapter` are ready-made presets for two very common shapes.
+ */
+import type { RowData, ServerRequest, ServerResult } from '@svgrid/grid'
+import type { RestDataSourceConfig } from './rest'
+import { normalizeFilters } from './filters'
+
+/** The parts of a REST config that describe a backend's wire format. */
+export type RestAdapter<TData extends RowData> = Required<
+  Pick<RestDataSourceConfig<TData>, 'buildQuery' | 'parse'>
+>
+
+const pick = (body: unknown, keys: string[]): unknown => {
+  const b = (body ?? {}) as Record<string, unknown>
+  for (const k of keys) if (b[k] != null) return b[k]
+  return undefined
+}
+
+export type OffsetLimitOptions = {
+  /** Query param for the first-row offset (default `offset`). */
+  offsetParam?: string
+  /** Query param for the page size (default `limit`). */
+  limitParam?: string
+  /** If set, single-column sort emits `<sortByParam>=<col>` + `<orderParam>=asc|desc`. */
+  sortByParam?: string
+  orderParam?: string
+  /** If set, the global search term is sent as `<searchParam>=<term>`. */
+  searchParam?: string
+  /** Response key holding the row array (tried in order; falls back to `data`/`rows`/`items`). */
+  rowsKey?: string
+  /** Response key holding the total count (tried in order; falls back to `total`/`count`). */
+  totalKey?: string
+}
+
+/**
+ * The `?offset=..&limit=..` family (Supabase-ish REST, DummyJSON with `skip`,
+ * many hand-rolled APIs). Configure the param names + response keys once.
+ */
+export function offsetLimitAdapter<TData extends RowData>(opts: OffsetLimitOptions = {}): RestAdapter<TData> {
+  const offsetParam = opts.offsetParam ?? 'offset'
+  const limitParam = opts.limitParam ?? 'limit'
+  const rowsKeys = [opts.rowsKey, 'data', 'rows', 'items'].filter(Boolean) as string[]
+  const totalKeys = [opts.totalKey, 'total', 'count', 'rowCount'].filter(Boolean) as string[]
+  return {
+    buildQuery(request: ServerRequest): Record<string, string> {
+      const params: Record<string, string> = {
+        [offsetParam]: String(request.startRow),
+        [limitParam]: String(request.endRow - request.startRow),
+      }
+      const first = request.sortModel[0]
+      if (opts.sortByParam && first) {
+        params[opts.sortByParam] = first.id
+        if (opts.orderParam) params[opts.orderParam] = first.desc ? 'desc' : 'asc'
+      }
+      if (opts.searchParam) {
+        const { search } = normalizeFilters(request.filterModel)
+        if (search) params[opts.searchParam] = search
+      }
+      return params
+    },
+    parse(body: unknown): ServerResult<TData> {
+      const rows = (pick(body, rowsKeys) ?? []) as TData[]
+      const total = pick(body, totalKeys)
+      return { rows, rowCount: total != null ? Number(total) : rows.length }
+    },
+  }
+}
+
+/**
+ * DummyJSON (`https://dummyjson.com/<collection>`): `skip`/`limit` paging,
+ * `sortBy`/`order` sort, rows under `products`* + a `total` field.
+ * (*`rowsKey` defaults to `products`; pass one for `users`, `posts`, etc.)
+ */
+export function dummyJsonAdapter<TData extends RowData>(rowsKey = 'products'): RestAdapter<TData> {
+  return offsetLimitAdapter<TData>({
+    offsetParam: 'skip',
+    limitParam: 'limit',
+    sortByParam: 'sortBy',
+    orderParam: 'order',
+    rowsKey,
+    totalKey: 'total',
+  })
+}
+
+/**
+ * `json-server` / JSONPlaceholder: `_start`/`_limit` paging, `_sort`/`_order`
+ * multi-column sort, a bare JSON array with the total in `X-Total-Count`.
+ */
+export function jsonServerAdapter<TData extends RowData>(): RestAdapter<TData> {
+  return {
+    buildQuery(request: ServerRequest): Record<string, string> {
+      const params: Record<string, string> = {
+        _start: String(request.startRow),
+        _limit: String(request.endRow - request.startRow),
+      }
+      if (request.sortModel.length) {
+        params._sort = request.sortModel.map((s) => s.id).join(',')
+        params._order = request.sortModel.map((s) => (s.desc ? 'desc' : 'asc')).join(',')
+      }
+      const { search } = normalizeFilters(request.filterModel)
+      if (search) params.q = search
+      return params
+    },
+    parse(body: unknown, response: Response): ServerResult<TData> {
+      const rows = Array.isArray(body) ? (body as TData[]) : []
+      const header = response.headers.get('x-total-count')
+      return { rows, rowCount: header != null ? Number(header) : rows.length }
+    },
+  }
+}