dzql 0.6.37 → 0.8.0

package/src/postgres/auth.ts

@@ -0,0 +1,50 @@
+/**
+ * Postgres auth helpers — RLS session context for delta-doc queries.
+ *
+ * `withAppAuth(pool, sqlArg, fn)` checks out a client, opens a transaction,
+ * sets `app.user_id` for the duration of the transaction, runs `fn` with the
+ * client, then commits and releases. Row-Level Security policies that read
+ * `current_setting('app.user_id', true)` then filter automatically.
+ *
+ *   CREATE POLICY venues_owner ON venues
+ *     FOR ALL USING (owner_id = current_setting('app.user_id', true)::int);
+ *
+ *   await withAppAuth(pool, user.id, c =>
+ *     c.query("SELECT delta_open($1) AS doc", [docName]),
+ *   );
+ *
+ * The session variable is set via `SET LOCAL` so it reverts on transaction
+ * end — safe against pool reuse.
+ *
+ * Re-exports the `DeltaAuth` contract from `../auth` for convenience.
+ */
+import type { Pool, PoolClient } from "pg";
+
+export type { DeltaAuth, AuthError, AuthAction } from "@blueshed/delta/auth";
+export { isAuthError, wireAuth, upgradeWithAuth } from "@blueshed/delta/auth";
+
+/**
+ * Run `fn` inside a transaction with `SET LOCAL app.user_id = <sqlArg>`. All
+ * queries issued on the passed client observe RLS policies scoped to that
+ * identity.
+ */
+export async function withAppAuth<T>(
+  pool: Pool,
+  sqlArg: string | number,
+  fn: (c: PoolClient) => Promise<T>,
+): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    // SET LOCAL cannot be parameterised — use set_config(..., is_local=true).
+    await client.query("SELECT set_config('app.user_id', $1, true)", [String(sqlArg)]);
+    const result = await fn(client);
+    await client.query("COMMIT");
+    return result;
+  } catch (err) {
+    try { await client.query("ROLLBACK"); } catch { /* pool may already be closed */ }
+    throw err;
+  } finally {
+    client.release();
+  }
+}

package/src/postgres/bootstrap.ts

@@ -0,0 +1,55 @@
+/**
+ * Bootstrap helpers — apply the delta-doc framework SQL to a Postgres
+ * database, programmatically. Alternative to copying the files into a
+ * consumer's `init_db/` directory.
+ *
+ *   import { Pool } from "pg";
+ *   import { applyFramework } from "@blueshed/delta/postgres";
+ *
+ *   const pool = new Pool({ connectionString: process.env.PG_URL });
+ *   await applyFramework(pool);
+ *
+ * The framework SQL is idempotent (`CREATE … IF NOT EXISTS`,
+ * `ON CONFLICT DO UPDATE`) so it is safe to call on every server boot.
+ *
+ * For docker-entrypoint-initdb.d workflows, use the `delta init` CLI to
+ * copy the same files into a directory the image can mount.
+ */
+import type { Pool } from "pg";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const FRAMEWORK_SQL_DIR = join(import.meta.dir, "..", "sql");
+
+/** Absolute paths to the framework SQL files, in apply-order.
+ *  Filters to `001*-*.sql` — siblings like `auth-jwt.sql` are applied
+ *  separately (see `@blueshed/delta/auth-jwt` → `applyAuthJwtSchema`). */
+export function frameworkSqlFiles(): string[] {
+  return readdirSync(FRAMEWORK_SQL_DIR)
+    .filter((f) => /^001[a-z]?-.+\.sql$/.test(f))
+    .sort()
+    .map((f) => join(FRAMEWORK_SQL_DIR, f));
+}
+
+/**
+ * Apply the framework SQL to the given pool. Runs every `001*` file in
+ * `src/sql/` alphabetically — 001a through 001g today. Safe to call
+ * repeatedly (idempotent statements).
+ */
+export async function applyFramework(pool: Pool): Promise<void> {
+  for (const path of frameworkSqlFiles()) {
+    const sql = readFileSync(path, "utf8");
+    await pool.query(sql);
+  }
+}
+
+/**
+ * Apply an arbitrary SQL string to the pool (convenience wrapper). Useful
+ * for layering `generateSql(schema, docs)` output on top of the framework:
+ *
+ *   await applyFramework(pool);
+ *   await applySql(pool, generateSql(schema, docs));
+ */
+export async function applySql(pool: Pool, sql: string): Promise<void> {
+  if (sql.trim()) await pool.query(sql);
+}

package/src/postgres/carry.ts

@@ -0,0 +1,40 @@
+/**
+ * Carrying an app's rows into, and out of, a Postgres database -- a server, or
+ * PGlite in this process. The same `Snapshot` every backend gives and takes
+ * (`../../schema`), so the data moves along the path with its ids and
+ * sequences unchanged.
+ */
+import type { Pool } from "pg";
+import { isoTime, lastId, q, type Schema, type Snapshot } from "@blueshed/delta/backend";
+
+/** Every row of the schema's tables (every version of a temporal row), and each sequence's last id. */
+export async function exportTables(pool: Pool, schema: Schema): Promise<Snapshot> {
+  const tables: Snapshot["tables"] = {};
+  const sequences: Record<string, number> = {};
+  for (const [key, table] of Object.entries(schema.tables)) {
+    const order = table.temporal ? "id, valid_from" : "id";
+    const { rows } = await pool.query(`SELECT to_jsonb(t.*) AS row FROM ${q(table.name)} t ORDER BY ${order}`);
+    tables[key] = rows.map(({ row }: { row: Record<string, unknown> }) =>
+      table.temporal ? { ...row, valid_from: isoTime(row.valid_from), valid_to: isoTime(row.valid_to) } : row,
+    );
+    const seq = (await pool.query(`SELECT last_value, is_called FROM ${q(`seq_${table.name}`)}`)).rows[0];
+    sequences[key] = seq ? Number(seq.last_value) - (seq.is_called ? 0 : 1) : 0;
+  }
+  return { tables, sequences };
+}
+
+/**
+ * Put a snapshot's rows into the schema's tables, as they are (ids kept), and
+ * set each sequence past them, so the next row the database names follows the
+ * last one named where the rows came from. The tables should be empty.
+ */
+export async function importTables(pool: Pool, schema: Schema, snapshot: Snapshot): Promise<void> {
+  for (const [key, table] of Object.entries(schema.tables)) {
+    for (const row of snapshot.tables[key] ?? []) {
+      const value = table.temporal ? { valid_from: new Date().toISOString(), valid_to: null, ...row } : row;
+      await pool.query(`INSERT INTO ${q(table.name)} SELECT * FROM jsonb_populate_record(null::${q(table.name)}, $1)`, [JSON.stringify(value)]);
+    }
+    const last = lastId(snapshot, key);
+    await pool.query(`SELECT setval($1, $2, $3)`, [`seq_${table.name}`, Math.max(last, 1), last > 0]);
+  }
+}

package/src/postgres/codegen.ts

@@ -0,0 +1,172 @@
+/**
+ * Codegen — turn a TypeScript schema (`defineSchema`) and a set of doc
+ * definitions (`defineDoc`) into the SQL that registers both with the
+ * delta-doc framework.
+ *
+ * Output includes:
+ *   - CREATE SEQUENCE / CREATE TABLE (+ current_* view for temporal tables)
+ *   - Helper indexes
+ *   - INSERT INTO _delta_collections (columns_def, parent, temporal, cascade_on)
+ *   - INSERT INTO _delta_docs       (prefix, root_collection, include, scope)
+ *
+ * Everything is idempotent (CREATE … IF NOT EXISTS, ON CONFLICT DO UPDATE),
+ * so the same file can be re-applied to a live database after a schema change.
+ *
+ * Drive it from your project's `types.ts`:
+ *
+ *   import { generateSql } from "@blueshed/delta/postgres";
+ *   import { schema, docs } from "./types";
+ *   await Bun.write("init_db/003-tables.sql", generateSql(schema, docs));
+ *
+ * Or from the bundled CLI:
+ *
+ *   bunx delta sql ./types.ts --out init_db/003-tables.sql
+ */
+import type { Schema, DocDef } from "./schema";
+import { lit, columnSqlType, sqlDefault, findCascadeOn } from "./sql";
+import { defaultForType, q } from "@blueshed/delta/backend";
+import { assertScopeKeys } from "@blueshed/delta/backend";
+
+export interface GenerateSqlOptions {
+  /** Header comment included at the top of the file. */
+  header?: string;
+  /** Override the regenerate-command hint printed in the header. */
+  regenerate?: string;
+}
+
+export function generateSql(
+  schema: Schema,
+  docs: DocDef[],
+  opts: GenerateSqlOptions = {},
+): string {
+  const today = new Date().toISOString().slice(0, 10);
+  const header =
+    opts.header ?? "GENERATED FROM types.ts — DO NOT EDIT";
+  const regen = opts.regenerate ?? "bunx delta sql ./types.ts";
+
+  const lines: string[] = [
+    "-- =========================================================================",
+    `-- ${header}`,
+    `-- Generated: ${today}`,
+    `-- Regenerate: ${regen}`,
+    "-- =========================================================================",
+    "",
+  ];
+
+  for (const [key, table] of Object.entries(schema.tables)) {
+    const seqName = `seq_${table.name}`;
+    lines.push(`-- ${key}`);
+    lines.push(`CREATE SEQUENCE IF NOT EXISTS ${q(seqName)};`);
+    lines.push("");
+
+    const cols: string[] = [
+      `id BIGINT NOT NULL DEFAULT nextval(${lit(seqName)})`,
+    ];
+    if (table.parent) {
+      cols.push(`${q(table.parent.fkColumn)} BIGINT NOT NULL`);
+    }
+
+    for (const [col, def] of Object.entries(table.columns)) {
+      const sqlType = columnSqlType(def);
+      const notNull = def.nullable ? "" : " NOT NULL";
+      const defaultVal =
+        def.default !== undefined ? ` DEFAULT ${sqlDefault(def.default)}` : "";
+      cols.push(`${q(col)} ${sqlType}${notNull}${defaultVal}`);
+    }
+
+    if (table.temporal) {
+      cols.push("valid_from TIMESTAMPTZ NOT NULL DEFAULT NOW()");
+      cols.push("valid_to TIMESTAMPTZ");
+      cols.push("PRIMARY KEY (id, valid_from)");
+    } else {
+      cols.push("PRIMARY KEY (id)");
+    }
+
+    lines.push(`CREATE TABLE IF NOT EXISTS ${q(table.name)} (`);
+    lines.push(cols.map((c) => `  ${c}`).join(",\n"));
+    lines.push(");");
+    // A column a later schema declares, added to a table made before it (SQLite's migrateSchema): a
+    // no-op on a table just made. Nullable, with its default or its type's, as migrateSchema adds it.
+    if (table.parent) lines.push(`ALTER TABLE ${q(table.name)} ADD COLUMN IF NOT EXISTS ${q(table.parent.fkColumn)} BIGINT;`);
+    for (const [col, def] of Object.entries(table.columns)) {
+      const fill = def.default !== undefined ? def.default : def.nullable ? undefined : defaultForType(def.type);
+      lines.push(`ALTER TABLE ${q(table.name)} ADD COLUMN IF NOT EXISTS ${q(col)} ${columnSqlType(def)}${fill !== undefined ? ` DEFAULT ${sqlDefault(fill)}` : ""};`);
+    }
+    // Own the sequence to the table.id so `TRUNCATE RESTART IDENTITY`
+    // actually resets the counter — without this, re-seeds in tests and
+    // demo scripts drift by the stale sequence value.
+    lines.push(`ALTER SEQUENCE ${q(seqName)} OWNED BY ${q(table.name)}.id;`);
+
+    if (table.temporal) {
+      // security_invoker (Postgres 15+): the view reads as the caller, so the table's RLS holds through it
+      lines.push(
+        `CREATE OR REPLACE VIEW ${q("current_" + table.name)} WITH (security_invoker = true) AS SELECT * FROM ${q(table.name)} WHERE valid_to IS NULL;`,
+      );
+      lines.push(
+        `CREATE INDEX IF NOT EXISTS ${q("idx_" + table.name + "_id_valid")} ON ${q(table.name)} (id, valid_to);`,
+      );
+    }
+    if (table.parent) {
+      lines.push(
+        `CREATE INDEX IF NOT EXISTS ${q("idx_" + table.name + "_" + table.parent.fkColumn)} ON ${q(table.name)} (${q(table.parent.fkColumn)});`,
+      );
+    }
+    lines.push("");
+  }
+
+  // Collection metadata
+  lines.push("-- Collection metadata");
+  for (const [key, table] of Object.entries(schema.tables)) {
+    const cascadeOn = lit(JSON.stringify(findCascadeOn(key, schema)));
+    const colsDef = lit(JSON.stringify(table.columns));
+    const parent = table.parent ? lit(table.parent.collection) : "NULL";
+    const parentFk = table.parent ? lit(table.parent.fkColumn) : "NULL";
+    lines.push(
+      `INSERT INTO _delta_collections (collection_key, table_name, columns_def, parent_collection, parent_fk, temporal, cascade_on)`,
+    );
+    lines.push(
+      `  VALUES (${lit(key)}, ${lit(table.name)}, ${colsDef}, ${parent}, ${parentFk}, ${table.temporal}, ${cascadeOn})`,
+    );
+    lines.push(
+      `  ON CONFLICT (collection_key) DO UPDATE SET table_name = EXCLUDED.table_name, columns_def = EXCLUDED.columns_def,`,
+    );
+    lines.push(
+      `    parent_collection = EXCLUDED.parent_collection, parent_fk = EXCLUDED.parent_fk, temporal = EXCLUDED.temporal, cascade_on = EXCLUDED.cascade_on;`,
+    );
+  }
+  lines.push("");
+
+  // Doc definitions. `implied` is written when a document is implied (and
+  // then for each, so one that stops being implied is reset), and `held` when
+  // one names its columns (todo #70): SQL for an app with neither needs no
+  // framework SQL newer than it.
+  lines.push("-- Doc definitions");
+  const implied = docs.some((d) => d.implied);
+  const held = docs.some((d) => d.columns);
+  for (const doc of docs) assertScopeKeys(doc, schema);   // its scope's keys and the columns it names are its collections' columns
+  for (const doc of docs) {
+    // Build a proper Postgres text[] array literal: each element is wrapped in
+    // double quotes with embedded `"` and `\` backslash-escaped, so a comma or
+    // quote inside a collection key can't corrupt the array.
+    const include = doc.include.length
+      ? lit(
+          `{${doc.include
+            .map((e) => `"${e.replace(/(["\\])/g, "\\$1")}"`)
+            .join(",")}}`,
+        )
+      : "'{}'";
+    const scope = lit(JSON.stringify(doc.scope));
+    lines.push(
+      `INSERT INTO _delta_docs (prefix, root_collection, include, scope${implied ? ", implied" : ""}${held ? ", held" : ""})`,
+    );
+    lines.push(
+      `  VALUES (${lit(doc.prefix)}, ${lit(doc.root)}, ${include}, ${scope}${implied ? `, ${!!doc.implied}` : ""}${held ? `, ${lit(JSON.stringify(doc.columns ?? {}))}` : ""})`,
+    );
+    lines.push(
+      `  ON CONFLICT (prefix) DO UPDATE SET root_collection = EXCLUDED.root_collection, include = EXCLUDED.include, scope = EXCLUDED.scope${implied ? ", implied = EXCLUDED.implied" : ""}${held ? ", held = EXCLUDED.held" : ""};`,
+    );
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/postgres/index.ts

@@ -0,0 +1,58 @@
+/**
+ * @blueshed/delta/postgres — Postgres backend for delta-doc.
+ *
+ * Schema + stored functions + LISTEN dispatch. Tables are generated from
+ * a TypeScript schema definition; all mutations go through stored functions
+ * that apply JSON-Patch ops and emit NOTIFY events. The doc-listener fans
+ * those events out to WebSocket subscribers.
+ *
+ *   import {
+ *     defineSchema, defineDoc,
+ *     createDocListener, docTypeFromDef,
+ *   } from "@blueshed/delta/postgres";
+ *
+ * The stored functions are `src/sql/001*.sql`: `applyFramework(pool)` applies
+ * them, or `bunx @blueshed/delta init <dir>` copies them for a migration tool
+ * (plain idempotent SQL; order is alphabetical).
+ */
+
+export {
+  defineSchema,
+  defineDoc,
+  loadDocAt,
+  pruneOpsLog,
+  validateOps,
+} from "./schema";
+export type {
+  ColumnDef,
+  TableDef,
+  Schema,
+  ResolvedTable,
+  DocDef,
+  ValidationError,
+} from "./schema";
+
+export { generateSql } from "./codegen";
+
+export { exportTables, importTables } from "./carry";
+export type { Snapshot } from "@blueshed/delta/backend";
+export type { GenerateSqlOptions } from "./codegen";
+
+export {
+  applyFramework,
+  applySql,
+  frameworkSqlFiles,
+} from "./bootstrap";
+
+export { migrate, migrationStatus, renameColumn, dropColumn, renameTable, fromFolder } from "./migrate";
+export type { Migration, MigrateOptions, MigrateResult, MigrationStatus } from "./migrate";
+
+export { createDocListener, defineCustomDoc } from "./listener";
+export type { CustomDocDef } from "./listener";
+
+export { docTypeFromDef } from "./registry";
+export type { DocType, Writer } from "./registry";
+
+export { withAppAuth } from "./auth";
+export type { DeltaAuth, AuthError, AuthAction } from "./auth";
+export { isAuthError, wireAuth, upgradeWithAuth } from "./auth";