zeed 1.4.0 → 1.5.0

package/src/common/schema/export-json-schema.ts

@@ -1,72 +1,79 @@
 import type { Type } from './schema'
 import { isEmpty } from '../data'
-import { objectMap } from '../data/object'
 
-const _mapJsonSchemaType: Record<string, string> = {
+const _primitiveMap: Record<string, string> = {
   string: 'string',
   number: 'number',
-  boolean: 'boolean',
   int: 'integer',
+  boolean: 'boolean',
 }
 
-export function schemaExportJsonSchema<T>(schema: Type<T>): Record<string, any> {
-  // assert(isSchemaObjectFlat(schema), 'schema should be a flat object')
+function transformSchema(schema: Type<any>): Record<string, any> {
+  const out: Record<string, any> = {}
 
-  function transformSchema(schema: Type<any>): any {
-    const type = _mapJsonSchemaType[schema.type] ?? schema.type ?? 'object'
+  if (schema._enumValues) {
+    out.type = _primitiveMap[schema.type] ?? schema.type
+    out.enum = [...schema._enumValues]
+  }
+  else if (schema.type === 'literal') {
+    out.const = schema._default
+  }
+  else if (schema.type === 'union' && Array.isArray(schema._union)) {
+    out.anyOf = schema._union.map((s: Type<any>) => transformSchema(s))
+  }
+  else if (schema.type === 'object' && schema._object) {
+    out.type = 'object'
     const properties: Record<string, any> = {}
     const required: string[] = []
-
-    objectMap(schema._object!, (key, schema: any) => {
-      const type = _mapJsonSchemaType[schema.type] ?? schema.type
-      properties[key] = { type }
-      const enumValues = (schema as any)._enumValues
-      if (enumValues) {
-        properties[key].enum = enumValues
-      }
-      if (schema._default !== undefined) {
-        properties[key].default = schema._default
-      }
-      if (schema._meta?.desc) {
-        properties[key].description = schema._meta.desc
-      }
-      if (schema._optional !== true) {
+    for (const key of Object.keys(schema._object)) {
+      const propSchema = schema._object[key] as Type<any>
+      properties[key] = transformSchema(propSchema)
+      if (propSchema._optional !== true)
         required.push(key)
-      }
-      if (schema.type === 'array' && schema._type) {
-        properties[key].items = transformSchema(schema._type)
-      }
-      else if (schema.type === 'object' && schema._object) {
-        Object.assign(properties[key], transformSchema(schema))
-        properties[key].additionalProperties = false
-      }
-      else if (schema.type === 'record' && schema._type) {
-        properties[key].type = 'object'
-        properties[key].additionalProperties = transformSchema(schema._type)
-      }
-      // Handle union types (e.g., z.union)
-      else if (schema.type === 'union' && Array.isArray(schema._union)) {
-        properties[key].type = schema._union.map((s: any) => _mapJsonSchemaType[s.type] ?? s.type) // todo complex types
-      }
-    })
-
-    if (!isEmpty(properties)) {
-      return {
-        type,
-        properties,
-        additionalProperties: false,
-        ...(required.length > 0 ? { required } : {}),
-      }
-    }
-
-    return {
-      type,
     }
+    if (!isEmpty(properties))
+      out.properties = properties
+    out.additionalProperties = false
+    if (required.length > 0)
+      out.required = required
   }
+  else if (schema.type === 'record' && schema._type) {
+    out.type = 'object'
+    out.additionalProperties = transformSchema(schema._type)
+  }
+  else if (schema.type === 'array' && schema._type) {
+    out.type = 'array'
+    out.items = transformSchema(schema._type)
+  }
+  else if (schema.type === 'tuple' && Array.isArray(schema._type)) {
+    out.type = 'array'
+    out.items = (schema._type as Type<any>[]).map(s => transformSchema(s))
+    out.minItems = schema._type.length
+    out.maxItems = schema._type.length
+  }
+  else if (schema.type === 'none') {
+    out.type = 'null'
+  }
+  else if (schema.type === 'any') {
+    // no constraint
+  }
+  else {
+    const t = _primitiveMap[schema.type]
+    if (t)
+      out.type = t
+  }
+
+  if (schema._default !== undefined && schema.type !== 'literal')
+    out.default = schema._default
+  if (schema._meta?.desc)
+    out.description = schema._meta.desc
 
+  return out
+}
+
+export function schemaExportJsonSchema<T>(schema: Type<T>): Record<string, any> {
   return {
     $schema: 'http://json-schema.org/draft-07/schema#',
-    additionalProperties: false,
     ...transformSchema(schema),
   }
 }

package/src/common/schema/index.ts

@@ -7,6 +7,7 @@ export * from './parse-object'
 export * from './schema'
 export * from './schema-standard'
 export * from './serialize'
+export * from './sql'
 export * from './type-test'
 export * from './utils'
 export * from './z'

package/src/common/schema/sql/README.md

@@ -0,0 +1,254 @@
+# SQL Select Builder
+
+A minimal, type-safe SQL `SELECT` builder built on top of zeed's `z` schema system. Inspired by Drizzle ORM and Kysely, but deliberately small: single-table queries, no joins, no inserts/updates/deletes.
+
+The goal is to get full TypeScript inference, editor autocompletion, and - uniquely - per-query dependency tracking for reactive use cases.
+
+## Features
+
+- Type-safe table definitions backed by `z` schemas
+- Full row type inference for results, including narrowed `pick`/`select` forms
+- Editor autocompletion on column keys
+- Parameterized SQL output (`?` placeholders, values returned separately)
+- Per-query dependency tracking split by role: `select`, `where`, `orderBy`
+- Zero runtime dependencies, tree-shakable
+
+## Quick Start
+
+```ts
+import { and, boolean, eq, from, gt, inArray, int, like, or, string, table } from 'zeed'
+
+const users = table('users', {
+  id: int(),
+  name: string(),
+  email: string(),
+  age: int(),
+  active: boolean(),
+})
+
+const query = from(users)
+  .pick('id', 'name')
+  .where(and(eq(users.active, true), gt(users.age, 18)))
+  .orderBy(users.name)
+  .limit(20)
+
+const { sql, params } = query.toSQL()
+// sql:    SELECT "users"."id", "users"."name" FROM "users"
+//         WHERE ("users"."active" = ?) AND ("users"."age" > ?)
+//         ORDER BY "users"."name" ASC LIMIT ?
+// params: [true, 18, 20]
+```
+
+## Defining Tables
+
+A table pairs a name with a `z`-schema shape. Each column becomes a typed reference usable in expressions.
+
+```ts
+const posts = table('posts', {
+  id: int(),
+  title: string(),
+  body: string(),
+  authorId: int(),
+  published: boolean(),
+})
+
+posts.id // Column<number>
+posts.title // Column<string>
+```
+
+The shape is a plain `Record<string, Type>`, so any `z` type works (`string`, `int`, `boolean`, `stringLiterals`, ...).
+
+## Selecting Columns
+
+Three forms, depending on how much control you need.
+
+### 1. Full row (default)
+
+```ts
+from(users)
+// Row: { id: number, name: string, email: string, age: number, active: boolean }
+```
+
+### 2. `pick(...keys)` - compact and typed
+
+```ts
+from(users).pick('id', 'email')
+// Row: { id: number, email: string }
+```
+
+Keys are typed against the table shape, so the editor autocompletes valid column names and rejects unknown ones at compile time.
+
+### 3. `select({ alias: column })` - for aliases or mixed expressions
+
+```ts
+import { select } from 'zeed'
+
+select({ uid: users.id, n: users.name }).from(users)
+// Row: { uid: number, n: string }
+// SQL: SELECT "users"."id" AS "uid", "users"."name" AS "n" FROM "users"
+```
+
+## Where Clauses
+
+Expressions are built from operator helpers. Columns and literal values can be mixed freely - literals are automatically bound as parameters.
+
+```ts
+import { and, eq, gt, gte, inArray, like, lt, ne, or, sqlIsNotNull, sqlIsNull } from 'zeed'
+
+from(users).where(
+  and(
+    eq(users.active, true),
+    or(
+      like(users.name, 'A%'),
+      inArray(users.id, [1, 2, 3]),
+    ),
+    sqlIsNotNull(users.email),
+  ),
+)
+```
+
+Available operators:
+
+| Helper          | SQL          |
+| --------------- | ------------ |
+| `eq(a, b)`      | `a = b`      |
+| `ne(a, b)`      | `a <> b`     |
+| `gt(a, b)`      | `a > b`      |
+| `gte(a, b)`     | `a >= b`     |
+| `lt(a, b)`      | `a < b`      |
+| `lte(a, b)`     | `a <= b`     |
+| `like(a, b)`    | `a LIKE b`   |
+| `inArray(a, [])`| `a IN (...)` |
+| `sqlIsNull(a)`  | `a IS NULL`  |
+| `sqlIsNotNull(a)` | `a IS NOT NULL` |
+| `and(...)`      | `(..) AND (..)` |
+| `or(...)`       | `(..) OR (..)`  |
+| `not(e)`        | `NOT (..)`   |
+
+`and` and `or` accept `undefined`, `false`, and `null` entries and drop them, which is handy for conditional filters.
+
+Note: `sqlIsNull` and `sqlIsNotNull` are prefixed to avoid collision with zeed's existing `isNull`/`isNotNull` data helpers.
+
+## Ordering, Limit, Offset
+
+```ts
+from(users)
+  .orderBy(users.age, 'DESC')
+  .orderBy(users.name) // ASC by default
+  .limit(10)
+  .offset(20)
+```
+
+## Compiling a Query
+
+```ts
+const { sql, params, dependencies } = query.toSQL()
+```
+
+- `sql` - the query string with `?` placeholders
+- `params` - array of bound values in order
+- `dependencies` - see below
+
+Pass `sql` and `params` to whichever SQLite/Postgres/MySQL driver you use.
+
+## Dependency Tracking
+
+Every compiled query reports exactly which table columns it touches, split by role. This is the key building block for reactive queries: when the database changes, you can decide whether a given query needs to re-run based on which columns were affected.
+
+```ts
+const q = from(users)
+  .pick('id', 'name')
+  .where(eq(users.email, 'a@b.c'))
+  .orderBy(users.age, 'DESC')
+
+q.toSQL().dependencies
+// [
+//   {
+//     table: 'users',
+//     select:  ['id', 'name'],  // fields returned to the caller
+//     where:   ['email'],       // fields used in filters
+//     orderBy: ['age'],         // fields used for ordering
+//     all:     ['age', 'email', 'id', 'name'], // union of the above
+//   }
+// ]
+```
+
+### Example: reactive invalidation
+
+```ts
+function isAffected(
+  deps: readonly QueryDependencies[],
+  change: { table: string, columns: string[] },
+): boolean {
+  return deps.some(d =>
+    d.table === change.table
+    && d.all.some(c => change.columns.includes(c)),
+  )
+}
+
+// On a write notification from the database:
+if (isAffected(query.toSQL().dependencies, { table: 'users', columns: ['email'] })) {
+  // re-run the query, push new rows to subscribers
+}
+```
+
+Splitting by role lets you optimize further:
+
+- A change to a `select` column means the result *shape* changes - re-render.
+- A change to a `where` or `orderBy` column means the result *set* may change - re-query.
+- A change to a column not in `all` is irrelevant - skip.
+
+## Type Inference
+
+Row types flow through the builder. Use `InferRow` to extract the result type for downstream code:
+
+```ts
+import type { InferRow } from 'zeed'
+
+const query = from(users).pick('id', 'email')
+type Row = InferRow<typeof query> // { id: number, email: string }
+
+function render(rows: Row[]) { /* ... */ }
+render(await run(query))
+```
+
+## Scope and Limitations
+
+By design, this builder is minimal:
+
+- `SELECT` only. No `INSERT`, `UPDATE`, `DELETE`, `CREATE TABLE`.
+- Single table per query. No `JOIN`, no subqueries, no CTEs.
+- No aggregate functions (`COUNT`, `SUM`, `GROUP BY`, `HAVING`).
+- One SQL dialect (`?` placeholders, double-quoted identifiers). Works with SQLite and, with most drivers, Postgres.
+
+The existing `select({...}).from(...)` form remains available for cases that need column aliases. If you need joins or mutations, use a dedicated ORM - this module is intended for read-only queries in reactive contexts where dependency tracking is the main value-add.
+
+## API Reference
+
+### `table(name, shape)`
+
+Creates a table handle. `shape` is a `Record<string, Type>` from `z`. Returns an object where each key is a typed `Column` plus `_name` and `_shape` metadata.
+
+### `from(table)`
+
+Starts a query. Returns a `SelectBuilder` with the full row type as its default result.
+
+### `select(selection?)`
+
+Alternative entry point. With no argument, behaves like a full-row select (requires a subsequent `.from(...)`). With a `{ alias: column }` map, creates an aliased selection.
+
+### `SelectBuilder`
+
+Chainable methods:
+
+- `.from(table)` - set the source table (only needed after `select()`)
+- `.pick(...keys)` - narrow to specific columns by name
+- `.where(expr)` - set the WHERE clause
+- `.orderBy(column, 'ASC' | 'DESC')` - append an ORDER BY entry
+- `.limit(n)` / `.offset(n)`
+- `.toSQL()` - compile to `{ sql, params, dependencies }`
+- `.dependencies()` - shortcut that returns just the dependencies
+
+### `InferRow<Query>`
+
+Type helper that extracts the row type from a builder or compiled query.

package/src/common/schema/sql/expr.ts

@@ -0,0 +1,99 @@
+import type { Column } from './table'
+import { isColumn } from './table'
+
+export interface Expr {
+  readonly kind: 'expr'
+  readonly sql: string
+  readonly params: unknown[]
+  readonly refs: Column[]
+}
+
+function operand(v: any): Expr {
+  if (isColumn(v)) {
+    return {
+      kind: 'expr',
+      sql: `"${v._table}"."${v._name}"`,
+      params: [],
+      refs: [v],
+    }
+  }
+  if (v && v.kind === 'expr')
+    return v as Expr
+  return { kind: 'expr', sql: '?', params: [v], refs: [] }
+}
+
+function binop(op: string) {
+  return (a: Column | Expr | unknown, b: Column | Expr | unknown): Expr => {
+    const x = operand(a)
+    const y = operand(b)
+    return {
+      kind: 'expr',
+      sql: `${x.sql} ${op} ${y.sql}`,
+      params: [...x.params, ...y.params],
+      refs: [...x.refs, ...y.refs],
+    }
+  }
+}
+
+export const eq = binop('=')
+export const ne = binop('<>')
+export const gt = binop('>')
+export const gte = binop('>=')
+export const lt = binop('<')
+export const lte = binop('<=')
+export const like = binop('LIKE')
+
+export function and(...parts: (Expr | undefined | false | null)[]): Expr {
+  const list = parts.filter((p): p is Expr => !!p)
+  if (list.length === 0)
+    return { kind: 'expr', sql: '1=1', params: [], refs: [] }
+  if (list.length === 1)
+    return list[0]
+  return {
+    kind: 'expr',
+    sql: list.map(p => `(${p.sql})`).join(' AND '),
+    params: list.flatMap(p => p.params),
+    refs: list.flatMap(p => p.refs),
+  }
+}
+
+export function or(...parts: (Expr | undefined | false | null)[]): Expr {
+  const list = parts.filter((p): p is Expr => !!p)
+  if (list.length === 0)
+    return { kind: 'expr', sql: '1=0', params: [], refs: [] }
+  if (list.length === 1)
+    return list[0]
+  return {
+    kind: 'expr',
+    sql: list.map(p => `(${p.sql})`).join(' OR '),
+    params: list.flatMap(p => p.params),
+    refs: list.flatMap(p => p.refs),
+  }
+}
+
+export function not(e: Expr): Expr {
+  return { kind: 'expr', sql: `NOT (${e.sql})`, params: e.params, refs: e.refs }
+}
+
+export function sqlIsNull(col: Column | Expr): Expr {
+  const x = operand(col)
+  return { kind: 'expr', sql: `${x.sql} IS NULL`, params: x.params, refs: x.refs }
+}
+
+export function sqlIsNotNull(col: Column | Expr): Expr {
+  const x = operand(col)
+  return { kind: 'expr', sql: `${x.sql} IS NOT NULL`, params: x.params, refs: x.refs }
+}
+
+export function inArray(col: Column | Expr, values: unknown[]): Expr {
+  const x = operand(col)
+  if (values.length === 0)
+    return { kind: 'expr', sql: '1=0', params: [], refs: x.refs }
+  const placeholders = values.map(() => '?').join(', ')
+  return {
+    kind: 'expr',
+    sql: `${x.sql} IN (${placeholders})`,
+    params: [...x.params, ...values],
+    refs: x.refs,
+  }
+}

package/src/common/schema/sql/index.ts

@@ -0,0 +1,3 @@
+export * from './expr'
+export * from './select'
+export * from './table'

package/src/common/schema/sql/select.spec.ts

@@ -0,0 +1,144 @@
+import type { Expect, IsEqual } from '../type-test'
+import type { InferRow } from './select'
+import { boolean, int, string } from '../schema'
+import { and, eq, gt, inArray, like, or } from './expr'
+import { from, select } from './select'
+import { table } from './table'
+
+const users = table('users', {
+  id: int(),
+  name: string(),
+  email: string(),
+  age: int(),
+  active: boolean(),
+})
+
+describe('sql select', () => {
+  it('selects all columns of a table', () => {
+    const q = select().from(users).toSQL()
+    expect(q.sql).toBe(
+      'SELECT "users"."id", "users"."name", "users"."email", "users"."age", "users"."active" FROM "users"',
+    )
+    expect(q.params).toEqual([])
+    expect(q.dependencies).toEqual([
+      {
+        table: 'users',
+        select: ['active', 'age', 'email', 'id', 'name'],
+        where: [],
+        orderBy: [],
+        all: ['active', 'age', 'email', 'id', 'name'],
+      },
+    ])
+  })
+
+  it('selects specific columns with type inference', () => {
+    const q = select({ id: users.id, name: users.name }).from(users)
+    type Row = InferRow<typeof q>
+    type _T = Expect<IsEqual<Row, { id: number, name: string }>>
+
+    const c = q.toSQL()
+    expect(c.sql).toBe('SELECT "users"."id", "users"."name" FROM "users"')
+    expect(c.dependencies).toEqual([
+      {
+        table: 'users',
+        select: ['id', 'name'],
+        where: [],
+        orderBy: [],
+        all: ['id', 'name'],
+      },
+    ])
+  })
+
+  it('from() + pick() is a compact form with typed keys', () => {
+    const q = from(users).pick('id', 'name').where(eq(users.email, 'x'))
+    type Row = InferRow<typeof q>
+    type _T = Expect<IsEqual<Row, { id: number, name: string }>>
+
+    const c = q.toSQL()
+    expect(c.sql).toBe(
+      'SELECT "users"."id", "users"."name" FROM "users" WHERE "users"."email" = ?',
+    )
+    expect(c.params).toEqual(['x'])
+    expect(c.dependencies[0].select).toEqual(['id', 'name'])
+    expect(c.dependencies[0].where).toEqual(['email'])
+  })
+
+  it('from() without pick returns the full row', () => {
+    const q = from(users)
+    type Row = InferRow<typeof q>
+    type _T = Expect<IsEqual<Row, {
+      id: number
+      name: string
+      email: string
+      age: number
+      active: boolean
+    }>>
+    expect(q.toSQL().sql).toBe(
+      'SELECT "users"."id", "users"."name", "users"."email", "users"."age", "users"."active" FROM "users"',
+    )
+  })
+
+  it('supports aliases in selection', () => {
+    const q = select({ uid: users.id }).from(users).toSQL()
+    expect(q.sql).toBe('SELECT "users"."id" AS "uid" FROM "users"')
+  })
+
+  it('builds where with parameters', () => {
+    const q = select()
+      .from(users)
+      .where(and(eq(users.active, true), gt(users.age, 18)))
+      .toSQL()
+    expect(q.sql).toContain('WHERE ("users"."active" = ?) AND ("users"."age" > ?)')
+    expect(q.params).toEqual([true, 18])
+  })
+
+  it('separates select, where and orderBy dependencies', () => {
+    const q = select({ id: users.id })
+      .from(users)
+      .where(eq(users.email, 'a@b.c'))
+      .orderBy(users.age, 'DESC')
+      .toSQL()
+    const dep = q.dependencies[0]
+    expect(dep.table).toBe('users')
+    expect(dep.select).toEqual(['id'])
+    expect(dep.where).toEqual(['email'])
+    expect(dep.orderBy).toEqual(['age'])
+    expect(dep.all).toEqual(['age', 'email', 'id'])
+  })
+
+  it('supports or, like, inArray', () => {
+    const q = select()
+      .from(users)
+      .where(or(like(users.name, 'A%'), inArray(users.id, [1, 2, 3])))
+      .toSQL()
+    expect(q.sql).toContain('WHERE ("users"."name" LIKE ?) OR ("users"."id" IN (?, ?, ?))')
+    expect(q.params).toEqual(['A%', 1, 2, 3])
+  })
+
+  it('handles orderBy, limit, offset and tracks orderBy deps', () => {
+    const q = select({ id: users.id })
+      .from(users)
+      .orderBy(users.age, 'DESC')
+      .limit(10)
+      .offset(20)
+      .toSQL()
+    expect(q.sql).toBe(
+      'SELECT "users"."id" FROM "users" ORDER BY "users"."age" DESC LIMIT ? OFFSET ?',
+    )
+    expect(q.params).toEqual([10, 20])
+    expect(q.dependencies[0].select).toEqual(['id'])
+    expect(q.dependencies[0].orderBy).toEqual(['age'])
+    expect(q.dependencies[0].all).toEqual(['age', 'id'])
+  })
+
+  it('dependencies() invalidation check helper', () => {
+    const q = select({ id: users.id }).from(users).where(eq(users.email, 'x'))
+    const deps = q.dependencies()
+    const changedTable = 'users'
+    const changedColumns = ['email']
+    const affected = deps.some(d =>
+      d.table === changedTable && d.all.some(c => changedColumns.includes(c)),
+    )
+    expect(affected).toBe(true)
+  })
+})