@svgrid/enterprise 1.2.0 → 2.0.0

package/src/sources/rest.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest'
+import type { ServerRequest } from '@svgrid/grid'
+import { createRestDataSource } from './rest'
+
+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, init?: RequestInit) => Response) {
+  const calls: Array<{ url: string; init?: RequestInit }> = []
+  const fetch = (async (url: string | URL, init?: RequestInit) => {
+    calls.push({ url: String(url), init })
+    return handler(String(url), init)
+  }) 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,
+})
+
+describe('createRestDataSource reads', () => {
+  it('builds the default query and parses an object response', async () => {
+    const { fetch, calls } = mockFetch(() => jsonResponse({ rows: [{ id: '1', name: 'Ada' }], rowCount: 5 }))
+    const src = createRestDataSource<Row>({ url: '/api/customers', fetch })
+    const out = await src.getRows(
+      req({
+        sortModel: [{ id: 'mrr', desc: true }, { id: 'name', desc: false }],
+        filterModel: { global: 'ada', columns: { name: { operator: 'contains', value: 'a' } } },
+      }),
+    )
+    const usp = new URLSearchParams(calls[0]!.url.split('?')[1])
+    expect(usp.get('offset')).toBe('0')
+    expect(usp.get('limit')).toBe('10')
+    expect(usp.get('sort')).toBe('-mrr,name')
+    expect(usp.get('search')).toBe('ada')
+    expect(usp.get('name')).toBe('contains:a')
+    expect(out).toEqual({ rows: [{ id: '1', name: 'Ada' }], rowCount: 5 })
+  })
+
+  it('merges static `query` params into every read (built paging wins on conflict)', async () => {
+    const { fetch, calls } = mockFetch(() => jsonResponse({ rows: [], rowCount: 0 }))
+    const src = createRestDataSource<Row>({ url: '/api/customers', fetch, query: { region: 'eu', limit: 'IGNORED' } })
+    await src.getRows(req({}))
+    const usp = new URLSearchParams(calls[0]!.url.split('?')[1])
+    expect(usp.get('region')).toBe('eu') // static param sent on every read
+    expect(usp.get('limit')).toBe('10') // the built paging limit wins over a static one
+  })
+
+  it('reads the total from Content-Range for an array body', async () => {
+    const { fetch } = mockFetch(() => jsonResponse([{ id: '1', name: 'Ada' }], { headers: { 'content-range': '0-0/240' } }))
+    const src = createRestDataSource<Row>({ url: '/api/customers', fetch })
+    const out = await src.getRows(req({}))
+    expect(out).toEqual({ rows: [{ id: '1', name: 'Ada' }], rowCount: 240 })
+  })
+
+  it('throws on a non-ok response', async () => {
+    const { fetch } = mockFetch(() => jsonResponse({}, { status: 500 }))
+    const src = createRestDataSource<Row>({ url: '/api/customers', fetch })
+    await expect(src.getRows(req({}))).rejects.toThrow(/500/)
+  })
+})
+
+describe('createRestDataSource writes', () => {
+  it('POSTs to the collection to create', async () => {
+    const { fetch, calls } = mockFetch(() => jsonResponse({ id: '9', name: 'New' }))
+    const src = createRestDataSource<Row>({ url: '/api/customers', fetch })
+    const row = await src.createRow({ name: 'New' })
+    expect(calls[0]!.url).toBe('/api/customers')
+    expect(calls[0]!.init?.method).toBe('POST')
+    expect(JSON.parse(String(calls[0]!.init?.body))).toEqual({ name: 'New' })
+    expect(row).toEqual({ id: '9', name: 'New' })
+  })
+
+  it('PATCHes /{id} to update and DELETEs /{id}', async () => {
+    const { fetch, calls } = mockFetch((_url, init) =>
+      init?.method === 'DELETE' ? jsonResponse(undefined, { status: 204 }) : jsonResponse({ id: '5', name: 'X' }),
+    )
+    const src = createRestDataSource<Row>({ url: '/api/customers', fetch })
+    await src.updateRow('5', { name: 'X' })
+    await src.deleteRow('7')
+    expect(calls[0]).toMatchObject({ url: '/api/customers/5' })
+    expect(calls[0]!.init?.method).toBe('PATCH')
+    expect(calls[1]!).toMatchObject({ url: '/api/customers/7' })
+    expect(calls[1]!.init?.method).toBe('DELETE')
+  })
+
+  it('applies custom headers', async () => {
+    const { fetch, calls } = mockFetch(() => jsonResponse({ rows: [], rowCount: 0 }))
+    const src = createRestDataSource<Row>({ url: '/api/x', fetch, headers: { authorization: 'Bearer t' } })
+    await src.getRows(req({}))
+    expect((calls[0]!.init?.headers as Record<string, string>).authorization).toBe('Bearer t')
+  })
+})

package/src/sources/rest.ts

@@ -0,0 +1,129 @@
+/**
+ * createRestDataSource - a `ServerDataSource` over an HTTP/JSON API. Handles the
+ * request lifecycle and the four CRUD calls; you point it at a collection URL.
+ * The default request/response shaping suits a conventional REST endpoint, and
+ * every part is overridable (`buildQuery`, `parse`, `headers`, `fetch`) for
+ * bespoke or legacy APIs.
+ *
+ *     const source = createRestDataSource({ url: '/api/customers', schema })
+ *
+ * Default wire format:
+ *   read    GET    {url}?offset&limit&sort&search&<col>=<op>:<value>
+ *   create  POST   {url}                 body: the new row
+ *   update  PATCH  {url}/{id}            body: the patch
+ *   delete  DELETE {url}/{id}
+ * where `sort` is a comma list with `-` for descending (e.g. `-createdAt,name`).
+ */
+import type { RowData, ServerRequest, ServerResult } from '@svgrid/grid'
+import { resolveIdField, type EntitySchema } from '../schema'
+import { nudgeEnterprise } from '../license'
+import type { WritableDataSource } from '../sveltekit/types'
+import { normalizeFilters, type NormalizedPredicate } from './filters'
+
+export type RestDataSourceConfig<TData extends RowData> = {
+  /** Collection endpoint, e.g. `/api/customers`. */
+  url: string
+  /** Used to resolve the id field for update/delete when `idField` is omitted. */
+  schema?: EntitySchema<TData>
+  /** Primary key property (default: from `schema`, else `'id'`). */
+  idField?: string
+  /** Custom fetch (SSR, auth). Defaults to the global `fetch`. */
+  fetch?: typeof fetch
+  /** Extra request headers, static or computed per call. */
+  headers?: Record<string, string> | (() => Record<string, string>)
+  /** Static query params merged into every read (e.g. an API key or filter). */
+  query?: Record<string, string>
+  /** Build read query params from the grid request. Override for bespoke APIs. */
+  buildQuery?: (request: ServerRequest) => Record<string, string>
+  /** Parse a read response body into rows + total. Override for bespoke shapes. */
+  parse?: (body: unknown, response: Response) => ServerResult<TData>
+}
+
+const encodePredicate = (p: NormalizedPredicate): string => {
+  if (p.op === 'in') return `in:${p.values.join(',')}`
+  if (p.op === 'isNull') return 'isNull'
+  if (p.op === 'between') return `between:${p.value},${p.valueTo}`
+  return `${p.op}:${p.value}`
+}
+
+function defaultBuildQuery(request: ServerRequest): Record<string, string> {
+  const params: Record<string, string> = {
+    offset: String(request.startRow),
+    limit: String(request.endRow - request.startRow),
+  }
+  if (request.sortModel.length) {
+    params.sort = request.sortModel.map((s) => (s.desc ? '-' : '') + s.id).join(',')
+  }
+  const { predicates, search } = normalizeFilters(request.filterModel)
+  if (search) params.search = search
+  for (const p of predicates) params[p.column] = encodePredicate(p)
+  return params
+}
+
+function defaultParse<TData>(body: unknown, response: Response): ServerResult<TData> {
+  if (Array.isArray(body)) {
+    // Total from a Content-Range header (`items 0-9/240`) when present.
+    const range = response.headers.get('content-range')
+    const total = range && /\/(\d+)\s*$/.exec(range)
+    return { rows: body as TData[], rowCount: total ? Number(total[1]) : body.length }
+  }
+  const b = (body ?? {}) as Record<string, unknown>
+  const rows = (b.rows ?? b.data ?? b.items ?? []) as TData[]
+  const rowCount = Number(b.rowCount ?? b.total ?? b.count ?? rows.length)
+  return { rows, rowCount }
+}
+
+export function createRestDataSource<TData extends RowData>(
+  config: RestDataSourceConfig<TData>,
+): WritableDataSource<TData> {
+  nudgeEnterprise('Studio') // soft-gate; never blocks
+  const doFetch = config.fetch ?? globalThis.fetch
+  const idField = config.idField ?? (config.schema ? resolveIdField(config.schema) : 'id')
+  const base = config.url.replace(/\/+$/, '')
+  const buildQuery = config.buildQuery ?? defaultBuildQuery
+  const parse = config.parse ?? defaultParse
+
+  const headers = (extra?: Record<string, string>): Record<string, string> => {
+    const h = typeof config.headers === 'function' ? config.headers() : (config.headers ?? {})
+    return { ...h, ...extra }
+  }
+
+  const send = async (url: string, init?: RequestInit): Promise<unknown> => {
+    const res = await doFetch(url, init)
+    if (!res.ok) throw new Error(`REST ${init?.method ?? 'GET'} ${url} -> ${res.status} ${res.statusText}`)
+    const parsed = res.status === 204 ? undefined : await res.json().catch(() => undefined)
+    return { body: parsed, res }
+  }
+
+  return {
+    async getRows(request: ServerRequest): Promise<ServerResult<TData>> {
+      // Static `query` params first; the built paging/sort/filter params win on conflict.
+      const qs = new URLSearchParams({ ...config.query, ...buildQuery(request) }).toString()
+      const url = qs ? `${base}?${qs}` : base
+      const { body, res } = (await send(url, { headers: headers() })) as { body: unknown; res: Response }
+      return parse(body, res)
+    },
+
+    async createRow(input: Partial<TData>): Promise<TData> {
+      const { body } = (await send(base, {
+        method: 'POST',
+        headers: headers({ 'content-type': 'application/json' }),
+        body: JSON.stringify(input),
+      })) as { body: unknown }
+      return (body ?? input) as TData
+    },
+
+    async updateRow(id: string, patch: Partial<TData>): Promise<TData> {
+      const { body } = (await send(`${base}/${encodeURIComponent(id)}`, {
+        method: 'PATCH',
+        headers: headers({ 'content-type': 'application/json' }),
+        body: JSON.stringify(patch),
+      })) as { body: unknown }
+      return (body ?? { ...patch, [idField]: id }) as TData
+    },
+
+    async deleteRow(id: string): Promise<void> {
+      await send(`${base}/${encodeURIComponent(id)}`, { method: 'DELETE', headers: headers() })
+    },
+  }
+}

package/src/sources/schema-from-columns.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest'
+import type { EntitySchema } from '../schema'
+import { buildEntitySchema, linkRelationLabels, pickLabelField } from './schema-from-columns'
+
+describe('buildEntitySchema', () => {
+  it('uses an explicit primary key and marks it readonly', () => {
+    const s = buildEntitySchema('t', [
+      { name: 'name', type: 'text' },
+      { name: 'code', type: 'text', primaryKey: true },
+    ])
+    expect(s.idField).toBe('code')
+    expect(s.fields.find((f) => f.field === 'code')).toMatchObject({ primaryKey: true, readonly: true })
+  })
+
+  it('falls back to a column named id, then the first column', () => {
+    expect(buildEntitySchema('t', [{ name: 'a' }, { name: 'id' }]).idField).toBe('id')
+    expect(buildEntitySchema('t', [{ name: 'first' }, { name: 'second' }]).idField).toBe('first')
+  })
+
+  it('defaults type to text and carries required + enum options', () => {
+    const s = buildEntitySchema('t', [
+      { name: 'id', primaryKey: true },
+      { name: 'name', required: true },
+      { name: 'tier', enumValues: ['free', 'pro'] },
+    ])
+    expect(s.fields.find((f) => f.field === 'name')).toMatchObject({ type: 'text', required: true })
+    const tier = s.fields.find((f) => f.field === 'tier')
+    expect(tier?.type).toBe('enum')
+    expect(tier?.options).toEqual([{ value: 'free', label: 'free' }, { value: 'pro', label: 'pro' }])
+  })
+
+  it('does not mark the primary key as required', () => {
+    const s = buildEntitySchema('t', [{ name: 'id', primaryKey: true, required: true }])
+    expect(s.fields[0]!).toMatchObject({ primaryKey: true, readonly: true })
+    expect(s.fields[0]!.required).toBeUndefined()
+  })
+
+  it('throws with no columns', () => {
+    expect(() => buildEntitySchema('t', [])).toThrow(/no columns/)
+  })
+
+  it('turns a foreign-key column into a relation field', () => {
+    const s = buildEntitySchema('contacts', [
+      { name: 'id', primaryKey: true },
+      { name: 'name', required: true },
+      { name: 'company_id', required: true, references: { table: 'companies', column: 'id' } },
+    ])
+    const rel = s.fields.find((f) => f.field === 'company_id')
+    expect(rel).toMatchObject({
+      field: 'company_id',
+      type: 'relation',
+      required: true,
+      relation: { entity: 'companies', foreignKey: 'company_id', labelField: 'name' },
+    })
+  })
+
+  it('does not turn the primary key into a relation even if it references', () => {
+    const s = buildEntitySchema('t', [{ name: 'id', primaryKey: true, references: { table: 'other' } }])
+    expect(s.fields[0]!.type).not.toBe('relation')
+    expect(s.fields[0]).toMatchObject({ primaryKey: true })
+  })
+
+  it('honors an explicit labelField on the reference', () => {
+    const s = buildEntitySchema('t', [
+      { name: 'id', primaryKey: true },
+      { name: 'owner', references: { table: 'users', labelField: 'email' } },
+    ])
+    expect(s.fields.find((f) => f.field === 'owner')?.relation?.labelField).toBe('email')
+  })
+})
+
+describe('pickLabelField', () => {
+  const make = (fieldNames: [string, 'text' | 'number'][]): EntitySchema => ({
+    name: 't', idField: 'id',
+    fields: fieldNames.map(([field, type]) => ({ field, type, ...(field === 'id' ? { primaryKey: true } : {}) })),
+  })
+
+  it('prefers name / title / label', () => {
+    expect(pickLabelField(make([['id', 'number'], ['title', 'text'], ['body', 'text']]))).toBe('title')
+  })
+  it('falls back to the first non-id text field, then the id', () => {
+    expect(pickLabelField(make([['id', 'number'], ['slug', 'text']]))).toBe('slug')
+    expect(pickLabelField(make([['id', 'number'], ['count', 'number']]))).toBe('id')
+  })
+})
+
+describe('linkRelationLabels', () => {
+  it('resolves each relation labelField from the related schema', () => {
+    const companies: EntitySchema = {
+      name: 'companies', idField: 'id',
+      fields: [{ field: 'id', type: 'number', primaryKey: true }, { field: 'name', type: 'text' }],
+    }
+    const contacts: EntitySchema = {
+      name: 'contacts', idField: 'id',
+      fields: [
+        { field: 'id', type: 'number', primaryKey: true },
+        { field: 'company_id', type: 'relation', relation: { entity: 'companies', foreignKey: 'company_id', labelField: 'name' } },
+        { field: 'buddy_id', type: 'relation', relation: { entity: 'missing', foreignKey: 'buddy_id', labelField: 'name' } },
+      ],
+    }
+    const [, linkedContacts] = linkRelationLabels([companies, contacts])
+    expect(linkedContacts!.fields.find((f) => f.field === 'company_id')?.relation?.labelField).toBe('name')
+    // Unknown related entity is left untouched.
+    expect(linkedContacts!.fields.find((f) => f.field === 'buddy_id')?.relation?.labelField).toBe('name')
+  })
+})

package/src/sources/schema-from-columns.ts

@@ -0,0 +1,88 @@
+/**
+ * The shared "columns -> EntitySchema" core. Every introspection path (SQL
+ * catalog, PostgREST/OpenAPI, a sample row, manual entry) discovers columns in
+ * its own way, then hands a normalized list here to assemble a consistent
+ * `EntitySchema` - primary key resolution, readonly on the key, enum options,
+ * and a sane default type. Keeping this in one place means the grid + form come
+ * out identical no matter which path found the columns.
+ */
+import type { RowData } from '@svgrid/grid'
+import type { EntityField, EntityFieldType, EntitySchema } from '../schema.js'
+import { refineField } from './field-inference.js'
+
+/** A discovered foreign key: this column references `table`.`column`. */
+export type ColumnReference = {
+  /** Referenced table (becomes the relation's `entity`). */
+  table: string
+  /** Referenced column (usually the related PK). */
+  column?: string
+  /** Field on the related entity to show the user. Defaults to `'name'`. */
+  labelField?: string
+}
+
+/** One discovered column, backend-neutral. */
+export type IntrospectedColumn = {
+  name: string
+  /** Actual DB column, when it differs from `name` (e.g. Drizzle `created_at` vs key `createdAt`). */
+  dbColumn?: string
+  /** High-level type. Defaults to `'text'` when a path can't determine it. */
+  type?: EntityFieldType
+  primaryKey?: boolean
+  /** NOT NULL (becomes a required, non-key field). */
+  required?: boolean
+  /** Allowed values, for enum columns. */
+  enumValues?: string[]
+  /** Foreign key: makes this a `relation` field with a searchable lookup. */
+  references?: ColumnReference
+}
+
+/** Assemble an EntitySchema from discovered columns. */
+export function buildEntitySchema<TData extends RowData = RowData>(
+  table: string,
+  columns: IntrospectedColumn[],
+): EntitySchema<TData> {
+  if (!columns.length) throw new Error(`buildEntitySchema: "${table}" has no columns`)
+
+  // Primary key: first flagged pk, else a column literally named "id", else the
+  // first column (so update/delete always have a key to target).
+  const explicitPk = columns.find((c) => c.primaryKey)?.name
+  const idField = explicitPk ?? columns.find((c) => /^id$/i.test(c.name))?.name ?? columns[0]!.name
+
+  const fields: EntityField<TData>[] = columns.map((c) => {
+    const isPk = c.name === idField
+    // A foreign-key column (that isn't the PK) becomes a relation field, so the
+    // form renders a lookup and master-detail can be inferred.
+    if (c.references && !isPk) {
+      const rel = { field: c.name, type: 'relation' as const } as EntityField<TData>
+      rel.relation = {
+        entity: c.references.table,
+        foreignKey: c.name,
+        labelField: c.references.labelField ?? 'name',
+      }
+      if (c.dbColumn) rel.dbColumn = c.dbColumn
+      if (c.required) rel.required = true
+      return rel
+    }
+
+    const type: EntityFieldType = c.enumValues?.length ? 'enum' : (c.type ?? 'text')
+    const f = { field: c.name, type } as EntityField<TData>
+    if (c.dbColumn) f.dbColumn = c.dbColumn
+    if (isPk) {
+      f.primaryKey = true
+      f.readonly = true
+    } else if (c.required) {
+      f.required = true
+    }
+    if (type === 'enum' && c.enumValues?.length) {
+      f.options = c.enumValues.map((v) => ({ value: v, label: v }))
+    }
+    // Infer a rich editor from the column name/type (phone / email / rating / ...).
+    return refineField(f)
+  })
+
+  return { name: table, label: table, idField, fields }
+}
+
+// Schema-level relation helpers live in ../schema (studio consumes them under
+// node16 resolution); re-exported here so introspection consumers get one entry.
+export { pickLabelField, linkRelationLabels } from '../schema.js'

package/src/sources/supabase.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest'
+import type { ServerRequest } from '@svgrid/grid'
+import type { EntitySchema } from '../schema'
+import { createSupabaseDataSource } from './supabase'
+
+type Customer = { id: number; name: string; email: string; tier: string; mrr: number }
+
+const schema: EntitySchema<Customer> = {
+  name: 'customers',
+  idField: 'id',
+  fields: [
+    { field: 'id', type: 'number', primaryKey: true },
+    { field: 'name', type: 'text' },
+    { field: 'email', type: 'text' },
+    { field: 'tier', type: 'enum', options: [{ value: 'pro', label: 'Pro' }] },
+    { field: 'mrr', type: 'number' },
+  ],
+}
+
+/** A supabase-js-like builder: chainable AND awaitable (thenable). */
+function makeClient(result: unknown) {
+  const calls: Array<[string, unknown[]]> = []
+  const builder: any = new Proxy(
+    {},
+    {
+      get(_t, prop: string) {
+        if (prop === 'then') return (res: (v: unknown) => void) => Promise.resolve(result).then(res)
+        return (...args: unknown[]) => {
+          calls.push([prop, args])
+          return builder
+        }
+      },
+    },
+  )
+  const client = { from: (table: string) => { calls.push(['from', [table]]); return builder } }
+  return { client, calls }
+}
+
+const req = (p: Partial<ServerRequest>): ServerRequest => ({
+  startRow: 0, endRow: 10, pageIndex: 0, pageSize: 10, sortModel: [], filterModel: {}, ...p,
+})
+
+const has = (calls: Array<[string, unknown[]]>, name: string) => calls.filter((c) => c[0] === name)
+
+describe('createSupabaseDataSource reads', () => {
+  it('selects with an exact count and returns rows + rowCount', async () => {
+    const { client, calls } = makeClient({ data: [{ id: 1, name: 'Ada' }], count: 42, error: null })
+    const src = createSupabaseDataSource({ client, table: 'customers', schema })
+    const out = await src.getRows(req({}))
+    expect(has(calls, 'select')[0]![1]).toEqual(['*', { count: 'exact' }])
+    expect(has(calls, 'range')[0]![1]).toEqual([0, 9])
+    expect(out).toEqual({ rows: [{ id: 1, name: 'Ada' }], rowCount: 42 })
+  })
+
+  it('maps filters, sort, and global search onto the query builder', async () => {
+    const { client, calls } = makeClient({ data: [], count: 0, error: null })
+    const src = createSupabaseDataSource({ client, table: 'customers', schema })
+    await src.getRows(
+      req({
+        sortModel: [{ id: 'mrr', desc: true }],
+        filterModel: {
+          global: 'ada',
+          columns: {
+            name: { operator: 'contains', value: 'a' },
+            mrr: { operator: 'greaterThan', value: '100' },
+            tier: { operator: 'equals', value: '', selectedValues: ['pro', 'free'] },
+          },
+        },
+      }),
+    )
+    expect(has(calls, 'ilike')).toContainEqual(['ilike', ['name', '%a%']])
+    expect(has(calls, 'gt')).toContainEqual(['gt', ['mrr', '100']])
+    expect(has(calls, 'in')).toContainEqual(['in', ['tier', ['pro', 'free']]])
+    expect(has(calls, 'order')).toContainEqual(['order', ['mrr', { ascending: false }]])
+    // global search: OR of ILIKEs across text + enum columns (name, email, tier)
+    expect(has(calls, 'or')[0]![1][0]).toBe('name.ilike.%ada%,email.ilike.%ada%,tier.ilike.%ada%')
+  })
+
+  it('throws on a query error', async () => {
+    const { client } = makeClient({ data: null, count: null, error: { message: 'boom' } })
+    const src = createSupabaseDataSource({ client, table: 'customers', schema })
+    await expect(src.getRows(req({}))).rejects.toThrow('boom')
+  })
+})
+
+describe('createSupabaseDataSource writes', () => {
+  it('strips the primary key on insert', async () => {
+    const { client, calls } = makeClient({ data: { id: 9, name: 'New' }, error: null })
+    const src = createSupabaseDataSource({ client, table: 'customers', schema })
+    const row = await src.createRow({ id: 123, name: 'New' } as Partial<Customer>)
+    expect(has(calls, 'insert')[0]![1]).toEqual([{ name: 'New' }])
+    expect(row).toEqual({ id: 9, name: 'New' })
+  })
+
+  it('updates by the schema id field', async () => {
+    const { client, calls } = makeClient({ data: { id: 5, name: 'X' }, error: null })
+    const src = createSupabaseDataSource({ client, table: 'customers', schema })
+    await src.updateRow('5', { name: 'X' })
+    expect(has(calls, 'update')[0]![1]).toEqual([{ name: 'X' }])
+    expect(has(calls, 'eq')[0]![1]).toEqual(['id', '5'])
+  })
+
+  it('deletes by the schema id field', async () => {
+    const { client, calls } = makeClient({ error: null })
+    const src = createSupabaseDataSource({ client, table: 'customers', schema })
+    await src.deleteRow('7')
+    expect(has(calls, 'delete').length).toBe(1)
+    expect(has(calls, 'eq')[0]![1]).toEqual(['id', '7'])
+  })
+})

package/src/sources/supabase.ts

@@ -0,0 +1,99 @@
+/**
+ * createSupabaseDataSource - a browser-ready `ServerDataSource` over a Supabase
+ * table, using the `supabase-js` client (PostgREST). You bring the client (so
+ * there's no dependency here and Row-Level Security + auth apply per request);
+ * this maps the grid's sort / filter / page / CRUD onto the query builder.
+ *
+ *     import { createClient } from '@supabase/supabase-js'
+ *     const client = createClient(url, anonKey)
+ *     const source = createSupabaseDataSource({ client, table: 'customers', schema })
+ *
+ * Global search covers the schema's text + enum columns by default; override
+ * with `searchColumns`. The primary key comes from the schema (`idField`) and is
+ * stripped from inserts (it's database-generated).
+ */
+import type { RowData, ServerRequest, ServerResult } from '@svgrid/grid'
+import { resolveIdField, type EntitySchema } from '../schema'
+import { nudgeEnterprise } from '../license'
+import type { WritableDataSource } from '../sveltekit/types'
+import { normalizeFilters } from './filters'
+
+/** The slice of a `supabase-js` client this adapter needs. */
+export type SupabaseClientLike = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  from(table: string): any
+}
+
+export type SupabaseDataSourceConfig<TData extends RowData> = {
+  client: SupabaseClientLike
+  /** Table (or view) name. */
+  table: string
+  schema: EntitySchema<TData>
+  /**
+   * Columns the global search box matches (OR of ILIKEs). Defaults to the
+   * schema's text + enum fields.
+   */
+  searchColumns?: string[]
+}
+
+const sanitize = (term: string) => term.replace(/[%,()]/g, '')
+
+export function createSupabaseDataSource<TData extends RowData>(
+  config: SupabaseDataSourceConfig<TData>,
+): WritableDataSource<TData> {
+  nudgeEnterprise('Studio') // soft-gate; never blocks
+  const { client, table, schema } = config
+  const idField = resolveIdField(schema)
+  const searchColumns =
+    config.searchColumns ??
+    schema.fields.filter((f) => f.type === 'text' || f.type === 'enum').map((f) => String(f.field))
+
+  return {
+    async getRows(request: ServerRequest): Promise<ServerResult<TData>> {
+      let q = client.from(table).select('*', { count: 'exact' })
+
+      const { predicates, search } = normalizeFilters(request.filterModel)
+      for (const p of predicates) {
+        switch (p.op) {
+          case 'in': q = q.in(p.column, p.values); break
+          case 'contains': q = q.ilike(p.column, `%${p.value}%`); break
+          case 'startsWith': q = q.ilike(p.column, `${p.value}%`); break
+          case 'eq': q = q.eq(p.column, p.value); break
+          case 'gt': q = q.gt(p.column, p.value); break
+          case 'lt': q = q.lt(p.column, p.value); break
+          case 'between': q = q.gte(p.column, p.value).lte(p.column, p.valueTo); break
+          case 'isNull': q = q.is(p.column, null); break
+        }
+      }
+      if (search && searchColumns.length) {
+        const term = sanitize(search)
+        q = q.or(searchColumns.map((c) => `${c}.ilike.%${term}%`).join(','))
+      }
+
+      for (const s of request.sortModel) q = q.order(s.id, { ascending: !s.desc })
+
+      const { data, count, error } = await q.range(request.startRow, request.endRow - 1)
+      if (error) throw new Error(error.message)
+      return { rows: (data ?? []) as ReadonlyArray<TData>, rowCount: count ?? 0 }
+    },
+
+    async createRow(input: Partial<TData>): Promise<TData> {
+      const rest = { ...input } as RowData
+      delete rest[idField] // primary key is database-generated
+      const { data, error } = await client.from(table).insert(rest).select().single()
+      if (error) throw new Error(error.message)
+      return (data ?? input) as TData
+    },
+
+    async updateRow(id: string, patch: Partial<TData>): Promise<TData> {
+      const { data, error } = await client.from(table).update(patch).eq(idField, id).select().single()
+      if (error) throw new Error(error.message)
+      return (data ?? { ...patch, [idField]: id }) as TData
+    },
+
+    async deleteRow(id: string): Promise<void> {
+      const { error } = await client.from(table).delete().eq(idField, id)
+      if (error) throw new Error(error.message)
+    },
+  }
+}