@nuxtagentic/data 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+Proprietary software. All rights reserved.
+
+Use of Nuxt Agentic packages and starter materials is governed by the applicable
+commercial agreement supplied with a purchase. This repository does not grant
+an open-source license or permission to redistribute the packages as a competing
+template or module library.
+
+Third-party dependencies retain their respective licenses. This notice does not
+replace or modify those licenses.

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# Data
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@nuxtagentic/data` provides the shared query and table infrastructure. It depends
+on Identity for the active account and organization scope and has no models or
+collection UI of its own.
+
+`useWorkspaceQuery` shares equivalent list requests within a scope.
+`useWorkspaceRecord` loads individual records, and `useWorkspaceRefresh` refreshes
+related lists after mutations. The shared query code validates fields, filters,
+sorting, and pagination against registered model views.
+
+`runtime/shared/model-views.ts` defines the model-view contract and
+`defineModelView`. Features own their actual view definitions and publish them
+through their metadata contributions. Data does not import feature schemas or
+the host config.
+
+Install it through a dependent feature, or add `@nuxtagentic/data` to Nuxt's
+`modules` when using the query helpers directly. See the [module map](../README.md).

package/module.ts

@@ -0,0 +1,19 @@
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+import { registerWorkspaceModule } from '@nuxtagentic/kit'
+
+export default defineNuxtModule({
+  meta: { name: '@nuxtagentic/data' },
+  moduleDependencies: {
+    '@nuxtagentic/identity': {},
+  },
+  setup(_options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+    registerWorkspaceModule(
+      {
+        id: 'data',
+        runtime: resolver.resolve('./runtime'),
+      },
+      nuxt,
+    )
+  },
+})

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@nuxtagentic/data",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "type": "module",
+  "files": [
+    "module.ts",
+    "runtime",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "exports": {
+    ".": "./module.ts",
+    "./package.json": "./package.json",
+    "./runtime/*.vue": "./runtime/*.vue",
+    "./runtime/*.css": "./runtime/*.css",
+    "./runtime/*.json": "./runtime/*.json",
+    "./runtime/*.svg": "./runtime/*.svg",
+    "./runtime/*": "./runtime/*.ts"
+  },
+  "dependencies": {
+    "@cloudconfig/core": "0.2.0-beta.2",
+    "@nuxt/kit": "4.6.1",
+    "h3": "1.15.11",
+    "@nuxtagentic/identity": "0.1.1",
+    "@nuxtagentic/kit": "0.1.1"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.6.1",
+    "vue": "^3.5.43"
+  },
+  "devDependencies": {
+    "tsx": "^4.23.15"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "description": "Scoped typed records and queries for Nuxt Agentic.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": "^22.22.3 || ^24.15.0 || >=26.0.0"
+  }
 }

package/runtime/composables/useWorkspaceQuery.ts

@@ -0,0 +1,38 @@
+import { useWorkspaceScope } from '@nuxtagentic/identity/runtime/composables/useWorkspaceScope'
+import { computed, type Ref } from 'vue'
+import { useAsyncData } from '#imports'
+import { useWorkspaceRefresh } from './useWorkspaceRefresh'
+
+export function useWorkspaceQuery<Row, Query>(
+  name: string,
+  query: Ref<Query>,
+  fetchRows: (query: Query, signal: AbortSignal) => Promise<{ data: Row[]; totalCount: number }>,
+) {
+  const scope = useWorkspaceScope()
+  const refreshAll = useWorkspaceRefresh(name)
+  const prefix = computed(() => `workspace:${name}:${scope.value}:list:`)
+  // Equivalent queries share data and in-flight requests across dashboard surfaces.
+  const key = computed(() => `${prefix.value}${JSON.stringify(query.value)}`)
+  const { data, status, pending, error, refresh } = useAsyncData(
+    key,
+    (_, { signal }) =>
+      scope.value ? fetchRows(query.value, signal) : Promise.resolve({ data: [], totalCount: 0 }),
+    {
+      lazy: true,
+      deep: false,
+      dedupe: 'defer',
+    },
+  )
+
+  return {
+    scope,
+    rows: computed<Row[]>(() => data.value?.data ?? []),
+    totalCount: computed(() => data.value?.totalCount ?? 0),
+    isLoading: computed(() => status.value === 'idle' || status.value === 'pending'),
+    status,
+    pending,
+    error,
+    refresh,
+    refreshAll,
+  }
+}

package/runtime/composables/useWorkspaceRecord.ts

@@ -0,0 +1,26 @@
+import { useAsyncData } from '#imports'
+import { computed, type Ref } from 'vue'
+export interface WorkspaceRecordSource<Row extends { id: number | string }> {
+  id: Ref<Row['id'] | null>
+  /** The workspace the record belongs to; changing it refetches under a new cache key. */
+  scope: Ref<string>
+  get: (id: Row['id']) => Promise<Row>
+}
+
+/** Loads one record of a workspace model, or `null` while nothing is selected. */
+export function useWorkspaceRecord<Row extends { id: number | string }>(
+  name: string,
+  { id, scope, get }: WorkspaceRecordSource<Row>,
+  { server = false }: { server?: boolean } = {},
+) {
+  return useAsyncData(
+    computed(() => `workspace:${name}:${scope.value}:detail:${id.value}`),
+    async () => {
+      if (id.value === null || !scope.value) {
+        return null
+      }
+      return get(id.value)
+    },
+    { server, default: () => null },
+  )
+}

package/runtime/composables/useWorkspaceRefresh.ts

@@ -0,0 +1,15 @@
+import { useNuxtApp, refreshNuxtData } from '#imports'
+import { useWorkspaceScope } from '@nuxtagentic/identity/runtime/composables/useWorkspaceScope'
+
+/** Refresh active queries for a resource in the current user/workspace scope. */
+export function useWorkspaceRefresh(name: string) {
+  const scope = useWorkspaceScope()
+  const nuxtApp = useNuxtApp()
+
+  return () => {
+    const prefix = `workspace:${name}:${scope.value}:list:`
+    return refreshNuxtData(
+      Object.keys(nuxtApp.payload.data).filter((key) => key.startsWith(prefix)),
+    )
+  }
+}

package/runtime/server/utils/cloudconfig-errors.ts

@@ -0,0 +1,13 @@
+import { createError } from 'h3'
+import { CloudConfigClientError } from '@cloudconfig/core/client'
+
+export function throwCloudConfigError(cause: unknown): never {
+  if (cause instanceof CloudConfigClientError) {
+    throw createError({
+      statusCode: cause.status,
+      statusMessage: cause.message,
+      data: { issues: cause.issues },
+    })
+  }
+  throw cause
+}

package/runtime/shared/date-periods.ts

@@ -0,0 +1,30 @@
+const MONTHS = [
+  'january',
+  'february',
+  'march',
+  'april',
+  'may',
+  'june',
+  'july',
+  'august',
+  'september',
+  'october',
+  'november',
+  'december',
+]
+const MONTH_PATTERN = new RegExp(
+  `\\b(${[...MONTHS, ...MONTHS.map((month) => month.slice(0, 3)), 'sept'].join('|')})(?:\\s+(\\d{4}))?\\b`,
+  'gi',
+)
+
+/** Named months cover the whole month, defaulting to the current UTC year. */
+export function findNamedMonthPeriods(source: string, now = new Date()) {
+  return [...source.matchAll(MONTH_PATTERN)].map((match) => {
+    const month = MONTHS.findIndex((name) => name.startsWith(match[1]!.toLowerCase()))
+    const year = match[2] ?? String(now.getUTCFullYear())
+    const start = new Date(`${year}-${String(month + 1).padStart(2, '0')}-01T00:00:00.000Z`)
+    const end = new Date(start)
+    end.setUTCMonth(end.getUTCMonth() + 1)
+    return { label: match[0], start: start.toISOString(), end: end.toISOString() }
+  })
+}

package/runtime/shared/dates.ts

@@ -0,0 +1,26 @@
+export function toDateKey(date: Date) {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`
+}
+
+export function toLocalDate(key: string) {
+  return new Date(`${key}T00:00:00`)
+}
+
+export function isValidDateKey(key: unknown): key is string {
+  return (
+    typeof key === 'string' &&
+    /^\d{4}-\d{2}-\d{2}$/.test(key) &&
+    Number.isFinite(toLocalDate(key).getTime()) &&
+    toDateKey(toLocalDate(key)) === key
+  )
+}
+
+export function addDays(date: Date, days: number) {
+  const next = new Date(date)
+  next.setDate(next.getDate() + days)
+  return next
+}
+
+export function getWeekStart(date: Date) {
+  return addDays(toLocalDate(toDateKey(date)), -((date.getDay() + 6) % 7))
+}

package/runtime/shared/model-search.ts

@@ -0,0 +1,45 @@
+import type { TableQuery } from '@cloudconfig/core/client'
+import type { ModelView } from './model-views'
+import type { FilterGroup, FilterNode } from '@cloudconfig/core'
+
+/** Apply text search only to the properties the UI explicitly enables. */
+export function withModelSearch<Key extends string>(
+  query: TableQuery<Key>,
+  view: ModelView,
+): TableQuery<Key> {
+  const wireKey = (key: string) =>
+    view.fields.find((field) => field.key === key)?.kind === 'relation' ? `${key}Id` : key
+  const wireFilter = (node: FilterNode): FilterNode =>
+    node.type === 'group'
+      ? { ...node, children: node.children.map(wireFilter) }
+      : { ...node, field: wireKey(node.field) }
+  const base = {
+    ...query,
+    sortBy: query.sortBy ? (wireKey(query.sortBy) as Key) : undefined,
+    filters: query.filters ? (wireFilter(query.filters) as FilterGroup) : undefined,
+  }
+  const search = query.search?.trim()
+  if (!search) {
+    return { ...base, search: undefined }
+  }
+  const filters: FilterGroup = {
+    type: 'group',
+    logic: 'and',
+    children: [
+      ...(base.filters ? [base.filters] : []),
+      {
+        type: 'group',
+        logic: 'or',
+        children: view.search.length
+          ? view.search.map((field) => ({
+              type: 'condition',
+              field: wireKey(field),
+              operator: 'like',
+              value: search,
+            }))
+          : [{ type: 'condition', field: 'id', operator: 'eq', value: -1 }],
+      },
+    ],
+  }
+  return { ...base, search: undefined, filters }
+}

package/runtime/shared/model-views.ts

@@ -0,0 +1,105 @@
+import { getFieldSpec, type AnyConfig, type FieldSpec, type InferSelect } from '@cloudconfig/core'
+
+export type ModelRow = { id: number; [key: string]: unknown }
+export type ModelField = FieldSpec & { key: string; label: string }
+
+export interface ModelView<Key extends string = string> {
+  id: string
+  model: string
+  label: string
+  icon: string
+  aliases: readonly string[]
+  fields: readonly ModelField[]
+  columns: readonly Key[]
+  search: readonly Key[]
+  filter: readonly Key[]
+  sort: readonly Key[]
+  actions: readonly ('create' | 'update' | 'delete')[]
+  selectionKey: string
+  /** Deterministic value semantics, separate from language interpretation. */
+  query?: {
+    nullAsFalse?: readonly Key[]
+    units?: Partial<Record<Key, 'bytes'>>
+  }
+  /** Optional domain vocabulary for schema-derived natural-language queries. */
+  prompt?: {
+    instructions?: string
+    fields?: Partial<Record<Key, string>>
+    /** Stored values mapped to domain vocabulary, e.g. admin: "administrator". */
+    values?: Partial<Record<Key, Record<string, string>>>
+    /** Override the global slot limit only where a model needs it. */
+    maxConstraints?: Partial<Record<Key, number>>
+  }
+}
+
+type ViewOptions<Key extends string> = Pick<
+  ModelView<Key>,
+  | 'id'
+  | 'label'
+  | 'icon'
+  | 'aliases'
+  | 'columns'
+  | 'search'
+  | 'filter'
+  | 'sort'
+  | 'actions'
+  | 'prompt'
+  | 'query'
+>
+
+/** Only public wire fields can be configured; types and controls come from CloudConfig. */
+export function defineModelView<
+  Backend extends AnyConfig,
+  Name extends keyof Backend['models'] & string,
+>(
+  backend: Backend,
+  name: Name,
+  options: ViewOptions<keyof InferSelect<Backend, Name> & string>,
+): ModelView {
+  const model = backend.models[name]
+  if (!model) {
+    throw new Error(`Model "${name}" is not registered in this schema.`)
+  }
+  const fields: ModelField[] = Object.entries(model.fields).flatMap(([key, field]) => {
+    const spec = getFieldSpec(field)
+    return spec.serverOnly ? [] : [{ ...spec, key, label: spec.label ?? fieldLabel(key) }]
+  })
+  fields.unshift({ ...baseField('number'), key: 'id', label: 'ID' })
+  if (model.options.timestamps !== false) {
+    fields.push(
+      { ...baseField('datetime'), key: 'createdAt', label: 'Created' },
+      { ...baseField('datetime'), key: 'updatedAt', label: 'Updated' },
+    )
+  }
+  return { ...options, model: name, fields, selectionKey: `${options.id}-record` }
+}
+
+function baseField(kind: FieldSpec['kind']): FieldSpec {
+  return { kind, required: false, unique: false, hasDefault: false }
+}
+
+function fieldLabel(key: string) {
+  const text = key.replace(/([a-z])([A-Z])/g, '$1 $2')
+  return text.charAt(0).toUpperCase() + text.slice(1)
+}
+
+export function getViewColumns(view: ModelView) {
+  const { columns, fields } = view
+  return columns.map((key) => ({
+    key,
+    label: fields.find((field) => field.key === key)!.label,
+  }))
+}
+
+export function formatModelValue(value: unknown): string {
+  if (value === null || value === undefined) {
+    return '—'
+  }
+  if (typeof value === 'boolean') {
+    return value ? 'Yes' : 'No'
+  }
+  if (typeof value === 'object') {
+    return JSON.stringify(value)
+  }
+  return String(value)
+}

package/runtime/shared/query/filters.ts

@@ -0,0 +1,190 @@
+import type { TableQuery } from '@cloudconfig/core/client'
+import type { FilterGroup, FilterNode, FilterOperator, FilterValue } from '@cloudconfig/core'
+import type { ModelView } from '../model-views'
+import type { Comparison, ResourceQuery, Where } from './types'
+import { toBooleanValue } from './values'
+
+/** Translate prompt queries to the same server filters used by CloudConfig tables. */
+export function toResourceTableQuery<Key extends string>(
+  query: ResourceQuery<Key>,
+  view: ModelView<Key>,
+): TableQuery<Key> {
+  function translate(node: Where<Key>, negate = false): FilterNode {
+    if (node.type === 'search') {
+      if (!view.search.length) {
+        throw new Error('Text search is not enabled for this model.')
+      }
+      return {
+        type: 'group',
+        logic: negate ? 'and' : 'or',
+        children: view.search.map((field) => ({
+          type: 'condition',
+          field,
+          operator: negate ? 'not_contains' : 'like',
+          value: node.value,
+        })),
+      }
+    }
+    if (node.type === 'group') {
+      return translate(node.expression, negate)
+    }
+    if (node.type === 'not') {
+      return translate(node.expression, !negate)
+    }
+    if (node.type === 'and' || node.type === 'or') {
+      // De Morgan: NOT (a AND b) is (NOT a) OR (NOT b), and the reverse.
+      const flippedLogic = node.type === 'and' ? 'or' : 'and'
+      const logic = negate ? flippedLogic : node.type
+      const children = [translate(node.left, negate), translate(node.right, negate)]
+      return {
+        type: 'group',
+        logic,
+        children: children.flatMap((child) =>
+          child.type === 'group' && child.logic === logic ? child.children : [child],
+        ),
+      }
+    }
+    const condition = (operator: FilterOperator, value: FilterValue): FilterNode => {
+      if (value === null && operator !== 'eq' && operator !== 'neq') {
+        throw new Error('Use IS NULL or IS NOT NULL to compare missing values.')
+      }
+      const field = view.fields.find((field) => field.key === node.column)
+      if (!view.filter.includes(node.column)) {
+        throw new Error(`Filtering ${node.column} is not enabled.`)
+      }
+      if (field?.kind === 'boolean' && value !== null) {
+        if (typeof value === 'number' || typeof value === 'string') {
+          value = toBooleanValue(value)
+        }
+        if (typeof value !== 'boolean' || !['eq', 'neq'].includes(operator)) {
+          throw new Error(
+            `${node.column} requires TRUE/FALSE, 1/0, YES/NO, ON/OFF, or NULL with = or !=.`,
+          )
+        }
+      }
+      if (
+        value !== null &&
+        field &&
+        ['number', 'float', 'relation'].includes(field.kind) &&
+        (typeof value !== 'number' || !Number.isFinite(value))
+      ) {
+        throw new Error(`${node.column} requires a number.`)
+      }
+      if (value !== null && field?.kind === 'select' && !field.options?.includes(String(value))) {
+        throw new Error(`Choose a configured option for ${node.column}.`)
+      }
+      if (value !== null && field && ['date', 'datetime'].includes(field.kind)) {
+        if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) {
+          throw new Error(`${node.column} requires a valid date.`)
+        }
+        value = field.kind === 'datetime' ? new Date(value).toISOString() : value.slice(0, 10)
+      }
+      if (
+        ['like', 'not_contains', 'starts_with', 'ends_with'].includes(operator) &&
+        field &&
+        !['text', 'textarea', 'email', 'url'].includes(field.kind)
+      ) {
+        throw new Error(`${node.column} does not support text matching.`)
+      }
+      return { type: 'condition', field: node.column, operator, value }
+    }
+    const negative = negate !== ('isNegated' in node && node.isNegated)
+    if (node.op === 'cmp') {
+      const operators: Record<Comparison, FilterOperator> = negate
+        ? {
+            '=': 'neq',
+            '!=': 'eq',
+            '>': 'lte',
+            '<': 'gte',
+            '>=': 'lt',
+            '<=': 'gt',
+          }
+        : {
+            '=': 'eq',
+            '!=': 'neq',
+            '>': 'gt',
+            '<': 'lt',
+            '>=': 'gte',
+            '<=': 'lte',
+          }
+      return condition(operators[node.comparison], node.value)
+    }
+    if (node.op === 'null') {
+      return condition(negative ? 'neq' : 'eq', null)
+    }
+    if (node.op === 'in') {
+      return {
+        type: 'group',
+        logic: negative ? 'and' : 'or',
+        children: node.list.map((value) => condition(negative ? 'neq' : 'eq', value)),
+      }
+    }
+    if (node.op === 'between') {
+      return {
+        type: 'group',
+        logic: negative ? 'or' : 'and',
+        children: [
+          condition(negative ? 'lt' : 'gte', node.low),
+          condition(negative ? 'gt' : 'lte', node.high),
+        ],
+      }
+    }
+    const pattern = node.value.includes('%') ? node.value : `%${node.value}%`
+    const leading = pattern.startsWith('%')
+    const trailing = pattern.endsWith('%')
+    if (negative && (!leading || !trailing)) {
+      throw new Error("NOT LIKE supports contains patterns such as '%text%'.")
+    }
+    if (!leading && !trailing) {
+      throw new Error("Use a LIKE pattern such as '%text%', 'text%', or '%text'.")
+    }
+    const value = pattern.slice(leading ? 1 : 0, trailing ? -1 : undefined)
+    return condition(likeOperator({ negative, leading, trailing }), value)
+  }
+  if (query.columns?.some((key) => !view.columns.includes(key))) {
+    throw new Error('One or more selected columns are not enabled.')
+  }
+  if (query.order && !view.sort.includes(query.order.column)) {
+    throw new Error(`Sorting ${query.order.column} is not enabled.`)
+  }
+  const filters: FilterGroup = {
+    type: 'group',
+    logic: 'and',
+    children: query.where ? [translate(query.where)] : [],
+  }
+  const defaultSort = view.sort.includes('createdAt' as Key) ? ('createdAt' as Key) : view.sort[0]
+  return {
+    page: 1,
+    pageSize: Math.max(1, Math.min(25, query.limit ?? 25)),
+    filters,
+    sortBy: query.order?.column ?? defaultSort,
+    sortDir: sortDirection(query.order?.direction, defaultSort === 'createdAt'),
+  }
+}
+
+/** Maps a LIKE pattern's wildcard positions to the closest filter operator. */
+function likeOperator({
+  negative,
+  leading,
+  trailing,
+}: {
+  negative: boolean
+  leading: boolean
+  trailing: boolean
+}) {
+  if (negative) {
+    return 'not_contains'
+  }
+  if (!leading) {
+    return 'starts_with'
+  }
+  return trailing ? 'like' : 'ends_with'
+}
+
+/** Newest first when sorting by creation date, otherwise ascending, unless the query says. */
+function sortDirection(direction: number | undefined, isCreatedAtSort: boolean) {
+  if (direction !== undefined) {
+    return direction === 1 ? 'asc' : 'desc'
+  }
+  return isCreatedAtSort ? 'desc' : 'asc'
+}

package/runtime/shared/query/sql.ts

@@ -0,0 +1,312 @@
+import type { ModelView } from '../model-views'
+import { findNamedMonthPeriods } from '../date-periods'
+import type { Comparison, ParseResult, ResourceQuery, Scalar, Where } from './types'
+import { toBooleanValue, createDatePeriodCondition } from './values'
+import { toResourceTableQuery } from './filters'
+
+const STOP = new Set(['and', 'or', 'order', 'sort', 'limit', 'not'])
+const COMPARISONS = ['=', '==', '!=', '<>', '>', '<', '>=', '<=']
+
+type Token = { type: 'str' | 'op' | 'word'; text: string }
+
+function toToken(match: RegExpExecArray): Token {
+  const [, quoted, singleQuoted, doubleQuoted, operator, word] = match
+  if (quoted) {
+    // SQL escapes a quote inside a string by doubling it.
+    const text = singleQuoted?.replaceAll("''", "'") ?? doubleQuoted!.replaceAll('""', '"')
+    return { type: 'str', text }
+  }
+  if (operator) {
+    return { type: 'op', text: operator }
+  }
+  return { type: 'word', text: word! }
+}
+
+const comparisonAliases: Record<string, Comparison> = { '==': '=', '<>': '!=' }
+
+function tokenize(source: string): Token[] {
+  const pattern =
+    /('((?:''|[^'])*)'|"((?:""|[^"])*)")|(>=|<=|!=|<>|==|=|>|<|\(|\)|,|\*)|([^\s'"()=<>!,]+)/y
+  const tokens: Token[] = []
+  let cursor = 0
+  while (cursor < source.length) {
+    if (/\s/.test(source[cursor]!)) {
+      cursor++
+      continue
+    }
+    pattern.lastIndex = cursor
+    const match = pattern.exec(source)
+    if (!match) {
+      throw new Error(`Unexpected "${source[cursor]}"`)
+    }
+    tokens.push(toToken(match))
+    cursor = pattern.lastIndex
+  }
+  return tokens
+}
+
+export function parseResourceSql<Key extends string>(
+  source: string,
+  view: ModelView<Key>,
+  aliases: Record<string, Key> = {},
+): ParseResult<Key> {
+  const columnsByName = Object.fromEntries(
+    view.fields.map((field) => [field.key.toLowerCase(), field.key]),
+  ) as Record<string, Key>
+  const resolveColumn = (token: Token | undefined): Key => {
+    const key =
+      token && (aliases[token.text.toLowerCase()] ?? columnsByName[token.text.toLowerCase()])
+    if (!key) {
+      throw new Error(token ? `Unknown column "${token.text}"` : 'Expected a column')
+    }
+    return key
+  }
+  const entities = new Set([view.id, view.model, ...view.aliases].map((name) => name.toLowerCase()))
+  let tokens: Token[]
+  try {
+    tokens = tokenize(source)
+  } catch (error) {
+    return { error: (error as Error).message }
+  }
+  const entityAt = tokens.findIndex(
+    (token) => token.type === 'word' && entities.has(token.text.toLowerCase()),
+  )
+  if (entityAt < 0) {
+    return { error: `Expected FROM ${view.id}` }
+  }
+
+  const keyword = (token: Token | undefined) =>
+    token?.type === 'word' ? token.text.toLowerCase() : null
+  let cursor = entityAt + 1
+  const peek = () => tokens[cursor]
+  const readToken = () => tokens[cursor++]
+  const isKeyword = (...words: string[]) => words.includes(keyword(peek()) ?? '')
+  const isOperator = (text: string) => peek()?.type === 'op' && peek()!.text === text
+
+  const readValue = (): Scalar => {
+    const token = readToken()
+    if (!token) {
+      throw new Error('Expected a value')
+    }
+    if (token.type === 'str') {
+      return token.text
+    }
+    if (token.type === 'op') {
+      throw new Error(`Unexpected "${token.text}"`)
+    }
+    const word = token.text.toLowerCase()
+    if (word === 'true') {
+      return true
+    }
+    if (word === 'false') {
+      return false
+    }
+    if (word === 'null') {
+      return null
+    }
+    if (!Number.isNaN(Number(token.text))) {
+      return Number(token.text)
+    }
+
+    let text = token.text
+    while (peek()?.type === 'word' && !STOP.has(keyword(peek())!)) {
+      text += ' ' + readToken()!.text
+    }
+    return text
+  }
+  const readFieldValue = (column: Key): Scalar => {
+    const parsed = readValue()
+    return view.fields.find((field) => field.key === column)?.kind === 'boolean'
+      ? toBooleanValue(parsed)
+      : parsed
+  }
+
+  const readCondition = (): Where<Key> => {
+    const token = readToken()
+    if (!token || token.type !== 'word') {
+      throw new Error(token ? `Unexpected "${token.text}"` : 'Expected a condition')
+    }
+    const column = resolveColumn(token)
+    let isNegated = false
+    const operator = peek()
+    if (!operator) {
+      throw new Error(`Expected an operator after ${token.text}`)
+    }
+    if (operator.type === 'op' && COMPARISONS.includes(operator.text)) {
+      readToken()
+      const comparison = comparisonAliases[operator.text] ?? (operator.text as Comparison)
+      const value = readFieldValue(column)
+      const kind = view.fields.find((field) => field.key === column)?.kind
+      if (typeof value === 'string' && (kind === 'date' || kind === 'datetime')) {
+        const period = findNamedMonthPeriods(value).find(
+          (period) => period.label.toLowerCase() === value.trim().toLowerCase(),
+        )
+        if (period) {
+          const boundary = (date: string) => (kind === 'date' ? date.slice(0, 10) : date)
+          return createDatePeriodCondition(
+            column,
+            comparison,
+            boundary(period.start),
+            boundary(period.end),
+          )
+        }
+      }
+      return { type: 'cond', column, op: 'cmp', comparison, value }
+    }
+    if (isKeyword('not')) {
+      readToken()
+      isNegated = true
+    }
+    if (isKeyword('like', 'ilike', 'contains')) {
+      const word = keyword(readToken())
+      const text = String(readValue())
+      return {
+        type: 'cond',
+        column,
+        op: 'like',
+        isNegated,
+        value: word === 'contains' ? `%${text}%` : text,
+      }
+    }
+    if (isKeyword('in')) {
+      readToken()
+      if (!isOperator('(')) {
+        throw new Error('Expected ( after IN')
+      }
+      readToken()
+      const list: Scalar[] = []
+      while (peek() && !isOperator(')')) {
+        if (isOperator(',')) {
+          readToken()
+          continue
+        }
+        list.push(readFieldValue(column))
+      }
+      if (!peek()) {
+        throw new Error('Missing )')
+      }
+      readToken()
+      if (!list.length) {
+        throw new Error('IN list is empty')
+      }
+      return { type: 'cond', column, op: 'in', isNegated, list }
+    }
+    if (isKeyword('between')) {
+      readToken()
+      const low = readValue()
+      if (!isKeyword('and')) {
+        throw new Error('Expected AND in BETWEEN')
+      }
+      readToken()
+      return { type: 'cond', column, op: 'between', isNegated, low, high: readValue() }
+    }
+    if (isKeyword('is')) {
+      readToken()
+      if (isKeyword('not')) {
+        readToken()
+        isNegated = true
+      }
+      if (!isKeyword('null')) {
+        throw new Error('Expected NULL after IS')
+      }
+      readToken()
+      return { type: 'cond', column, op: 'null', isNegated }
+    }
+    throw new Error(`Unknown operator "${peek()?.text ?? ''}"`)
+  }
+
+  const readUnary = (): Where<Key> => {
+    if (isKeyword('not')) {
+      readToken()
+      return { type: 'not', expression: readUnary() }
+    }
+    if (isOperator('(')) {
+      readToken()
+      const expression = readOr()
+      if (!isOperator(')')) {
+        throw new Error('Missing )')
+      }
+      readToken()
+      return { type: 'group', expression }
+    }
+    return readCondition()
+  }
+  const readAnd = (): Where<Key> => {
+    let left = readUnary()
+    while (isKeyword('and')) {
+      readToken()
+      left = { type: 'and', left, right: readUnary() }
+    }
+    return left
+  }
+  const readOr = (): Where<Key> => {
+    let left = readAnd()
+    while (isKeyword('or')) {
+      readToken()
+      left = { type: 'or', left, right: readAnd() }
+    }
+    return left
+  }
+
+  try {
+    let columns: Key[] | null = null
+    if (keyword(tokens[0]) === 'select') {
+      const segment = tokens.slice(1, entityAt)
+      if (keyword(segment.at(-1)) !== 'from') {
+        throw new Error(`Expected FROM before ${view.id}`)
+      }
+      const named = segment.slice(0, -1).filter((token) => token.text !== ',')
+      if (!named.length) {
+        throw new Error('Expected columns after SELECT')
+      }
+      if (!(named.length === 1 && named[0]!.text === '*')) {
+        columns = [...new Set(named.map(resolveColumn))]
+      }
+    } else if (entityAt > 0) {
+      throw new Error(`Start with SELECT or ${view.id}`)
+    }
+    if (isKeyword('where', 'with', 'whose', 'having')) {
+      readToken()
+    }
+    let where: Where<Key> | null = null
+    let order: ResourceQuery<Key>['order'] = null
+    let limit: number | null = null
+    if (peek() && !isKeyword('order', 'sort', 'limit')) {
+      where = readOr()
+    }
+    if (isKeyword('order', 'sort')) {
+      readToken()
+      if (isKeyword('by')) {
+        readToken()
+      }
+      const column = resolveColumn(readToken())
+      let direction: 1 | -1 = 1
+      if (isKeyword('asc')) {
+        readToken()
+      } else if (isKeyword('desc')) {
+        readToken()
+        direction = -1
+      }
+      order = { column, direction }
+    }
+    if (isKeyword('limit')) {
+      readToken()
+      const limitToken = readToken()
+      if (!limitToken || Number.isNaN(+limitToken.text)) {
+        throw new Error('Expected a number after LIMIT')
+      }
+      if (!Number.isFinite(+limitToken.text)) {
+        throw new Error('LIMIT requires a finite number.')
+      }
+      limit = Math.max(0, Math.floor(+limitToken.text))
+    }
+    if (peek()) {
+      throw new Error(`Unexpected "${peek()!.text}"`)
+    }
+    const query = { columns, where, order, limit }
+    toResourceTableQuery(query, view)
+    return { query }
+  } catch (error) {
+    return { error: (error as Error).message }
+  }
+}

package/runtime/shared/query/types.ts

@@ -0,0 +1,28 @@
+export interface ResourceQuery<Key extends string = string> {
+  columns: Key[] | null
+  where: Where<Key> | null
+  order: { column: Key; direction: 1 | -1 } | null
+  limit: number | null
+}
+
+export type Scalar = string | number | boolean | null
+export type Comparison = '=' | '!=' | '>' | '<' | '>=' | '<='
+
+export type Condition<Key extends string = string> = { type: 'cond'; column: Key } & (
+  | { op: 'cmp'; comparison: Comparison; value: Scalar }
+  | { op: 'like'; isNegated: boolean; value: string }
+  | { op: 'in'; isNegated: boolean; list: Scalar[] }
+  | { op: 'between'; isNegated: boolean; low: Scalar; high: Scalar }
+  | { op: 'null'; isNegated: boolean }
+)
+
+export type Where<Key extends string = string> =
+  | Condition<Key>
+  | { type: 'search'; value: string }
+  | { type: 'and'; left: Where<Key>; right: Where<Key> }
+  | { type: 'or'; left: Where<Key>; right: Where<Key> }
+  | { type: 'not'; expression: Where<Key> }
+  | { type: 'group'; expression: Where<Key> }
+
+export type ParseResult<Key extends string = string> =
+  { query: ResourceQuery<Key> } | { error: string }

package/runtime/shared/query/values.ts

@@ -0,0 +1,41 @@
+import type { Comparison, Condition, Scalar, Where } from './types'
+
+export function toBooleanValue(value: Scalar): Scalar {
+  if (value === 0 || value === 1) {
+    return value === 1
+  }
+  if (typeof value === 'string' && /^(true|false|yes|no|on|off|1|0)$/i.test(value)) {
+    return /^(true|yes|on|1)$/i.test(value)
+  }
+  return value
+}
+
+/** Compare whole date periods using an inclusive start and exclusive end. */
+export function createDatePeriodCondition<Key extends string>(
+  column: Key,
+  comparison: Comparison,
+  start: string,
+  end: string,
+): Where<Key> {
+  const compare = (comparison: Comparison, value: string): Condition<Key> => ({
+    type: 'cond',
+    column,
+    op: 'cmp',
+    comparison,
+    value,
+  })
+  switch (comparison) {
+    case '=':
+      return { type: 'and', left: compare('>=', start), right: compare('<', end) }
+    case '!=':
+      return { type: 'or', left: compare('<', start), right: compare('>=', end) }
+    case '>':
+      return compare('>=', end)
+    case '>=':
+      return compare('>=', start)
+    case '<':
+      return compare('<', start)
+    case '<=':
+      return compare('<', end)
+  }
+}

package/runtime/shared/resource-query.ts

@@ -0,0 +1,11 @@
+export type {
+  ResourceQuery,
+  Scalar,
+  Comparison,
+  Condition,
+  Where,
+  ParseResult,
+} from './query/types'
+export { createDatePeriodCondition } from './query/values'
+export { parseResourceSql } from './query/sql'
+export { toResourceTableQuery } from './query/filters'

package/runtime/shared/table-query.ts

@@ -0,0 +1,26 @@
+import type { PagedResult, TableQuery } from '@cloudconfig/core/client'
+
+export function createEmptyPage<Row>(query: TableQuery = {}): PagedResult<Row> {
+  return {
+    data: [],
+    totalCount: 0,
+    totalPages: 1,
+    page: query.page ?? 1,
+    pageSize: query.pageSize ?? 25,
+  }
+}
+
+export function limitPage<Row>(result: PagedResult<Row>, limit: number | null): PagedResult<Row> {
+  if (limit === null) {
+    return result
+  }
+
+  const totalCount = Math.min(result.totalCount, limit)
+  const offset = (result.page - 1) * result.pageSize
+  return {
+    ...result,
+    totalCount,
+    totalPages: Math.max(1, Math.ceil(totalCount / result.pageSize)),
+    data: result.data.slice(0, Math.max(0, limit - offset)),
+  }
+}

package/runtime/shared/upload-limits.ts

@@ -0,0 +1,3 @@
+export const UPLOAD_LIMIT_MB = 100
+export const UPLOAD_LIMIT_BYTES = UPLOAD_LIMIT_MB * 1024 * 1024
+export const IMAGE_PIXEL_LIMIT = 64_000_000