@svgrid/enterprise 1.2.0 → 2.0.0

package/src/studio/verify.ts

@@ -0,0 +1,79 @@
+/**
+ * verifyScaffold - the generator's self-check. Compiles each generated
+ * `.svelte` file with Svelte's own compiler and reports any errors, so
+ * malformed output is caught BEFORE it's written to a project. This is the
+ * cheap first gate of the verify loop; the deep gate (type resolution across
+ * real imports) is the host running the project's own `svelte-check`.
+ *
+ * The Svelte compiler is imported dynamically and best-effort: if it can't be
+ * resolved (e.g. a bare `npx @svgrid/mcp` with no svelte on disk), those files
+ * are counted as `skipped` rather than failing - the function never throws and
+ * carries no hard dependency, so it's safe in Node and in the browser.
+ *
+ * `.ts` files aren't compiled here (that needs the project's tsc + imports);
+ * they're reported as skipped.
+ */
+import type { GeneratedFile } from './scaffold.js'
+
+export type VerifySeverity = 'error' | 'warning'
+export type VerifyIssue = { path: string; severity: VerifySeverity; message: string }
+export type VerifyResult = {
+  /** True when no error-level issues were found (warnings are allowed). */
+  ok: boolean
+  issues: VerifyIssue[]
+  /** How many files were actually compiled. */
+  checked: number
+  /** How many files were skipped (non-svelte, or compiler unavailable). */
+  skipped: number
+}
+
+export async function verifyScaffold(
+  files: ReadonlyArray<GeneratedFile>,
+): Promise<VerifyResult> {
+  const issues: VerifyIssue[] = []
+  let checked = 0
+  let skipped = 0
+
+  let compile: ((source: string, options: Record<string, unknown>) => { warnings: Array<{ message?: string }> }) | undefined
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mod: any = await import('svelte/compiler')
+    compile = mod.compile
+  } catch {
+    compile = undefined
+  }
+
+  for (const file of files) {
+    if (!file.path.endsWith('.svelte') || !compile) {
+      skipped++
+      continue
+    }
+    try {
+      const { warnings } = compile(file.contents, { filename: file.path, generate: 'client' })
+      checked++
+      for (const w of warnings) {
+        issues.push({ path: file.path, severity: 'warning', message: w.message ?? 'warning' })
+      }
+    } catch (err) {
+      checked++
+      issues.push({
+        path: file.path,
+        severity: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+
+  return { ok: !issues.some((i) => i.severity === 'error'), issues, checked, skipped }
+}
+
+/** One-line human summary of a verify result, for tool output / logs. */
+export function summarizeVerify(result: VerifyResult): string {
+  if (result.checked === 0) {
+    return 'verification skipped (Svelte compiler unavailable) - run svelte-check in your project.'
+  }
+  const errors = result.issues.filter((i) => i.severity === 'error')
+  if (errors.length === 0) return `verified: ${result.checked} file(s) compile.`
+  return `VERIFICATION FAILED (${errors.length} error(s)):\n` +
+    errors.map((e) => `  ${e.path}: ${e.message}`).join('\n')
+}

package/src/sveltekit/in-memory.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest'
+import type { ServerRequest } from '@svgrid/grid'
+import type { EntitySchema } from '../schema'
+import { createInMemoryDataSource } from './in-memory'
+
+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' },
+  { id: '3', name: 'Cara', age: 25, tier: 'pro' },
+  { id: '4', name: 'Dan', age: 55, tier: 'free' },
+  { id: '5', name: 'Eve', age: 38, tier: 'pro' },
+]
+
+function req(partial: Partial<ServerRequest>): ServerRequest {
+  return { startRow: 0, endRow: 50, pageIndex: 0, pageSize: 50, sortModel: [], filterModel: {}, ...partial }
+}
+
+describe('createInMemoryDataSource reads', () => {
+  it('filters with a numeric operator and reports the filtered count', async () => {
+    const src = createInMemoryDataSource(seed, schema)
+    const { rows, rowCount } = await src.getRows(
+      req({ filterModel: { columns: { age: { operator: 'greaterThan', value: '35' } } } }),
+    )
+    expect(rows.map((r) => r.name).sort()).toEqual(['Bob', 'Dan', 'Eve'])
+    expect(rowCount).toBe(3)
+  })
+
+  it('runs a case-insensitive global search over textual fields', async () => {
+    const src = createInMemoryDataSource(seed, schema)
+    const { rows } = await src.getRows(req({ filterModel: { global: 'PRO' } }))
+    expect(rows.map((r) => r.id).sort()).toEqual(['1', '3', '5'])
+  })
+
+  it('sorts descending and pages', async () => {
+    const src = createInMemoryDataSource(seed, schema)
+    const { rows, rowCount } = await src.getRows(
+      req({ sortModel: [{ id: 'age', desc: true }], startRow: 0, pageSize: 2 }),
+    )
+    expect(rows.map((r) => r.age)).toEqual([55, 41])
+    expect(rowCount).toBe(5)
+  })
+
+  it('an `in` (facet) filter selects the listed values', async () => {
+    const src = createInMemoryDataSource(seed, schema)
+    const { rows } = await src.getRows(
+      req({ filterModel: { columns: { tier: { operator: 'equals', value: '', selectedValues: ['free'] } } } }),
+    )
+    expect(rows.map((r) => r.name).sort()).toEqual(['Bob', 'Dan'])
+  })
+})
+
+describe('createInMemoryDataSource writes', () => {
+  it('creates, updates, and deletes, reflected in subsequent reads', async () => {
+    const src = createInMemoryDataSource(seed, schema)
+
+    const created = await src.createRow({ id: '6', name: 'Fay', age: 22, tier: 'free' })
+    expect(created.name).toBe('Fay')
+    expect((await src.getRows(req({}))).rowCount).toBe(6)
+
+    const updated = await src.updateRow('6', { age: 23 })
+    expect(updated.age).toBe(23)
+
+    await src.deleteRow('1')
+    const after = await src.getRows(req({}))
+    expect(after.rowCount).toBe(5)
+    expect(after.rows.some((r) => r.id === '1')).toBe(false)
+  })
+
+  it('throws when updating a missing row', async () => {
+    const src = createInMemoryDataSource(seed, schema)
+    await expect(src.updateRow('999', { age: 1 })).rejects.toThrow(/no row with id="999"/)
+  })
+
+  it('getAggregate groups + reduces, honoring a filter', async () => {
+    const src = createInMemoryDataSource(seed, schema)
+    expect(await src.getAggregate({ dimension: 'tier', reduce: 'count' })).toEqual([
+      { category: 'pro', value: 3 },
+      { category: 'free', value: 2 },
+    ])
+    // filtered: only age > 35 -> Bob(free), Dan(free), Eve(pro)
+    const filtered = await src.getAggregate({
+      dimension: 'tier', reduce: 'count',
+      filterModel: { columns: { age: { operator: 'greaterThan', value: '35' } } },
+    })
+    expect(filtered).toEqual([{ category: 'free', value: 2 }, { category: 'pro', value: 1 }])
+  })
+
+  it('getAggregate with no dimension is a single grand total (a KPI)', async () => {
+    const src = createInMemoryDataSource(seed, schema)
+    expect(await src.getAggregate({ reduce: 'count' })).toEqual([{ category: '', value: 5 }])
+  })
+})

package/src/sveltekit/in-memory.ts

@@ -0,0 +1,129 @@
+/**
+ * In-memory reference `ServerDataSource`. Applies a `QueryPlan` to a plain
+ * array - filter, global search, sort, page - and supports the full CRUD
+ * contract. It is the executable specification of what a backend adapter must
+ * do, and is genuinely useful on its own for small datasets, tests, demos,
+ * and prototyping a schema before a database exists behind it.
+ */
+import type { RowData, ServerRequest, ServerResult } from '@svgrid/grid'
+import { resolveIdField, type EntitySchema } from '../schema'
+import { planQuery, type PlanPredicate, type QueryPlan } from './query-plan'
+import type { WritableDataSource } from './types'
+import { aggregateRows, type AggregateBucket, type AggregateRequest, type AggregateSource } from '../sources/aggregate'
+
+function asString(v: unknown): string {
+  return v == null ? '' : String(v)
+}
+
+function num(v: unknown): number {
+  return typeof v === 'number' ? v : Number(v)
+}
+
+function matchesPredicate(row: RowData, p: PlanPredicate): boolean {
+  const cell = row[p.field]
+  switch (p.op) {
+    case 'eq':
+      return asString(cell) === asString(p.value)
+    case 'contains':
+      return asString(cell).toLowerCase().includes(asString(p.value).toLowerCase())
+    case 'startsWith':
+      return asString(cell).toLowerCase().startsWith(asString(p.value).toLowerCase())
+    case 'gt':
+      return typeof p.value === 'number' ? num(cell) > p.value : asString(cell) > asString(p.value)
+    case 'lt':
+      return typeof p.value === 'number' ? num(cell) < p.value : asString(cell) < asString(p.value)
+    case 'between': {
+      if (typeof p.value === 'number' && typeof p.valueTo === 'number') {
+        return num(cell) >= p.value && num(cell) <= p.valueTo
+      }
+      return asString(cell) >= asString(p.value) && asString(cell) <= asString(p.valueTo)
+    }
+    case 'isBlank':
+      return cell == null || cell === ''
+    case 'in':
+      return (p.values ?? []).some((v) => asString(v) === asString(cell))
+    default:
+      return true
+  }
+}
+
+function matches(row: RowData, plan: QueryPlan): boolean {
+  if (plan.search) {
+    const term = plan.search.term.toLowerCase()
+    const hit = plan.search.fields.some((f) => asString(row[f]).toLowerCase().includes(term))
+    if (!hit) return false
+  }
+  return plan.where.every((p) => matchesPredicate(row, p))
+}
+
+function sortRows<T extends RowData>(rows: T[], orderBy: QueryPlan['orderBy']): T[] {
+  if (orderBy.length === 0) return rows
+  // Stable multi-key sort: decorate with index, compare keys in order, fall back to index.
+  return rows
+    .map((row, index) => ({ row, index }))
+    .sort((a, b) => {
+      for (const { field, desc } of orderBy) {
+        const av = a.row[field]
+        const bv = b.row[field]
+        let cmp: number
+        if (typeof av === 'number' && typeof bv === 'number') cmp = av - bv
+        else cmp = asString(av).localeCompare(asString(bv))
+        if (cmp !== 0) return desc ? -cmp : cmp
+      }
+      return a.index - b.index
+    })
+    .map((d) => d.row)
+}
+
+export function createInMemoryDataSource<TData extends RowData>(
+  initial: ReadonlyArray<TData>,
+  schema: EntitySchema<TData>,
+): WritableDataSource<TData> & AggregateSource & { rows(): ReadonlyArray<TData> } {
+  let store: TData[] = [...initial]
+  const idField = resolveIdField(schema)
+
+  return {
+    async getRows(request: ServerRequest): Promise<ServerResult<TData>> {
+      const plan = planQuery(schema, request)
+      const filtered = sortRows(
+        store.filter((r) => matches(r, plan)),
+        plan.orderBy,
+      )
+      return {
+        rows: filtered.slice(plan.offset, plan.offset + plan.limit),
+        rowCount: filtered.length,
+      }
+    },
+    async createRow(input: Partial<TData>): Promise<TData> {
+      const row = { ...input } as TData
+      store = [...store, row]
+      return row
+    },
+    async updateRow(id: string, patch: Partial<TData>): Promise<TData> {
+      let updated: TData | undefined
+      store = store.map((r) => {
+        if (asString(r[idField]) === id) {
+          updated = { ...r, ...patch }
+          return updated
+        }
+        return r
+      })
+      if (!updated) throw new Error(`createInMemoryDataSource: no row with ${idField}="${id}"`)
+      return updated
+    },
+    async deleteRow(id: string): Promise<void> {
+      store = store.filter((r) => asString(r[idField]) !== id)
+    },
+    async getAggregate(request: AggregateRequest): Promise<AggregateBucket[]> {
+      // Apply the (optional) filter using the same plan machinery as getRows,
+      // over the whole store (no paging), then reduce in memory.
+      const plan = planQuery(schema, {
+        startRow: 0, endRow: store.length, pageIndex: 0, pageSize: store.length,
+        sortModel: [], filterModel: request.filterModel ?? {},
+      })
+      const filtered = store.filter((r) => matches(r, plan))
+      return aggregateRows(filtered, request)
+    },
+    rows: () => store,
+  }
+}

package/src/sveltekit/index.ts

@@ -0,0 +1,23 @@
+export {
+  planQuery,
+  coerce,
+  type QueryPlan,
+  type PlanPredicate,
+  type PlanOp,
+} from './query-plan'
+export { createInMemoryDataSource } from './in-memory'
+export {
+  createKitDataSource,
+  createKitHandlers,
+  type KitDataSourceOptions,
+  type KitHandlerOptions,
+  type KitHandlers,
+  type KitMessage,
+} from './transport'
+export { planToSql, type SqlDialect, type SqlPlan } from './sql'
+export {
+  createSqlDataSource,
+  type SqlExecutor,
+  type SqlDataSourceConfig,
+} from './sql-source'
+export type { WritableDataSource } from './types'

package/src/sveltekit/query-plan.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest'
+import type { ServerRequest } from '@svgrid/grid'
+import type { EntitySchema } from '../schema'
+import { planQuery } from './query-plan'
+
+type Customer = { id: string; name: string; age: number; tier: string; active: boolean }
+
+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', options: [{ value: 'free', label: 'Free' }, { value: 'pro', label: 'Pro' }] },
+    { field: 'active', type: 'boolean' },
+  ],
+}
+
+function req(partial: Partial<ServerRequest>): ServerRequest {
+  return {
+    startRow: 0,
+    endRow: 50,
+    pageIndex: 0,
+    pageSize: 50,
+    sortModel: [],
+    filterModel: {},
+    ...partial,
+  }
+}
+
+describe('planQuery', () => {
+  it('maps grid operators to plan predicates', () => {
+    const plan = planQuery(
+      schema,
+      req({ filterModel: { columns: { name: { operator: 'contains', value: 'ann' } } } }),
+    )
+    expect(plan.where).toEqual([{ field: 'name', op: 'contains', value: 'ann' }])
+  })
+
+  it('coerces numeric operands to numbers', () => {
+    const plan = planQuery(
+      schema,
+      req({ filterModel: { columns: { age: { operator: 'greaterThan', value: '30' } } } }),
+    )
+    expect(plan.where[0]).toEqual({ field: 'age', op: 'gt', value: 30 })
+  })
+
+  it('turns selectedValues into an `in` predicate', () => {
+    const plan = planQuery(
+      schema,
+      req({ filterModel: { columns: { tier: { operator: 'equals', value: '', selectedValues: ['free', 'pro'] } } } }),
+    )
+    expect(plan.where[0]).toEqual({ field: 'tier', op: 'in', values: ['free', 'pro'] })
+  })
+
+  it('coerces both bounds of a between', () => {
+    const plan = planQuery(
+      schema,
+      req({ filterModel: { columns: { age: { operator: 'between', value: '20', valueTo: '40' } } } }),
+    )
+    expect(plan.where[0]).toEqual({ field: 'age', op: 'between', value: 20, valueTo: 40 })
+  })
+
+  it('whitelists fields: unknown columns are dropped', () => {
+    const plan = planQuery(
+      schema,
+      req({ filterModel: { columns: { evil: { operator: 'contains', value: 'x' } } } }),
+    )
+    expect(plan.where).toHaveLength(0)
+  })
+
+  it('drops empty operator values but keeps isBlank', () => {
+    const plan = planQuery(
+      schema,
+      req({
+        filterModel: {
+          columns: {
+            name: { operator: 'contains', value: '' },
+            id: { operator: 'isBlank', value: '' },
+          },
+        },
+      }),
+    )
+    expect(plan.where).toEqual([{ field: 'id', op: 'isBlank' }])
+  })
+
+  it('builds a search over textual fields only', () => {
+    const plan = planQuery(schema, req({ filterModel: { global: '  acme ' } }))
+    expect(plan.search).toEqual({ term: 'acme', fields: ['name', 'tier'] })
+  })
+
+  it('is null-search when no global term', () => {
+    expect(planQuery(schema, req({})).search).toBeNull()
+  })
+
+  it('maps sort, dropping unknown sort fields', () => {
+    const plan = planQuery(
+      schema,
+      req({ sortModel: [{ id: 'age', desc: true }, { id: 'ghost', desc: false }] }),
+    )
+    expect(plan.orderBy).toEqual([{ field: 'age', desc: true }])
+  })
+
+  it('carries paging through as limit/offset', () => {
+    const plan = planQuery(schema, req({ startRow: 100, pageSize: 25 }))
+    expect(plan.limit).toBe(25)
+    expect(plan.offset).toBe(100)
+  })
+})

package/src/sveltekit/query-plan.ts

@@ -0,0 +1,125 @@
+/**
+ * The query-plan seam. `planQuery` turns the grid's `ServerRequest` (sort +
+ * filter + paging) into a neutral, backend-agnostic `QueryPlan`. Every backend
+ * adapter - the in-memory reference source, `planToSql` for any SQL database,
+ * a Drizzle/Supabase mapping - consumes this one plan, so the request-shaping
+ * logic (operator mapping, type coercion, field whitelisting) lives and is
+ * tested in exactly one place.
+ *
+ * Security note: only fields declared on the `EntitySchema` reach the plan.
+ * Unknown column names in the request are dropped, so a client cannot smuggle
+ * arbitrary identifiers through to SQL.
+ */
+import type { RowData, ServerRequest } from '@svgrid/grid'
+import type { EntityFieldType, EntitySchema } from '../schema'
+
+/** Normalized predicate operators (a stable superset of the grid's filter operators). */
+export type PlanOp = 'eq' | 'contains' | 'startsWith' | 'gt' | 'lt' | 'between' | 'isBlank' | 'in'
+
+export type PlanPredicate = {
+  field: string
+  op: PlanOp
+  /** Single operand (eq / contains / startsWith / gt / lt, and the low bound of between). */
+  value?: unknown
+  /** Upper bound for `between`. */
+  valueTo?: unknown
+  /** Operands for `in` (set / facet filter). */
+  values?: unknown[]
+}
+
+export type QueryPlan = {
+  /** AND-combined column predicates. */
+  where: PlanPredicate[]
+  /** Global free-text search: OR `contains` across these textual fields. Null when no search term. */
+  search: { term: string; fields: string[] } | null
+  orderBy: Array<{ field: string; desc: boolean }>
+  limit: number
+  offset: number
+}
+
+/** Grid filter operator -> normalized plan operator. Unmapped operators are ignored. */
+const OP_MAP: Record<string, PlanOp> = {
+  equals: 'eq',
+  contains: 'contains',
+  startsWith: 'startsWith',
+  greaterThan: 'gt',
+  lessThan: 'lt',
+  between: 'between',
+  isBlank: 'isBlank',
+}
+
+/** Field types that global text search scans. */
+const TEXTUAL: ReadonlySet<EntityFieldType> = new Set<EntityFieldType>(['text', 'enum'])
+
+/** Coerce a raw string request value to the field's runtime type for correct comparisons. */
+export function coerce(type: EntityFieldType, raw: unknown): unknown {
+  if (raw == null) return raw
+  switch (type) {
+    case 'number': {
+      const n = Number(raw)
+      return Number.isFinite(n) ? n : undefined
+    }
+    case 'boolean':
+      return raw === true || raw === 'true'
+    default:
+      // text / date / dateString / datetime / enum / relation / json: compared as strings
+      return typeof raw === 'string' ? raw : String(raw)
+  }
+}
+
+export function planQuery<TData extends RowData>(
+  schema: EntitySchema<TData>,
+  request: ServerRequest,
+): QueryPlan {
+  const fields = new Map(schema.fields.map((f) => [f.field, f]))
+  const where: PlanPredicate[] = []
+  const fm = request.filterModel ?? {}
+
+  for (const [field, spec] of Object.entries(fm.columns ?? {})) {
+    const def = fields.get(field)
+    if (!def) continue // whitelist: ignore columns not on the schema
+
+    // A facet / set selection wins over the operator filter.
+    if (spec.selectedValues && spec.selectedValues.length > 0) {
+      where.push({ field, op: 'in', values: spec.selectedValues.map((v) => coerce(def.type, v)) })
+      continue
+    }
+
+    const op = OP_MAP[spec.operator]
+    if (!op) continue
+
+    if (op === 'isBlank') {
+      where.push({ field, op })
+      continue
+    }
+    if (op === 'between') {
+      where.push({
+        field,
+        op,
+        value: coerce(def.type, spec.value),
+        valueTo: coerce(def.type, spec.valueTo),
+      })
+      continue
+    }
+    if (spec.value === '' || spec.value == null) continue
+    where.push({ field, op, value: coerce(def.type, spec.value) })
+  }
+
+  const term = (fm.global ?? '').trim()
+  const search =
+    term.length > 0
+      ? {
+          term,
+          // Textual, non-key fields: searching a primary key by substring is noise.
+          fields: schema.fields
+            .filter((f) => TEXTUAL.has(f.type) && !f.primaryKey && f.field !== schema.idField)
+            .map((f) => f.field),
+        }
+      : null
+
+  const orderBy = (request.sortModel ?? [])
+    .filter((s) => fields.has(s.id))
+    .map((s) => ({ field: s.id, desc: !!s.desc }))
+
+  return { where, search, orderBy, limit: request.pageSize, offset: request.startRow }
+}