@svgrid/enterprise 1.2.0 → 2.0.0

package/src/sveltekit/transport.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest'
+import type { ServerRequest } from '@svgrid/grid'
+import type { EntitySchema } from '../schema'
+import { createInMemoryDataSource } from './in-memory'
+import { createKitDataSource, createKitHandlers } from './transport'
+
+type Customer = { id: string; name: string; age: number; tier: string }
+
+const schema: EntitySchema<Customer> = {
+  name: 'customers',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true },
+    { field: 'name', type: 'text' },
+    { field: 'age', type: 'number' },
+    { field: 'tier', type: 'enum' },
+  ],
+}
+
+const seed: Customer[] = [
+  { id: '1', name: 'Ann', age: 30, tier: 'pro' },
+  { id: '2', name: 'Bob', age: 41, tier: 'free' },
+]
+
+/**
+ * Stand up the full loop in-process: an in-memory backend behind the server
+ * handlers, and a client whose `fetch` routes straight into those handlers via
+ * a real `Request`. This exercises the wire protocol end to end without a
+ * running SvelteKit server.
+ */
+function wireClientToServer() {
+  const backend = createInMemoryDataSource(seed, schema)
+  const handlers = createKitHandlers({ schema, source: backend })
+  const fakeFetch = (url: string, init?: RequestInit) =>
+    handlers.handle(new Request(`http://localhost${url}`, init))
+  const client = createKitDataSource<Customer>({ endpoint: '/api/customers', fetch: fakeFetch })
+  return { client, backend }
+}
+
+const req = (partial: Partial<ServerRequest>): ServerRequest => ({
+  startRow: 0,
+  endRow: 50,
+  pageIndex: 0,
+  pageSize: 50,
+  sortModel: [],
+  filterModel: {},
+  ...partial,
+})
+
+describe('SvelteKit transport round trip', () => {
+  it('getRows travels client -> server -> backend and back', async () => {
+    const { client } = wireClientToServer()
+    const res = await client.getRows(req({ sortModel: [{ id: 'age', desc: true }] }))
+    expect(res.rowCount).toBe(2)
+    expect(res.rows[0]?.name).toBe('Bob')
+  })
+
+  it('createRow / updateRow / deleteRow mutate the backend through the protocol', async () => {
+    const { client, backend } = wireClientToServer()
+
+    const created = await client.createRow({ id: '3', name: 'Cara', age: 25, tier: 'pro' })
+    expect(created.name).toBe('Cara')
+    expect(backend.rows()).toHaveLength(3)
+
+    const updated = await client.updateRow('3', { age: 26 })
+    expect(updated.age).toBe(26)
+
+    await client.deleteRow('1')
+    expect(backend.rows().some((r) => r.id === '1')).toBe(false)
+  })
+
+  it('surfaces a backend error as a rejected fetch', async () => {
+    const { client } = wireClientToServer()
+    // updating a non-existent id makes the in-memory source throw -> 500
+    await expect(client.updateRow('nope', { age: 1 })).rejects.toThrow(/svgrid kit: 500/)
+  })
+
+  it('returns 405 when the backend lacks a writer', async () => {
+    const readOnly = { getRows: async () => ({ rows: [], rowCount: 0 }) }
+    const handlers = createKitHandlers({ schema, source: readOnly })
+    const client = createKitDataSource<Customer>({
+      endpoint: '/x',
+      fetch: (url, init) => handlers.handle(new Request(`http://localhost${url}`, init)),
+    })
+    await expect(client.createRow({ name: 'x' })).rejects.toThrow(/405/)
+  })
+})
+
+describe('createKitHandlers server-enforced validation', () => {
+  const vSchema: EntitySchema<Customer> = {
+    name: 'customers',
+    fields: [
+      { field: 'id', type: 'text', primaryKey: true },
+      { field: 'name', type: 'text', required: true },
+      { field: 'age', type: 'number', min: 0, max: 120 },
+      { field: 'tier', type: 'enum' },
+    ],
+  }
+  const post = (h: ReturnType<typeof createKitHandlers>, body: unknown) =>
+    h.handle(new Request('http://localhost/api/customers', { method: 'POST', body: JSON.stringify(body) }))
+
+  it('rejects a constraint-violating create with 422 + fieldErrors', async () => {
+    const handlers = createKitHandlers({ schema: vSchema, source: createInMemoryDataSource<Customer>([], vSchema), validate: true })
+    const res = await post(handlers, { kind: 'mutate', op: 'create', input: { id: '9', age: 999 } })
+    expect(res.status).toBe(422)
+    const body = await res.json()
+    expect(body.fieldErrors.name).toBeTruthy() // required missing
+    expect(body.fieldErrors.age).toBeTruthy()  // above max
+  })
+
+  it('accepts a valid create', async () => {
+    const handlers = createKitHandlers({ schema: vSchema, source: createInMemoryDataSource<Customer>([], vSchema), validate: true })
+    const res = await post(handlers, { kind: 'mutate', op: 'create', input: { id: '9', name: 'Zoe', age: 22 } })
+    expect(res.status).toBe(200)
+  })
+
+  it('validates only the fields present in an update patch', async () => {
+    const handlers = createKitHandlers({ schema: vSchema, source: createInMemoryDataSource<Customer>(seed, vSchema), validate: true })
+    // omits required `name` (fine - not in the patch), valid age -> 200
+    expect((await post(handlers, { kind: 'mutate', op: 'update', id: '1', patch: { age: 33 } })).status).toBe(200)
+    // bad age in the patch -> 422
+    expect((await post(handlers, { kind: 'mutate', op: 'update', id: '1', patch: { age: -5 } })).status).toBe(422)
+  })
+
+  it('is off by default (no validation unless opted in)', async () => {
+    const handlers = createKitHandlers({ schema: vSchema, source: createInMemoryDataSource<Customer>([], vSchema) })
+    const res = await post(handlers, { kind: 'mutate', op: 'create', input: { id: '9', age: 999 } })
+    expect(res.status).toBe(200)
+  })
+})
+
+describe('createKitHandlers audit hook', () => {
+  const post = (h: ReturnType<typeof createKitHandlers>, b: unknown) =>
+    h.handle(new Request('http://localhost/api/customers', { method: 'POST', body: JSON.stringify(b) }))
+
+  it('fires after create / update / delete with the change details', async () => {
+    const log: Array<{ action: string; id: string | null; values?: unknown }> = []
+    const handlers = createKitHandlers({ schema, source: createInMemoryDataSource(seed, schema), audit: (e) => { log.push({ action: e.action, id: e.id, values: e.values }) } })
+    await post(handlers, { kind: 'mutate', op: 'create', input: { id: '9', name: 'Zoe', age: 20, tier: 'pro' } })
+    await post(handlers, { kind: 'mutate', op: 'update', id: '9', patch: { age: 21 } })
+    await post(handlers, { kind: 'mutate', op: 'delete', id: '9' })
+    expect(log.map((e) => e.action)).toEqual(['create', 'update', 'delete'])
+    expect(log[0]!.id).toBe('9')
+    expect(log[1]!.values).toEqual({ age: 21 })
+  })
+
+  it('never fires on reads, and a throwing audit sink does not fail the write', async () => {
+    let fired = 0
+    const handlers = createKitHandlers({ schema, source: createInMemoryDataSource(seed, schema), audit: () => { fired++; throw new Error('sink down') } })
+    expect((await post(handlers, { kind: 'query', request: req({}) })).status).toBe(200)
+    expect(fired).toBe(0)
+    expect((await post(handlers, { kind: 'mutate', op: 'create', input: { id: '9', name: 'Z', age: 1, tier: 'x' } })).status).toBe(200)
+    expect(fired).toBe(1) // audit ran, but the write still succeeded
+  })
+})
+
+describe('createKitHandlers authorize (RBAC seam)', () => {
+  const body = (b: unknown, init: RequestInit = {}) =>
+    new Request('http://localhost/api/customers', { method: 'POST', body: JSON.stringify(b), ...init })
+
+  it('reads pass but writes 403 when authorize denies them', async () => {
+    const handlers = createKitHandlers({ schema, source: createInMemoryDataSource(seed, schema), authorize: ({ action }) => action === 'read' })
+    expect((await handlers.handle(body({ kind: 'query', request: req({}) }))).status).toBe(200)
+    expect((await handlers.handle(body({ kind: 'mutate', op: 'delete', id: '1' }))).status).toBe(403)
+  })
+
+  it('resolves the role from event.locals', async () => {
+    const handlers = createKitHandlers({
+      schema,
+      source: createInMemoryDataSource(seed, schema),
+      authorize: ({ action, event }) => action === 'read' || event.locals?.role === 'admin',
+    })
+    expect((await handlers.handle(body({ kind: 'mutate', op: 'delete', id: '1' }), { locals: { role: 'viewer' } })).status).toBe(403)
+    expect((await handlers.handle(body({ kind: 'mutate', op: 'delete', id: '2' }), { locals: { role: 'admin' } })).status).toBe(200)
+  })
+})

package/src/sveltekit/transport.ts

@@ -0,0 +1,254 @@
+/**
+ * SvelteKit transport - the deep integration an agnostic grid can't ship.
+ *
+ * Two halves that speak one small JSON protocol over a single route:
+ *
+ *   - `createKitDataSource({ endpoint })` runs in the browser (or a `load`
+ *     function) and returns a `ServerDataSource` that POSTs requests to your
+ *     endpoint. Drop it straight into `createServerDataSource`.
+ *
+ *   - `createKitHandlers({ schema, source })` runs on the server and returns a
+ *     `POST` handler for a `+server.ts` route. It parses the protocol, calls
+ *     your backend `ServerDataSource` (in-memory, SQL, Drizzle, ...), and
+ *     returns JSON.
+ *
+ * Example `src/routes/api/customers/+server.ts`:
+ *
+ *     import { createKitHandlers } from '@svgrid/enterprise'
+ *     import { customerSchema, customerSource } from '$lib/customers'
+ *     export const { POST } = createKitHandlers({ schema: customerSchema, source: customerSource })
+ *
+ * Client:
+ *
+ *     const source = createKitDataSource({ endpoint: '/api/customers' })
+ *     const controller = createServerDataSource(source, { onChange: ... })
+ */
+import type {
+  RowData,
+  ServerDataSource,
+  ServerRequest,
+  ServerResult,
+} from '@svgrid/grid'
+import type { EntitySchema } from '../schema'
+import { validateAll } from '../edit-panel'
+import type { WritableDataSource } from './types'
+
+/** Wire protocol: the single JSON body shape the client POSTs and the server dispatches on. */
+export type KitMessage<TData> =
+  | { kind: 'query'; request: ServerRequest }
+  | { kind: 'mutate'; op: 'create'; input: Partial<TData> }
+  | { kind: 'mutate'; op: 'update'; id: string; patch: Partial<TData> }
+  | { kind: 'mutate'; op: 'delete'; id: string }
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+// --- client ---------------------------------------------------------------
+
+export type KitDataSourceOptions = {
+  /** Route that `createKitHandlers` is mounted on, e.g. `'/api/customers'`. */
+  endpoint: string
+  /**
+   * Fetch implementation. Pass SvelteKit's event `fetch` inside a `load` so
+   * requests are same-origin and SSR-safe; defaults to the global `fetch`.
+   */
+  fetch?: FetchLike
+}
+
+export function createKitDataSource<TData extends RowData>(
+  options: KitDataSourceOptions,
+): WritableDataSource<TData> {
+  const doFetch: FetchLike = options.fetch ?? ((i, init) => fetch(i, init))
+
+  async function post<T>(body: KitMessage<TData>): Promise<T> {
+    const res = await doFetch(options.endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+    if (!res.ok) {
+      const detail = await res.text().catch(() => '')
+      throw new Error(`svgrid kit: ${res.status} ${res.statusText}${detail ? ` - ${detail}` : ''}`)
+    }
+    return (await res.json()) as T
+  }
+
+  return {
+    getRows: (request) => post<ServerResult<TData>>({ kind: 'query', request }),
+    createRow: (input) => post<TData>({ kind: 'mutate', op: 'create', input }),
+    updateRow: (id, patch) => post<TData>({ kind: 'mutate', op: 'update', id, patch }),
+    deleteRow: (id) => post<void>({ kind: 'mutate', op: 'delete', id }).then(() => undefined),
+  }
+}
+
+// --- server ---------------------------------------------------------------
+
+/** The CRUD action a Kit message maps to (`query` -> `read`). */
+export type KitAction = 'read' | 'create' | 'update' | 'delete'
+/** Context passed to the `authorize` guard before every op. */
+export type KitAuthorizeContext<TData extends RowData> = {
+  action: KitAction
+  /** The SvelteKit request event, so you can read `locals` / session for the
+   *  caller's role or user id. Only `request` is guaranteed in non-Kit callers. */
+  event: { request: Request; locals?: Record<string, unknown> }
+  message: KitMessage<TData>
+}
+
+/** A field-error map (`{ field: message }`); empty/undefined means valid. */
+export type KitFieldErrors = Record<string, string>
+/** Context passed to a custom `validate` function before a create / update. */
+export type KitValidateContext<TData extends RowData> = {
+  action: 'create' | 'update'
+  values: Partial<TData>
+  event: { request: Request; locals?: Record<string, unknown> }
+}
+
+export type KitHandlerOptions<TData extends RowData> = {
+  schema: EntitySchema<TData>
+  source: ServerDataSource<TData>
+  /**
+   * Optional server-side guard run BEFORE every op. Return `false` (or throw) to
+   * reject the request with `403`. Receives the SvelteKit event, so you can read
+   * `event.locals` / the session to resolve the caller's role - this is where
+   * server-enforced authorization (RBAC) lives, independent of any client UI.
+   */
+  authorize?: (ctx: KitAuthorizeContext<TData>) => boolean | Promise<boolean>
+  /**
+   * Server-enforced validation, run BEFORE a create / update reaches the source.
+   * - `true`: validate the payload against the `schema`'s declarative constraints
+   *   (required, min/max, length, pattern, email/url, per-field + cross-field
+   *   rules) via `validateAll`. Updates validate only the fields present in the
+   *   patch. Defect payloads are rejected with `422 { error, fieldErrors }`.
+   * - a function: your own check returning a `{ field: message }` map (non-empty
+   *   -> 422).
+   * Default off, so existing routes are unchanged; the Studio generator turns it
+   * on. Enforcing here means a client that skips its form validation still can't
+   * write bad data.
+   */
+  validate?: boolean | ((ctx: KitValidateContext<TData>) => KitFieldErrors | null | undefined | Promise<KitFieldErrors | null | undefined>)
+  /**
+   * Called AFTER a successful create / update / delete with the change details,
+   * so you can write an audit record (who / what / when). Receives the SvelteKit
+   * event for `locals` (the actor). Best-effort: a throw here is swallowed and
+   * logged, so an audit-sink hiccup never fails the underlying write.
+   */
+  audit?: (entry: KitAuditEntry<TData>) => void | Promise<void>
+}
+
+/** The change details handed to the `audit` hook after a successful mutation. */
+export type KitAuditEntry<TData extends RowData> = {
+  action: 'create' | 'update' | 'delete'
+  /** The affected row's id. */
+  id: string | null
+  /** Submitted values: create input / update patch. Undefined for delete. */
+  values?: Partial<TData>
+  /** The row the source returned (create / update). Undefined for delete. */
+  result?: TData
+  event: { request: Request; locals?: Record<string, unknown> }
+}
+
+export type KitHandlers = {
+  /** SvelteKit `+server.ts` route handler. Export it as `export const { POST } = ...`. */
+  POST: (event: { request: Request; locals?: Record<string, unknown> }) => Promise<Response>
+  /** Lower-level dispatcher over a raw `Request`, for custom wiring or tests. */
+  handle: (request: Request, event?: { locals?: Record<string, unknown> }) => Promise<Response>
+}
+
+const actionOf = <TData extends RowData>(msg: KitMessage<TData>): KitAction =>
+  msg.kind === 'query' ? 'read' : msg.op
+
+export function createKitHandlers<TData extends RowData>(
+  options: KitHandlerOptions<TData>,
+): KitHandlers {
+  const { source, authorize, validate, audit } = options
+  const idField = options.schema.idField ?? options.schema.fields.find((f) => f.primaryKey)?.field ?? 'id'
+  const rowId = (row: unknown): string | null => {
+    const v = (row as Record<string, unknown> | null)?.[idField]
+    return v == null ? null : String(v)
+  }
+  // Best-effort: never let an audit-sink error fail the write it's recording.
+  const fireAudit = async (entry: KitAuditEntry<TData>) => {
+    if (!audit) return
+    try { await audit(entry) } catch (err) { console.error('svgrid kit: audit hook failed', err) }
+  }
+
+  async function handle(request: Request, event?: { locals?: Record<string, unknown> }): Promise<Response> {
+    let msg: KitMessage<TData>
+    try {
+      msg = (await request.json()) as KitMessage<TData>
+    } catch {
+      return jsonResponse({ error: 'invalid JSON body' }, 400)
+    }
+
+    // Authorize BEFORE touching the source. A thrown guard is treated as a deny.
+    if (authorize) {
+      let allowed: boolean
+      try {
+        allowed = await authorize({ action: actionOf(msg), event: { request, locals: event?.locals }, message: msg })
+      } catch (err) {
+        return jsonResponse({ error: err instanceof Error ? err.message : 'forbidden' }, 403)
+      }
+      if (!allowed) return jsonResponse({ error: 'forbidden' }, 403)
+    }
+
+    // Validate create / update payloads BEFORE the source. 422 on field errors.
+    if (validate && msg.kind === 'mutate' && (msg.op === 'create' || msg.op === 'update')) {
+      const values = (msg.op === 'create' ? msg.input : msg.patch) as Partial<TData>
+      let errors: KitFieldErrors | null | undefined
+      if (validate === true) {
+        const all = await validateAll(options.schema, values as Record<string, unknown>)
+        // On update, only the supplied fields are validated (a patch omits the rest).
+        errors = msg.op === 'update'
+          ? Object.fromEntries(Object.keys(values).filter((k) => all[k]).map((k) => [k, all[k]!]))
+          : all
+      } else {
+        errors = await validate({ action: msg.op, values, event: { request, locals: event?.locals } })
+      }
+      if (errors && Object.keys(errors).length) {
+        return jsonResponse({ error: 'validation failed', fieldErrors: errors }, 422)
+      }
+    }
+
+    try {
+      if (msg.kind === 'query') {
+        const result = await source.getRows(msg.request)
+        return jsonResponse(result)
+      }
+      if (msg.kind === 'mutate') {
+        const evt = { request, locals: event?.locals }
+        if (msg.op === 'create') {
+          if (!source.createRow) return jsonResponse({ error: 'create not supported' }, 405)
+          const row = await source.createRow(msg.input)
+          await fireAudit({ action: 'create', id: rowId(row), values: msg.input, result: row, event: evt })
+          return jsonResponse(row)
+        }
+        if (msg.op === 'update') {
+          if (!source.updateRow) return jsonResponse({ error: 'update not supported' }, 405)
+          const row = await source.updateRow(msg.id, msg.patch)
+          await fireAudit({ action: 'update', id: msg.id, values: msg.patch, result: row, event: evt })
+          return jsonResponse(row)
+        }
+        if (msg.op === 'delete') {
+          if (!source.deleteRow) return jsonResponse({ error: 'delete not supported' }, 405)
+          await source.deleteRow(msg.id)
+          await fireAudit({ action: 'delete', id: msg.id, event: evt })
+          return jsonResponse({ ok: true })
+        }
+      }
+      return jsonResponse({ error: 'unknown message kind' }, 400)
+    } catch (err) {
+      return jsonResponse({ error: err instanceof Error ? err.message : String(err) }, 500)
+    }
+  }
+
+  return {
+    handle,
+    POST: (event) => handle(event.request, event),
+  }
+}

package/src/sveltekit/types.ts

@@ -0,0 +1,11 @@
+import type { RowData, ServerDataSource } from '@svgrid/grid'
+
+/**
+ * A `ServerDataSource` that implements the full CRUD contract - the optional
+ * `createRow` / `updateRow` / `deleteRow` are required here. Sources that
+ * always support writes (the in-memory reference source, the SvelteKit client)
+ * return this so callers get the methods without a null check.
+ */
+export type WritableDataSource<TData extends RowData> = Required<
+  Pick<ServerDataSource<TData>, 'getRows' | 'createRow' | 'updateRow' | 'deleteRow'>
+>