@pikku/kysely 0.13.23 → 0.13.27

package/src/schema/index.ts

@@ -1,441 +0,0 @@
-import { CamelCasePlugin, type Kysely } from 'kysely'
-import {
-  schemaContext,
-  type PikkuSchema,
-  type RequiredTypes,
-  type SchemaContext,
-  type SchemaRequirement,
-} from './pikku-schema.types.js'
-import { agentSchema } from './agent.schema.js'
-import { auditSchema } from './audit.schema.js'
-import { channelSchema } from './channel.schema.js'
-import { credentialSchema } from './credential.schema.js'
-import { deploymentSchema } from './deployment.schema.js'
-import { scopeSchema } from './scope.schema.js'
-import { secretSchema } from './secret.schema.js'
-import { sessionSchema } from './session.schema.js'
-import { webhookSchema } from './webhook.schema.js'
-import { workflowSchema } from './workflow.schema.js'
-import { virtualUserSchema } from './virtual-user.schema.js'
-import { virtualUserScheduleSchema } from './virtual-user-schedule.schema.js'
-
-export type {
-  PikkuSchema,
-  RequiredTypes,
-  SchemaContext,
-  SchemaRequirement,
-  SchemaStatement,
-  SchemaStatementFactory,
-} from './pikku-schema.types.js'
-export {
-  rawStatement,
-  requiredType,
-  schemaContext,
-  unqualifiedContext,
-} from './pikku-schema.types.js'
-
-/**
- * Every table any part of the pikku runtime can need, in dependency order.
- *
- * Order is load-bearing, not cosmetic: `scope` has foreign keys onto Better
- * Auth's `user`, and the tables within each schema reference each other. Sort
- * this list alphabetically and it stops applying.
- *
- * `audit` and `virtualUser` are in the list now. They used to be left out and
- * created by their own services at boot, which was the only way they ever came
- * into existence — so with the runtime no longer creating anything, leaving
- * them out would mean a wired audit sink starting up against a table that
- * nothing writes a migration for. Both are gated by `ownedBy`, so a project
- * that wires neither still carries neither.
- */
-export const pikkuSchemas: PikkuSchema[] = [
-  channelSchema,
-  sessionSchema,
-  secretSchema,
-  credentialSchema,
-  deploymentSchema,
-  webhookSchema,
-  workflowSchema,
-  agentSchema,
-  scopeSchema,
-  auditSchema,
-  virtualUserSchema,
-  virtualUserScheduleSchema,
-]
-
-export { agentSchema } from './agent.schema.js'
-export { auditSchema } from './audit.schema.js'
-export { channelSchema } from './channel.schema.js'
-export { credentialSchema } from './credential.schema.js'
-export { deploymentSchema } from './deployment.schema.js'
-export { scopeSchema } from './scope.schema.js'
-export { secretSchema } from './secret.schema.js'
-export { sessionSchema } from './session.schema.js'
-export { virtualUserSchema } from './virtual-user.schema.js'
-export { virtualUserScheduleSchema } from './virtual-user-schedule.schema.js'
-export { webhookSchema } from './webhook.schema.js'
-export { workflowSchema } from './workflow.schema.js'
-
-/**
- * The schemas a project needs, given the services its code actually reaches.
- *
- * `services` is the inspector's `requiredServices` — the same set that drives
- * service tree-shaking, so a schema is written for exactly the projects whose
- * functions, middleware or wirings reach the service that owns its tables.
- *
- * The gate is one-sided: a schema declaring no `ownedBy` is always in, because
- * nothing a project writes implies it and leaving it out would be a guess.
- */
-export const requiredPikkuSchemas = (
-  services: ReadonlySet<string>
-): PikkuSchema[] =>
-  pikkuSchemas.filter(
-    (schema) =>
-      !schema.ownedBy || schema.ownedBy.some((name) => services.has(name))
-  )
-
-/**
- * Bind a declaration to a database.
- *
- * The plugin is applied here rather than trusted to the caller. Declarations
- * name tables and columns the way the rest of the codebase queries them
- * (`agentThreads.resourceId`), and it is `CamelCasePlugin` that turns those into
- * the physical `agent_threads.resource_id`. Without it the same declaration
- * silently creates quoted camelCase tables that nothing can read.
- */
-const bind = (db: Kysely<any>) => db.withPlugin(new CamelCasePlugin())
-
-/**
- * The schema a connection is bound to, or `undefined` for one that is not.
- *
- * Read back out of compiled DDL rather than off the connection, because kysely
- * keeps the `withSchema(...)` setting inside its executor and exposes no way to
- * ask. Compiling a throwaway `create table` is the same trick `declaredTables`
- * uses on the real statements, against the same regex — nothing is executed and
- * the probe never leaves this function.
- *
- * Derived rather than passed in so that raw statements follow whatever
- * connection they are handed. A caller that had to remember to say the schema
- * twice would eventually say it once.
- */
-const boundSchema = (db: Kysely<any>): string | undefined =>
-  CREATE_TABLE.exec(
-    db.schema.createTable('pikkuSchemaProbe').addColumn('id', 'text').compile()
-      .sql
-  )?.[1]
-
-/** The context for statements compiled against `db`, matching its binding. */
-const contextFor = (db: Kysely<any>): SchemaContext =>
-  schemaContext(boundSchema(db))
-
-export interface UnmetRequirement {
-  schema: PikkuSchema
-  requirement: SchemaRequirement
-}
-
-/**
- * Look up every prerequisite in `db`, reporting the gaps and the types found.
- *
- * Both halves come from one introspection because they are one question. The
- * gaps say whether a schema can be applied at all; the types say how — a
- * foreign key onto a `uuid` primary key has to be declared `uuid`, and guessing
- * `text` produces DDL the database refuses.
- *
- * Introspection returns physical names, so `requires` is written in physical
- * names too — this is the one place in the declaration that is not camelCase.
- */
-export const resolveRequirements = async (
-  db: Kysely<any>,
-  schemas: PikkuSchema[] = pikkuSchemas
-): Promise<{ types: RequiredTypes; unmet: UnmetRequirement[] }> => {
-  const tables = new Map(
-    (await bind(db).introspection.getTables()).map((table) => [
-      table.name,
-      table,
-    ])
-  )
-
-  const types: RequiredTypes = {}
-  const unmet: UnmetRequirement[] = []
-  for (const schema of schemas) {
-    for (const requirement of schema.requires ?? []) {
-      const column = tables
-        .get(requirement.table)
-        ?.columns.find((c) => c.name === requirement.column)
-      if (!column) {
-        unmet.push({ schema, requirement })
-      } else {
-        types[`${requirement.table}.${requirement.column}`] = column.dataType
-      }
-    }
-  }
-  return { types, unmet }
-}
-
-/**
- * The prerequisites `db` does not satisfy, as a list rather than a throw.
- *
- * Separate from `applyPikkuSchemas` because the two callers want opposite
- * things from the same answer: a service booting cannot proceed without its
- * tables, while a tool asking what a project's schema *would* be needs to
- * describe the gap rather than die on it.
- */
-export const unsatisfiedRequirements = async (
-  db: Kysely<any>,
-  schemas: PikkuSchema[] = pikkuSchemas
-): Promise<UnmetRequirement[]> => (await resolveRequirements(db, schemas)).unmet
-
-/**
- * Create the tables, in order, on a database that has whatever they require.
- *
- * Prerequisites are checked before anything is created, so a project missing
- * one is told which schema wanted what — rather than being handed a foreign key
- * error, or a half-applied database to clean up.
- *
- * The statements then run in one transaction, so the same promise holds for a
- * failure the check cannot foresee: a statement that dies mid-list takes the
- * ones before it with it. On an engine without transactional DDL the rollback
- * is the engine's to give, not ours.
- */
-export const applyPikkuSchemas = async (
-  db: Kysely<any>,
-  schemas: PikkuSchema[] = pikkuSchemas
-): Promise<void> => {
-  const { types, unmet } = await resolveRequirements(db, schemas)
-  if (unmet.length > 0) {
-    throw new Error(
-      unmet
-        .map(
-          ({ schema, requirement }) =>
-            `The '${schema.name}' schema requires '${requirement.table}.${requirement.column}', which nothing has created. ` +
-            `${requirement.owner} owns it — apply its schema first.`
-        )
-        .join('\n')
-    )
-  }
-
-  await db.transaction().execute(async (trx) => {
-    const bound = bind(trx)
-    const ctx = contextFor(bound)
-    for (const schema of schemas) {
-      for (const statement of schema.statements) {
-        const query = statement(bound, types, ctx)
-        try {
-          await query.execute()
-        } catch (error) {
-          throw explain(error, query.compile().sql, schema)
-        }
-      }
-    }
-  })
-}
-
-/** `references "app"."workflow_runs"` — a foreign key onto a qualified table. */
-const QUALIFIED_REFERENCE = /references "[^"]+"\."[^"]+"/i
-
-/**
- * sqlite's own words for "you put a dot where a table name goes".
- *
- * Matched rather than a driver's `code`, because every sqlite binding
- * (better-sqlite3, node:sqlite, bun:sqlite, libsql) passes the engine's message
- * through verbatim while disagreeing about how to label it. Postgres phrases the
- * same class of error the other way round — `syntax error at or near "."` — so
- * this cannot fire on it.
- */
-const SQLITE_REJECTED_QUALIFIER = /near "\.":\s*syntax error/i
-
-/**
- * Say what a schema-bound connection did to the DDL, when that is what failed.
- *
- * `withSchema(...)` qualifies foreign key targets along with everything else.
- * Postgres needs that — an unqualified reference resolves against `search_path`,
- * which a schema-bound connection does not control — and sqlite refuses it: a
- * `REFERENCES` clause there takes a bare table name, because a foreign key can
- * only point inside the same database, so there is no qualifier to give. One
- * declaration cannot spell both, and what the engine says about it is
- * `near ".": syntax error`, which names neither the schema nor the cause.
- *
- * Gated on sqlite's exact phrasing as well as the SQL. Postgres compiles the
- * same qualified reference legitimately, and can raise a syntax error of its own
- * on this DDL — a column type resolved from `requires` goes in verbatim — so a
- * looser `/syntax error/` would answer for postgres in sqlite's name.
- */
-const explain = (error: unknown, sql: string, schema: PikkuSchema): unknown => {
-  const message = error instanceof Error ? error.message : String(error)
-  if (
-    !QUALIFIED_REFERENCE.test(sql) ||
-    !SQLITE_REJECTED_QUALIFIER.test(message)
-  ) {
-    return error
-  }
-  return new Error(
-    `The '${schema.name}' schema has a foreign key, and this connection is bound to a schema, ` +
-      `so it compiled to a qualified 'references "schema"."table"' that the database rejected. ` +
-      'sqlite is the engine that does this: its REFERENCES clause takes a bare table name. ' +
-      'Use a connection without withSchema(...) there — sqlite has one schema to be in — ' +
-      'or write the schema down as a migration with `pikku db generate` and apply it yourself. ' +
-      `The database said: ${message}`,
-    { cause: error }
-  )
-}
-
-/** A table a schema creates, as the DDL addresses it. */
-export interface DeclaredTable {
-  /** Present when the connection is `withSchema(...)`-bound. */
-  schema?: string
-  name: string
-}
-
-/** How a table reads in an error message: qualified only when it is. */
-const displayName = (table: DeclaredTable): string =>
-  table.schema ? `${table.schema}.${table.name}` : table.name
-
-/**
- * `create table "workflow_runs"` and `create table "app"."workflow_runs"`.
- *
- * The schema half is optional and the table is always the LAST quoted
- * identifier — matching the first one instead reads a `withSchema('app')`
- * connection's DDL as a table called `app`, which is no table at all.
- */
-const CREATE_TABLE =
-  /^\s*create table (?:if not exists\s+)?(?:"([^"]+)"\.)?"([^"]+)"/i
-
-/**
- * The tables a schema creates, read back out of its own compiled SQL.
- *
- * Derived rather than declared alongside the statements, because a hand-kept
- * list of names is a second source of truth: rename a table in a statement and
- * the list keeps answering for the old one.
- *
- * Compiled against `db` rather than in the abstract, so the answer carries the
- * schema the DDL will actually target — the same binding the lookup has to use.
- */
-export const declaredTables = (
-  schema: PikkuSchema,
-  db: Kysely<any>
-): DeclaredTable[] => {
-  const bound = bind(db)
-  const ctx = contextFor(bound)
-  const tables: DeclaredTable[] = []
-  for (const statement of schema.statements) {
-    const match = CREATE_TABLE.exec(statement(bound, {}, ctx).compile().sql)
-    if (match) tables.push({ schema: match[1], name: match[2]! })
-  }
-  return tables
-}
-
-/**
- * What `db` already has, indexed both ways.
- *
- * Introspection reports every schema it can see, so the bare name alone cannot
- * answer the question: a `workflow_runs` in some other schema is not the one a
- * `withSchema('app')` connection reads or writes. Qualified declarations are
- * matched on the pair. Unqualified DDL resolves against the connection's
- * search_path, which is not knowable from here, so it falls back to the name.
- */
-interface ExistingTables {
-  qualified: Set<string>
-  bare: Set<string>
-  /** Whether this engine reports schemas at all. */
-  schemaAware: boolean
-}
-
-const tablesOf = async (db: Kysely<any>): Promise<ExistingTables> => {
-  const tables = await bind(db).introspection.getTables()
-  return {
-    qualified: new Set(
-      tables
-        .filter((table) => table.schema)
-        .map((table) => `${table.schema}.${table.name}`)
-    ),
-    bare: new Set(tables.map((table) => table.name)),
-    schemaAware: tables.some((table) => table.schema !== undefined),
-  }
-}
-
-/**
- * Qualified declarations match on the pair — but only where that pair means
- * something.
- *
- * `TableMetadata.schema` is optional, and sqlite and mysql leave it unset:
- * sqlite has one schema to be in, and mysql calls the thing a database. A
- * `withSchema('main')` connection there declares `main.workflow_runs` while
- * introspection can only offer `workflow_runs`, and holding out for the pair
- * would read every existing table as missing — the same false negative this
- * whole function exists to fix, arrived at from the other side. So when the
- * engine reports no schemas, the bare name is the only name there is.
- */
-const isPresent = (existing: ExistingTables, table: DeclaredTable): boolean =>
-  table.schema && existing.schemaAware
-    ? existing.qualified.has(`${table.schema}.${table.name}`)
-    : existing.bare.has(table.name)
-
-/**
- * Refuse to start unless one schema's tables are already there.
- *
- * What a service calls at boot, and it never issues DDL. The runtime is not an
- * author of the schema: `pikku db generate` writes the declaration down as a
- * migration and `pikku db migrate` applies it, and those two are the only way
- * these tables come into existence. A service that finds them missing says so
- * and stops.
- *
- * This is the whole point of gating what `db generate` writes. While boot could
- * still create, a schema that generation left out was created silently at
- * startup instead — two authorities over one set of tables, which is the
- * condition all of this exists to end. With creation gone, a schema generation
- * missed is a sentence at startup naming the command that fixes it.
- *
- * Half-present is not a distinct case any more. Every missing table is reported
- * the same way, because the remedy is the same one either way.
- */
-export const requirePikkuSchema = async (
-  db: Kysely<any>,
-  schema: PikkuSchema
-): Promise<void> => {
-  const existing = await tablesOf(db)
-  const declared = declaredTables(schema, db)
-  const missing = declared.filter((table) => !isPresent(existing, table))
-
-  if (missing.length === 0) return
-
-  const present = declared.filter((table) => isPresent(existing, table))
-  throw new Error(
-    `The '${schema.name}' schema is not in this database: ${missing.map(displayName).join(', ')} missing` +
-      (present.length > 0
-        ? `, ${present.map(displayName).join(', ')} already there`
-        : '') +
-      '. The runtime does not create these — run `pikku db generate` to write the ' +
-      'migration, then `pikku db migrate` to apply it.'
-  )
-}
-
-/**
- * Render the declaration as SQL for the dialect `db` was built with.
- *
- * `types` comes from `resolveRequirements` against the database the migration
- * is being written for. Omit it and foreign keys onto another source's columns
- * compile as `text`, which is a shape, not a migration.
- *
- * `schema` qualifies every table the migration creates, for a project that
- * keeps the runtime tables somewhere other than the default search path. It is
- * applied here and not to `db` itself because the caller's connection is a
- * throwaway the declaration was just *applied* to, in whatever schema that
- * database actually has — qualifying that would create tables in a schema the
- * scratch database has never heard of. Only the rendered SQL is bound.
- */
-export const compilePikkuSchemas = (
-  db: Kysely<any>,
-  schemas: PikkuSchema[] = pikkuSchemas,
-  types: RequiredTypes = {},
-  schemaName?: string
-): string => {
-  const bound = schemaName ? bind(db).withSchema(schemaName) : bind(db)
-  const ctx = contextFor(bound)
-  return schemas
-    .flatMap((schema) =>
-      schema.statements.map(
-        (statement) => `${statement(bound, types, ctx).compile().sql};`
-      )
-    )
-    .join('\n\n')
-}

package/src/schema/pikku-schema.types.ts

@@ -1,169 +0,0 @@
-import { sql, type CompiledQuery, type Kysely, type RawBuilder } from 'kysely'
-
-/**
- * One DDL statement, bound to a database.
- *
- * Bound rather than free-standing because the same declaration serves two
- * purposes that need the same object: applied to a throwaway database it yields
- * the schema to introspect, and compiled against a dialect it yields the SQL a
- * migration is written from.
- */
-export interface SchemaStatement {
-  execute(): Promise<unknown>
-  compile(): CompiledQuery
-}
-
-export type SchemaStatementFactory = (
-  db: Kysely<any>,
-  types: RequiredTypes,
-  ctx: SchemaContext
-) => SchemaStatement
-
-/**
- * What a statement needs to know about the schema its DDL lands in.
- *
- * Only raw SQL needs this. The schema builder learns the schema from the
- * connection — `withSchema('app')` qualifies every table it names, foreign key
- * targets included — but a raw fragment is passed through verbatim, so a
- * statement that spells its own SQL has to spell the qualifier too.
- */
-export interface SchemaContext {
-  /**
-   * A table as the surrounding DDL addresses it: `"app"."credentials"` on a
-   * schema-bound connection, `"credentials"` otherwise.
-   *
-   * Takes the physical name, not the camelCase one the schema builder accepts.
-   * Raw SQL does not go through `CamelCasePlugin`, so it is already written in
-   * physical names throughout and this is no exception.
-   */
-  table: (name: string) => RawBuilder<unknown>
-}
-
-/**
- * The `SchemaContext` for DDL that names no schema.
- *
- * The default everywhere a schema has not been asked for, which is every engine
- * but postgres and most postgres projects too.
- */
-export const unqualifiedContext: SchemaContext = {
-  table: (name) => sql.raw(`"${name}"`),
-}
-
-/**
- * A `SchemaContext` qualifying every table into `schema`.
- *
- * Identifiers are quoted rather than interpolated bare so a schema named after
- * a reserved word still compiles.
- */
-export const schemaContext = (schema: string | undefined): SchemaContext =>
-  schema
-    ? { table: (name) => sql.raw(`"${schema}"."${name}"`) }
-    : unqualifiedContext
-
-/**
- * The physical types of the columns named in `requires`, keyed `table.column`.
- *
- * Introspected from the database the schemas are being applied to, because a
- * foreign key column has to be declared with the type of the column it points
- * at and that column belongs to somebody else.
- */
-export type RequiredTypes = Record<string, string>
-
-/**
- * The declared type for a foreign key onto a column another source owns.
- *
- * Falls back to `text` when nothing has been introspected — the case when the
- * declaration is compiled without a database, where the real type is unknowable
- * and only the shape of the statement is being inspected.
- */
-export const requiredType = (
-  types: RequiredTypes,
-  table: string,
-  column: string
-): RawBuilder<unknown> => sql.raw(types[`${table}.${column}`] ?? 'text')
-
-/**
- * The tables one part of the pikku runtime needs, declared rather than created.
- *
- * `name` labels the generated migration and the drift report, so it is part of
- * the contract — changing it orphans the migration that was written under the
- * old one.
- */
-export interface PikkuSchema {
-  name: string
-  statements: SchemaStatementFactory[]
-  /**
-   * Tables this schema references but does not create, which something else
-   * must have created first.
-   *
-   * Declared rather than discovered so the failure arrives as a sentence naming
-   * what is missing and who owns it, instead of a foreign key error from the
-   * database — or, worse, a stub table conjured up to make the error go away.
-   */
-  requires?: SchemaRequirement[]
-  /**
-   * The singleton services whose `init()` requires these tables, or absent for
-   * a schema every project needs.
-   *
-   * Named as services rather than as wirings because a service is what the
-   * tables actually belong to: one `requirePikkuSchema` call site per service,
-   * and `pikku db generate` writes the schema for a project whose functions
-   * reach any of them. A wiring is a poor proxy — a project can construct
-   * `KyselyWorkflowService` and wire no workflows at all.
-   *
-   * Absent means unconditional. `secrets` is on every project and the session
-   * and deployment stores are reached by generated code rather than by
-   * functions, so nothing a project writes implies them and their absence
-   * cannot be inferred.
-   *
-   * Under-naming is safe now that the runtime creates nothing: a schema left
-   * out of the migration is a sentence at startup, not a table conjured behind
-   * your back. Over-naming costs an unused table. Prefer over-naming.
-   */
-  ownedBy?: string[]
-}
-
-/**
- * A column another source owns, which one of these schemas depends on.
- *
- * Named down to the column, not just the table, because that is the granularity
- * the dependency actually has: a foreign key needs the referenced column to
- * exist *and* needs its type in order to declare a matching one.
- *
- * `owner` is carried in the declaration rather than composed into the error at
- * the point it is thrown, so adding a second prerequisite cannot leave behind a
- * message that still names the first one's owner.
- */
-export interface SchemaRequirement {
-  table: string
-  column: string
-  owner: string
-}
-
-/**
- * Wrap a raw SQL fragment as a statement.
- *
- * For the DDL kysely's schema builder cannot express — a unique index over an
- * expression, say. Raw SQL is *not* rewritten by `withSchema`, so a fragment
- * naming a table unqualified resolves against the connection's search path
- * rather than the schema the rest of the declaration lands in. Take the
- * function form and name tables through `ctx.table` to stay with them; the
- * bare-fragment form is for SQL that names no table at all.
- */
-export function rawStatement(
-  fragment: RawBuilder<unknown>
-): SchemaStatementFactory
-export function rawStatement(
-  build: (ctx: SchemaContext) => RawBuilder<unknown>
-): SchemaStatementFactory
-export function rawStatement(
-  source: RawBuilder<unknown> | ((ctx: SchemaContext) => RawBuilder<unknown>)
-): SchemaStatementFactory {
-  return (db, _types, ctx = unqualifiedContext) => {
-    const fragment = typeof source === 'function' ? source(ctx) : source
-    return {
-      execute: () => fragment.execute(db),
-      compile: () => fragment.compile(db),
-    }
-  }
-}