@pikku/kysely 0.13.24 → 0.13.28

package/src/classification-plugin.ts

@@ -1,249 +0,0 @@
-import type { KyselyPlugin, RootOperationNode, UnknownRow } from 'kysely'
-import type {
-  ClassificationManifest,
-  ColumnForm,
-} from '@pikku/core/classification'
-import {
-  DEFAULT_KEY_ID,
-  isColumnEnvelope,
-  type ClassificationCrypto,
-} from './classification-crypto.js'
-
-/** What the manifest says about one column, reduced to what the query path needs. */
-interface EncryptedColumn {
-  form: Extract<ColumnForm, 'wrapped' | 'sealed'>
-  keyId: string
-}
-
-interface ResolvedManifest {
-  /** `table.column` → column, for the exact per-query resolution. */
-  qualified: Map<string, EncryptedColumn>
-  /** `column` → column, the fallback for when the query's tables say nothing. */
-  flat: Map<string, EncryptedColumn>
-}
-
-function snakeToCamel(name: string): string {
-  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase())
-}
-
-/**
- * Flatten the manifest into a table-qualified lookup plus a bare column-name
- * fallback, both indexed under snake_case and camelCase so the plugin works on
- * either side of `CamelCasePlugin` in the array.
- *
- * A bare name two tables disagree about is dropped rather than letting the last
- * one win: on a joined query it could carry either, and guessing wrong means
- * either handing back ciphertext or refusing a legitimate write. The qualified
- * map still resolves it whenever the query names its tables.
- */
-function buildManifest(manifest: ClassificationManifest): ResolvedManifest {
-  const qualified = new Map<string, EncryptedColumn>()
-  const flat = new Map<string, EncryptedColumn>()
-  const ambiguous = new Set<string>()
-
-  const assignFlat = (key: string, column: EncryptedColumn) => {
-    const existing = flat.get(key)
-    if (existing && existing.keyId !== column.keyId) {
-      ambiguous.add(key)
-      return
-    }
-    flat.set(key, column)
-  }
-
-  for (const [table, columns] of Object.entries(manifest.tables)) {
-    for (const [name, classification] of Object.entries(columns)) {
-      const form = classification.form
-      if (form !== 'wrapped' && form !== 'sealed') continue
-
-      const column: EncryptedColumn = {
-        form,
-        keyId: classification.keyId ?? DEFAULT_KEY_ID,
-      }
-      const camel = snakeToCamel(name)
-      qualified.set(`${table}.${name}`, column)
-      qualified.set(`${table}.${camel}`, column)
-      assignFlat(name, column)
-      assignFlat(camel, column)
-    }
-  }
-
-  for (const key of ambiguous) flat.delete(key)
-  return { qualified, flat }
-}
-
-function collectQueryTables(node: unknown, out: Set<string>): void {
-  if (!node || typeof node !== 'object') return
-
-  const op = node as {
-    kind?: string
-    table?: { identifier?: { name?: string } }
-  }
-  if (op.kind === 'TableNode') {
-    const name = op.table?.identifier?.name
-    if (typeof name === 'string' && name.length > 0) out.add(name)
-  }
-
-  for (const value of Object.values(node)) {
-    if (Array.isArray(value)) {
-      for (const item of value) collectQueryTables(item, out)
-    } else {
-      collectQueryTables(value, out)
-    }
-  }
-}
-
-function lookupColumn(
-  manifest: ResolvedManifest,
-  tables: readonly string[],
-  column: string
-): EncryptedColumn | undefined {
-  let matched: EncryptedColumn | undefined
-  for (const table of tables) {
-    const found = manifest.qualified.get(`${table}.${column}`)
-    if (!found) continue
-    if (matched && matched.keyId !== found.keyId) {
-      return manifest.flat.get(column)
-    }
-    matched = found
-  }
-  return matched ?? manifest.flat.get(column)
-}
-
-/**
- * The column names an insert or update writes, paired with the values going
- * into them.
- *
- * Only literal values are collected. A raw expression or a sub-select is
- * something this plugin cannot read and must not guess at, so it is skipped —
- * the guard's job is to catch a plaintext string a call site forgot to encrypt,
- * not to prove every write correct.
- */
-function collectWrittenValues(node: unknown): Array<[string, unknown]> {
-  const written: Array<[string, unknown]> = []
-
-  const visit = (current: unknown): void => {
-    if (!current || typeof current !== 'object') return
-    const op = current as {
-      kind?: string
-      column?: { column?: { name?: string } }
-      value?: { kind?: string; value?: unknown }
-      columns?: Array<{ column?: { name?: string } }>
-      values?: unknown
-    }
-
-    if (op.kind === 'ColumnUpdateNode') {
-      const name = op.column?.column?.name
-      if (typeof name === 'string' && op.value?.kind === 'ValueNode') {
-        written.push([name, op.value.value])
-      }
-    }
-
-    if (op.kind === 'InsertQueryNode' && Array.isArray(op.columns)) {
-      const names = op.columns.map((c) => c.column?.name)
-      const rows = (op.values as { kind?: string; values?: unknown[] })?.values
-      if (Array.isArray(rows)) {
-        for (const row of rows) {
-          const list = (row as { kind?: string; values?: unknown[] })?.values
-          if (!Array.isArray(list)) continue
-          list.forEach((value, index) => {
-            const name = names[index]
-            if (typeof name !== 'string') return
-            const unwrapped =
-              value && typeof value === 'object' && 'kind' in value
-                ? (value as { kind?: string; value?: unknown }).kind ===
-                  'ValueNode'
-                  ? (value as { value?: unknown }).value
-                  : undefined
-                : value
-            if (unwrapped !== undefined) written.push([name, unwrapped])
-          })
-        }
-      }
-    }
-
-    for (const value of Object.values(current)) {
-      if (Array.isArray(value)) {
-        for (const item of value) visit(item)
-      } else {
-        visit(value)
-      }
-    }
-  }
-
-  visit(node)
-  return written
-}
-
-export interface CreateClassificationPluginOptions {
-  manifest: ClassificationManifest
-  crypto: ClassificationCrypto
-}
-
-/**
- * Make a column's at-rest form a property of the column rather than of the
- * developer's memory.
- *
- * Reads are transparent: a `wrapped` column comes back decrypted, so
- * application code never sees an envelope. `hashed` and `plain` columns are
- * untouched, which is what keeps the rest of the schema queryable.
- *
- * Writes are *guarded* rather than transformed, and the reason is Kysely's
- * shape, not a preference: `transformQuery` is synchronous and WebCrypto is
- * not, so a plugin cannot encrypt on the way in. Encrypting at the call site
- * and letting a forgotten call slip through silently is the failure this
- * design exists to prevent, so the guard refuses any plaintext heading for a
- * `wrapped` or `sealed` column. Values are produced with
- * `ClassificationCrypto.encryptColumn`.
- *
- * A `sealed` column is never decrypted on the way out — the application holds
- * only the public half by definition, so returning it as stored is correct
- * rather than a gap.
- */
-export function createClassificationPlugin(
-  options: CreateClassificationPluginOptions
-): KyselyPlugin {
-  const manifest = buildManifest(options.manifest)
-  const queryTables = new WeakMap<object, readonly string[]>()
-
-  return {
-    transformQuery(args) {
-      const tables = new Set<string>()
-      collectQueryTables(args.node as RootOperationNode, tables)
-      queryTables.set(args.queryId, [...tables])
-
-      for (const [name, value] of collectWrittenValues(args.node)) {
-        if (value === null || value === undefined) continue
-        const column = lookupColumn(manifest, [...tables], name)
-        if (!column) continue
-        if (!isColumnEnvelope(value)) {
-          throw new Error(
-            `Refusing to write plaintext into "${name}", which is classified ${column.form}. ` +
-              `Produce the value with ClassificationCrypto.encryptColumn() before writing it.`
-          )
-        }
-      }
-
-      return args.node
-    },
-
-    async transformResult(args) {
-      const tables = queryTables.get(args.queryId) ?? []
-      const rows: UnknownRow[] = []
-
-      for (const row of args.result.rows as UnknownRow[]) {
-        let next: UnknownRow | undefined
-        for (const [name, value] of Object.entries(row)) {
-          if (value === null || value === undefined) continue
-          const column = lookupColumn(manifest, tables, name)
-          if (!column || column.form !== 'wrapped') continue
-          if (!isColumnEnvelope(value)) continue
-          next ??= { ...row }
-          next[name] = await options.crypto.decryptColumn(value)
-        }
-        rows.push(next ?? row)
-      }
-
-      return { ...args.result, rows }
-    },
-  }
-}

package/src/coercion-plugin.test.ts

@@ -1,160 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import type { QueryResult, UnknownRow } from 'kysely'
-import { createCoercionPlugin, type CoercionMap } from './coercion-plugin.js'
-
-function selectFrom(...tables: string[]) {
-  return {
-    kind: 'SelectQueryNode',
-    from: {
-      kind: 'FromNode',
-      froms: tables.map((table) => ({
-        kind: 'TableNode',
-        table: {
-          kind: 'SchemableIdentifierNode',
-          identifier: { kind: 'IdentifierNode', name: table },
-        },
-      })),
-    },
-  }
-}
-
-const runTransform = async (
-  map: CoercionMap,
-  rows: UnknownRow[],
-  node?: unknown
-): Promise<UnknownRow[]> => {
-  const plugin = createCoercionPlugin({ map })
-  const queryId = {} as { queryId: string }
-  if (node !== undefined) {
-    plugin.transformQuery({ node, queryId } as any)
-  }
-  const result = { rows } as QueryResult<UnknownRow>
-  const out = await plugin.transformResult({ result, queryId } as any)
-  return out.rows as UnknownRow[]
-}
-
-describe('createCoercionPlugin', () => {
-  test('transformQuery passes the node through untouched', () => {
-    const plugin = createCoercionPlugin({ map: {} })
-    const node = selectFrom('users') as any
-    assert.equal(
-      plugin.transformQuery({ node, queryId: { queryId: 'x' } } as any),
-      node
-    )
-  })
-
-  test('coerces date columns from ISO strings to Date', async () => {
-    const [row] = await runTransform({ users: { created_at: 'date' } }, [
-      { created_at: '2026-06-26T00:00:00.000Z' },
-    ])
-    assert.ok(row!.created_at instanceof Date)
-    assert.equal(
-      (row!.created_at as Date).toISOString(),
-      '2026-06-26T00:00:00.000Z'
-    )
-  })
-
-  test('leaves unparseable date strings untouched', async () => {
-    const [row] = await runTransform({ users: { created_at: 'date' } }, [
-      { created_at: 'not-a-date' },
-    ])
-    assert.equal(row!.created_at, 'not-a-date')
-  })
-
-  test('coerces bool columns from 0/1 numbers and bigints', async () => {
-    const rows = await runTransform(
-      { users: { is_active: 'bool', has_pets: 'bool' } },
-      [{ is_active: 1, has_pets: 0n }]
-    )
-    assert.equal(rows[0]!.is_active, true)
-    assert.equal(rows[0]!.has_pets, false)
-  })
-
-  test('parses json columns and tolerates invalid json', async () => {
-    const rows = await runTransform(
-      { users: { meta: 'json', broken: 'json' } },
-      [{ meta: '{"a":1}', broken: '{bad' }]
-    )
-    assert.deepEqual(rows[0]!.meta, { a: 1 })
-    assert.equal(rows[0]!.broken, '{bad')
-  })
-
-  test('passes through null values and unmapped columns', async () => {
-    const rows = await runTransform({ users: { created_at: 'date' } }, [
-      { created_at: null, name: 'leave me' },
-    ])
-    assert.equal(rows[0]!.created_at, null)
-    assert.equal(rows[0]!.name, 'leave me')
-  })
-
-  test('matches both snake_case and camelCase column names', async () => {
-    const rows = await runTransform({ users: { created_at: 'date' } }, [
-      { createdAt: '2026-06-26T00:00:00.000Z' },
-    ])
-    assert.ok(rows[0]!.createdAt instanceof Date)
-  })
-
-  test('leaves columns ambiguous across tables uncoerced', async () => {
-    const rows = await runTransform(
-      { users: { value: 'json' }, events: { value: 'bool' } },
-      [{ value: '{"a":1}' }]
-    )
-    assert.equal(rows[0]!.value, '{"a":1}')
-  })
-
-  test('still coerces columns that agree across tables', async () => {
-    const rows = await runTransform(
-      { users: { active: 'bool' }, events: { active: 'bool' } },
-      [{ active: 1 }]
-    )
-    assert.equal(rows[0]!.active, true)
-  })
-
-  test('uses table-qualified coercions when names collide', async () => {
-    const map: CoercionMap = {
-      users: { settings: 'json' },
-      posts: { settings: 'bool' },
-    }
-    const fromUsers = await runTransform(
-      map,
-      [{ settings: '{"theme":"dark"}' }],
-      selectFrom('users')
-    )
-    assert.deepEqual(fromUsers[0]!.settings, { theme: 'dark' })
-
-    const fromPosts = await runTransform(
-      map,
-      [{ settings: 1 }],
-      selectFrom('posts')
-    )
-    assert.equal(fromPosts[0]!.settings, true)
-  })
-
-  test('table-qualified lookup matches camelCase result columns too', async () => {
-    const rows = await runTransform(
-      { users: { created_at: 'date' }, jobs: { created_at: 'json' } },
-      [{ createdAt: '2026-06-26T00:00:00.000Z' }],
-      selectFrom('users')
-    )
-    assert.ok(rows[0]!.createdAt instanceof Date)
-  })
-
-  test('a join whose tables disagree leaves the column uncoerced', async () => {
-    const rows = await runTransform(
-      { users: { value: 'json' }, events: { value: 'bool' } },
-      [{ value: '{"a":1}' }],
-      selectFrom('users', 'events')
-    )
-    assert.equal(rows[0]!.value, '{"a":1}')
-  })
-
-  test('falls back to flat keys when the query names no known table', async () => {
-    const rows = await runTransform(
-      { users: { created_at: 'date' } },
-      [{ createdAt: '2026-01-02T03:04:05.000Z' }],
-      selectFrom('unrelated')
-    )
-    assert.ok(rows[0]!.createdAt instanceof Date)
-  })
-})

package/src/coercion-plugin.ts

@@ -1,187 +0,0 @@
-import type { KyselyPlugin, RootOperationNode, UnknownRow } from 'kysely'
-
-/**
- * The kinds a column can be coerced *to* at runtime. This is the value type of
- * the generated `CoercionMap`, so it is a public artifact contract — a kind may
- * only appear here if `fromDb` below actually does something with it.
- *
- * `uuid` is deliberately absent: it is an annotation kind (it selects the `Uuid`
- * TypeScript type in the generated schema) but not a coercion kind, and the
- * codegen filters it out of `coercion.gen.ts` for exactly that reason — a UUID
- * is a string in both Postgres and SQLite.
- */
-export type ColumnKind = 'date' | 'bool' | 'json'
-
-/**
- * Per-table column kind map. Keys are the table names queries are written
- * against; inner keys are snake_case column names.
- * Generated into `outDir/db/coercion.gen.ts` by `pikku db migrate` from the
- * explicit `kind` entries in `db/annotations.ts`.
- */
-export type CoercionMap = Record<string, Record<string, ColumnKind>>
-
-export interface CreateCoercionPluginOptions {
-  map: CoercionMap
-}
-
-function fromDb(value: unknown, kind: ColumnKind): unknown {
-  if (value == null) return value
-  switch (kind) {
-    case 'date':
-      if (typeof value === 'string') {
-        const d = new Date(value)
-        return Number.isNaN(d.getTime()) ? value : d
-      }
-      return value
-    case 'bool':
-      if (typeof value === 'number') return value !== 0
-      if (typeof value === 'bigint') return value !== 0n
-      return value
-    case 'json':
-      if (typeof value !== 'string') return value
-      try {
-        return JSON.parse(value)
-      } catch {
-        return value
-      }
-  }
-}
-
-function snakeToCamel(name: string): string {
-  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase())
-}
-
-interface ResolvedMaps {
-  /** `table.column` → kind, for the exact per-query resolution. */
-  qualified: Record<string, ColumnKind>
-  /** `column` → kind, the fallback for when the query's tables say nothing. */
-  flat: Record<string, ColumnKind>
-}
-
-/**
- * Flatten the per-table map into a table-qualified lookup plus a bare
- * column-name fallback. Both are indexed by BOTH snake_case and camelCase so
- * they work regardless of CamelCasePlugin ordering in the plugin array.
- *
- * When two tables disagree on the kind for the same column name, the bare name
- * is ambiguous (a joined/aliased query could carry either) and is dropped from
- * the flat map rather than letting whichever table was processed last win. The
- * qualified map still resolves it whenever the query names its tables.
- */
-function buildMaps(map: CoercionMap): ResolvedMaps {
-  const qualified: Record<string, ColumnKind> = {}
-  const flat: Record<string, ColumnKind> = {}
-  const ambiguous = new Set<string>()
-  const assignFlat = (key: string, kind: ColumnKind) => {
-    const existing = flat[key]
-    if (existing !== undefined && existing !== kind) {
-      ambiguous.add(key)
-      return
-    }
-    flat[key] = kind
-  }
-  for (const [table, cols] of Object.entries(map)) {
-    for (const [col, kind] of Object.entries(cols)) {
-      const camel = snakeToCamel(col)
-      qualified[`${table}.${col}`] = kind
-      qualified[`${table}.${camel}`] = kind
-      assignFlat(col, kind)
-      assignFlat(camel, kind)
-    }
-  }
-  for (const key of ambiguous) delete flat[key]
-  return { qualified, flat }
-}
-
-/**
- * Collect every table named anywhere in the query's operation node, so a result
- * column can be resolved against the tables the query actually touched instead
- * of against every table in the schema.
- */
-function collectQueryTables(node: unknown, out: Set<string>): void {
-  if (!node || typeof node !== 'object') return
-
-  const op = node as {
-    kind?: string
-    table?: { identifier?: { name?: string } }
-  }
-  if (op.kind === 'TableNode') {
-    const tableName = op.table?.identifier?.name
-    if (typeof tableName === 'string' && tableName.length > 0)
-      out.add(tableName)
-  }
-
-  for (const value of Object.values(node)) {
-    if (Array.isArray(value)) {
-      for (const item of value) collectQueryTables(item, out)
-    } else {
-      collectQueryTables(value, out)
-    }
-  }
-}
-
-/**
- * Resolve a result column's kind against the query's tables, falling back to
- * the bare column name. Tables that disagree with each other are as ambiguous
- * as two schema tables are, so they fall back too.
- */
-function lookupKind(
-  maps: ResolvedMaps,
-  tables: readonly string[],
-  col: string
-): ColumnKind | undefined {
-  let matchedKind: ColumnKind | undefined
-  for (const table of tables) {
-    const kind = maps.qualified[`${table}.${col}`]
-    if (!kind) continue
-    if (matchedKind && matchedKind !== kind) return maps.flat[col]
-    matchedKind = kind
-  }
-  return matchedKind ?? maps.flat[col]
-}
-
-/**
- * Convert values stored in a dialect's on-disk representation back into the
- * logical types app code expects (Date / boolean / parsed JSON).
- *
- * SQLite is what makes this necessary — it stores dates as TEXT, booleans as
- * INTEGER and JSON as TEXT — but the plugin is dialect-neutral: on Postgres the
- * driver already returns Date/boolean/object, and every branch of `fromDb`
- * passes a non-string, non-number value straight through. That is why it lives
- * in `@pikku/kysely` next to `SerializePlugin` rather than in a SQLite package:
- * the CLI installs it on its local Postgres database too.
- *
- * Write-side coercion (Date → ISO string, boolean → 0/1, object → JSON) is
- * handled in the SQLite database adapters (always-on), so this plugin is
- * read-only.
- *
- * Place AFTER CamelCasePlugin in the plugin array (or it handles both
- * orderings via the dual-keyed maps).
- */
-export function createCoercionPlugin(
-  options: CreateCoercionPluginOptions
-): KyselyPlugin {
-  const maps = buildMaps(options.map)
-  const queryTables = new WeakMap<object, readonly string[]>()
-  return {
-    transformQuery(args) {
-      const tables = new Set<string>()
-      collectQueryTables(args.node as RootOperationNode, tables)
-      queryTables.set(args.queryId, [...tables])
-      return args.node
-    },
-    async transformResult(args) {
-      const tables = queryTables.get(args.queryId) ?? []
-      const out: UnknownRow[] = []
-      for (const row of args.result.rows as UnknownRow[]) {
-        const next: UnknownRow = { ...row }
-        for (const [col, val] of Object.entries(row)) {
-          const kind = lookupKind(maps, tables, col)
-          if (kind) next[col] = fromDb(val, kind)
-        }
-        out.push(next)
-      }
-      return { ...args.result, rows: out }
-    },
-  }
-}