dzql 0.8.0 → 0.10.0

package/src/compile/rows.ts

@@ -0,0 +1,122 @@
+/**
+ * Compiled row SQL: the statements a write runs on a row, written for each
+ * collection. The framework builds each from the table's name at run time
+ * (`EXECUTE format(...)`), planned again on every call; written out, each is a
+ * statement whose plan the database keeps.
+ *
+ * `compileRows(schema)` writes, for every collection of the schema:
+ * - `_delta_row_lock`: the row as it stands (a temporal one's open version),
+ *   locked for the write;
+ * - `_delta_row_put`: a replace's row stored -- a temporal one a new version
+ *   (one this write made gives way to it, the standing one closes), else the
+ *   row again -- answered as stored;
+ * - `_delta_next_id`: an add's id, from the collection's sequence;
+ * - `_delta_row_clear_moment`: a temporal version this write made and took
+ *   back, so an add of its id takes its place;
+ * - `_delta_row_there`: is the row there now (a temporal one's open version)?
+ * - `_delta_row_read`: the row as it stands, without its validity;
+ * - `_delta_row_add`: an add's row stored. The framework's INSERT names the
+ *   columns the row gives (`_delta_insert_sql`), so one it leaves out takes its
+ *   database default: where the row gives exactly every column the schema
+ *   declares (its id, parent key, columns and validity), that INSERT is one
+ *   statement, written here; a row with any other keys is the framework's.
+ *
+ * Each answers what the framework's (`_framework`) answers, and sends any
+ * collection it was not compiled for there.
+ */
+import { q, type Schema } from "@blueshed/delta/backend";
+import { lit, standingRows } from "./opens";
+
+/** A CASE over the collections, each branch from `branch`, any other collection to `fallback`. */
+function dispatch(schema: Schema, branch: (coll: string, table: Schema["tables"][string]) => string | null, fallback: string): string {
+  const branches = Object.entries(schema.tables).flatMap(([coll, table]) => {
+    const b = branch(coll, table);
+    return b === null ? [] : [`    WHEN ${lit(coll)} THEN\n      ${b}`];
+  });
+  return branches.length ? `  CASE p_coll\n${branches.join("\n")}\n    ELSE ${fallback}\n  END CASE;` : `  ${fallback}`;
+}
+
+/** The row SQL of every collection of `schema`, and the dispatch to the framework's for any other. */
+export function compileRows(schema: Schema): string {
+  const lock = `CREATE OR REPLACE FUNCTION _delta_row_lock(p_coll TEXT, p_table TEXT, p_temporal BOOLEAN, p_id BIGINT)
+RETURNS JSONB AS $$
+DECLARE
+  v_row JSONB;
+BEGIN
+${dispatch(schema, (_, t) => `SELECT to_jsonb(t.*) INTO v_row FROM ${q(t.name)} t WHERE t.id = p_id${t.temporal ? " AND valid_to IS NULL" : ""} FOR UPDATE;
+      RETURN v_row;`, "RETURN _delta_row_lock_framework(p_coll, p_table, p_temporal, p_id);")}
+END;
+$$ LANGUAGE plpgsql;`;
+
+  const put = `CREATE OR REPLACE FUNCTION _delta_row_put(p_coll TEXT, p_table TEXT, p_temporal BOOLEAN, p_id BIGINT, p_row JSONB, p_ts TIMESTAMPTZ)
+RETURNS JSONB AS $$
+DECLARE
+  v_row JSONB;
+BEGIN
+${dispatch(schema, (_, t) => (t.temporal
+    ? `DELETE FROM ${q(t.name)} WHERE id = p_id AND valid_to IS NULL AND valid_from = p_ts;
+      UPDATE ${q(t.name)} SET valid_to = p_ts WHERE id = p_id AND valid_to IS NULL;
+      INSERT INTO ${q(t.name)} AS t SELECT * FROM jsonb_populate_record(null::${q(t.name)}, p_row || jsonb_build_object('valid_from', p_ts, 'valid_to', NULL))
+        RETURNING to_jsonb(t.*) INTO v_row;
+      RETURN v_row;`
+    : `DELETE FROM ${q(t.name)} WHERE id = p_id;
+      INSERT INTO ${q(t.name)} AS t SELECT * FROM jsonb_populate_record(null::${q(t.name)}, p_row) RETURNING to_jsonb(t.*) INTO v_row;
+      RETURN v_row;`), "RETURN _delta_row_put_framework(p_coll, p_table, p_temporal, p_id, p_row, p_ts);")}
+END;
+$$ LANGUAGE plpgsql;`;
+
+  // the sequence named as the framework names it: nextval of the text 'seq_<table>'
+  const next = `CREATE OR REPLACE FUNCTION _delta_next_id(p_coll TEXT, p_table TEXT)
+RETURNS BIGINT AS $$
+BEGIN
+${dispatch(schema, (_, t) => `RETURN nextval(${lit(`seq_${t.name}`)});`, "RETURN _delta_next_id_framework(p_coll, p_table);")}
+END;
+$$ LANGUAGE plpgsql;`;
+
+  const clear = `CREATE OR REPLACE FUNCTION _delta_row_clear_moment(p_coll TEXT, p_table TEXT, p_id BIGINT, p_ts TIMESTAMPTZ)
+RETURNS void AS $$
+BEGIN
+${dispatch(schema, (_, t) => (t.temporal ? `DELETE FROM ${q(t.name)} WHERE id = p_id AND valid_from = p_ts AND valid_to = p_ts;
+      RETURN;` : null), "PERFORM _delta_row_clear_moment_framework(p_coll, p_table, p_id, p_ts);")}
+END;
+$$ LANGUAGE plpgsql;`;
+
+  const there = `CREATE OR REPLACE FUNCTION _delta_row_there(p_collection_key TEXT, p_id BIGINT)
+RETURNS BOOLEAN AS $$
+DECLARE
+  p_coll TEXT := p_collection_key;
+BEGIN
+${dispatch(schema, (_, t) => `RETURN p_id IS NOT NULL AND EXISTS (SELECT 1 FROM ${standingRows(t)} WHERE id = p_id);`,
+    "RETURN _delta_row_there_framework(p_collection_key, p_id);")}
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+
+  const read = `CREATE OR REPLACE FUNCTION _delta_row_read(p_coll TEXT, p_view TEXT, p_id BIGINT)
+RETURNS JSONB AS $$
+DECLARE
+  v_row JSONB;
+BEGIN
+${dispatch(schema, (_, t) => `SELECT _delta_strip_temporal(to_jsonb(t.*)) INTO v_row FROM ${standingRows(t)} t WHERE t.id = p_id;
+      RETURN v_row;`, "RETURN _delta_row_read_framework(p_coll, p_view, p_id);")}
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+
+  const add = `CREATE OR REPLACE FUNCTION _delta_row_add(p_coll TEXT, p_table TEXT, p_row JSONB)
+RETURNS JSONB AS $$
+DECLARE
+  v_row JSONB;
+BEGIN
+${dispatch(schema, (_, t) => {
+    const keys = [...new Set(["id", ...(t.parent ? [t.parent.fkColumn] : []), ...Object.keys(t.columns), ...(t.temporal ? ["valid_from", "valid_to"] : [])])];
+    const cols = keys.map((k) => q(k)).join(", ");
+    return `IF p_row ?& ARRAY[${keys.map(lit).join(", ")}] AND (SELECT count(*) FROM jsonb_object_keys(p_row)) = ${keys.length} THEN
+        INSERT INTO ${q(t.name)} AS t (${cols}) SELECT ${cols} FROM jsonb_populate_record(null::${q(t.name)}, p_row) RETURNING to_jsonb(t.*) INTO v_row;
+        RETURN v_row;
+      END IF;
+      RETURN _delta_row_add_framework(p_coll, p_table, p_row);`;
+  }, "RETURN _delta_row_add_framework(p_coll, p_table, p_row);")}
+END;
+$$ LANGUAGE plpgsql;`;
+
+  return [lock, put, next, clear, there, read, add, ""].join("\n\n");
+}

package/src/compile/scope.ts

@@ -0,0 +1,87 @@
+/**
+ * Compiled write scope: may a document write a row? "You may write what you
+ * may read": every row-addressed op in a write is asked first (`delta_apply`,
+ * `_delta_row_in_scope`), and a row it may not read is answered as one that is
+ * not there.
+ *
+ * `compileInScope(schema, docs)` writes `dzql_in_scope__<slug>(name,
+ * collection, id)` for each document, answering what the framework's
+ * `_delta_row_in_scope` answers, from its definition: a list document holds
+ * its included collections whole and its root rows by the name's conditions;
+ * a single document holds a row whose parent chain, walked up through the
+ * tables as they stand, reaches its root, which meets the rest of its name's
+ * scope. And `_delta_row_in_scope` itself, which sends each compiled document
+ * to its own and any other to the framework (`_delta_row_in_scope_framework`).
+ */
+import { q, type DocDef, type Schema } from "@blueshed/delta/backend";
+import { lit, named, need, scopeOf , currentOnly } from "./opens";
+
+/** A document's write-scope function: `dzql_in_scope__<slug>`. */
+export const inScopeFunction = (prefix: string): string => named("in_scope", prefix);
+
+
+/** One document's write-scope function. */
+function inScopeOf(schema: Schema, doc: DocDef): string {
+  const root = need(schema, doc, doc.root);
+  const scope = scopeOf(schema, doc);   // a value its columns cannot take: refused, as the framework's resolver refuses it
+  const conds = scope.conds ? ` AND ${scope.conds}` : "";
+  // the root row of a single document: its id, and (where the name scopes more than the id) the rest of its scope
+  const others = Object.keys(doc.scope ?? {}).some((k) => k !== "id");
+  const rootMeets = (id: string) => others
+    ? `COALESCE(${id} = v_id, FALSE) AND EXISTS (SELECT 1 FROM ${q(root.name)} t WHERE t.id = v_id${currentOnly(root, "t")}${conds})`
+    : `COALESCE(${id} = v_id, FALSE)`;
+  const included = new Set(doc.include);
+
+  const singles = Object.entries(schema.tables).map(([coll, table]) => {
+    if (coll === doc.root) return `      WHEN ${lit(coll)} THEN RETURN ${rootMeets("p_id")};`;
+    // unparented: held whole where included; else it ends a chain short of the root
+    if (!table.parent) return `      WHEN ${lit(coll)} THEN RETURN ${included.has(coll) ? "TRUE" : "FALSE"};`;
+    let id = "p_id";
+    let t = table;
+    for (let depth = 0; depth < 32; depth++) {
+      id = `(SELECT x.${q(t.parent!.fkColumn)} FROM ${q(t.name)} x WHERE x.id = ${id}${currentOnly(t, "x")})`;
+      const parentKey = t.parent!.collection;
+      if (parentKey === doc.root) return `      WHEN ${lit(coll)} THEN RETURN ${rootMeets(id)};`;
+      const parent = schema.tables[parentKey];
+      if (!parent?.parent) return `      WHEN ${lit(coll)} THEN RETURN FALSE;`;   // the chain ends short of the root
+      t = parent;
+    }
+    return `      WHEN ${lit(coll)} THEN RETURN FALSE;`;
+  });
+
+  return `CREATE OR REPLACE FUNCTION ${inScopeFunction(doc.prefix)}(p_name TEXT, p_coll TEXT, p_id BIGINT)
+RETURNS BOOLEAN AS $$
+DECLARE
+  p_at     TIMESTAMPTZ;
+  v_single BOOLEAN;
+  v_id     BIGINT;
+  ${scope.declare.join("\n  ")}
+BEGIN
+  IF p_id IS NULL THEN RETURN FALSE; END IF;
+  ${scope.body}
+  IF NOT v_single THEN
+    -- a list holds its included collections whole; its root rows by the name's conditions
+    IF p_coll IS DISTINCT FROM ${lit(doc.root)} THEN RETURN TRUE; END IF;
+    RETURN EXISTS (SELECT 1 FROM ${q(root.name)} t WHERE t.id = p_id${currentOnly(root, "t")}${conds});
+  END IF;
+  CASE p_coll
+${singles.join("\n")}
+    ELSE RETURN FALSE;
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+}
+
+/** The SQL that answers a write's scope for each of `docs`: a function per document, and `_delta_row_in_scope` sending each to its own. */
+export function compileInScope(schema: Schema, docs: DocDef[]): string {
+  const dispatch = `CREATE OR REPLACE FUNCTION _delta_row_in_scope(p_def _delta_docs, p_doc_name TEXT, p_collection_key TEXT, p_id BIGINT)
+RETURNS BOOLEAN AS $$
+BEGIN
+  CASE p_def.prefix
+${docs.map((d) => `    WHEN ${lit(d.prefix)} THEN RETURN ${inScopeFunction(d.prefix)}(p_doc_name, p_collection_key, p_id);`).join("\n")}
+    ELSE RETURN _delta_row_in_scope_framework(p_def, p_doc_name, p_collection_key, p_id);
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+  return [...docs.map((d) => inScopeOf(schema, d)), dispatch, ""].join("\n\n");
+}

package/src/compile/told.ts

@@ -0,0 +1,94 @@
+/**
+ * Compiled telling: what a document is told of a write. Asked by `_delta_tell`
+ * of the writer and of every document that held a row the write touched, or
+ * holds it now, with the write's touches and their holders.
+ *
+ * `compileTold(schema, docs)` writes `dzql_told__<slug>(name, rows)` for each
+ * document, answering what the framework's `_delta_told` answers, from its
+ * definition: whether the name makes it one row (`scopeOf`), its root, the
+ * columns it shows of each collection it names them for (`columns`, the row's
+ * id and parent key with them), and the empty root an implied one opens with
+ * when its root leaves. And `_delta_told` itself, which sends each compiled
+ * document to its own and any other to the framework (`_delta_told_framework`).
+ */
+import type { DocDef, Schema } from "@blueshed/delta/backend";
+import { lit, named, need, scopeOf } from "./opens";
+
+/** A document's telling function: `dzql_told__<slug>`. */
+export const toldFunction = (prefix: string): string => named("told", prefix);
+
+/**
+ * A row (SQL `row`) of collection (SQL `coll`) as the document shows it, as
+ * `_delta_show` does: where it names the collection's columns, those, the id
+ * and the parent key; else whole.
+ */
+function shown(schema: Schema, doc: DocDef, coll: string, row: string): string {
+  const named = Object.entries(doc.columns ?? {});
+  if (named.length === 0) return row;
+  const branches = named.map(([c, cols]) => {
+    const fk = schema.tables[c]?.parent?.fkColumn;
+    const keep = [...new Set(["id", ...(fk ? [fk] : []), ...cols])].map(lit).join(", ");
+    return `WHEN ${lit(c)} THEN COALESCE((SELECT jsonb_object_agg(f, v) FROM jsonb_each(${row}) AS e(f, v) WHERE f IN (${keep})), '{}'::jsonb)`;
+  });
+  return `(CASE WHEN jsonb_typeof(${row}) IS DISTINCT FROM 'object' THEN ${row} ELSE CASE ${coll} ${branches.join(" ")} ELSE ${row} END END)`;
+}
+
+/** One document's telling function. */
+function toldOf(schema: Schema, doc: DocDef): string {
+  need(schema, doc, doc.root);
+  const scope = scopeOf(schema, doc);   // a name its columns cannot take: refused, as the framework's resolver refuses it
+  const after = shown(schema, doc, "v_t->>'coll'", "v_t->'after'");
+  const gone = doc.implied
+    ? shown(schema, doc, "v_t->>'coll'", `_delta_implied_root((SELECT d FROM _delta_docs d WHERE d.prefix = ${lit(doc.prefix)}), (v_t->>'id')::BIGINT)`)
+    : "'null'::jsonb";
+  return `CREATE OR REPLACE FUNCTION ${toldFunction(doc.prefix)}(p_name TEXT, p_rows JSONB)
+RETURNS JSONB AS $$
+DECLARE
+  p_at     TIMESTAMPTZ;
+  v_single BOOLEAN;
+  v_id     BIGINT;
+  v_t      JSONB;
+  v_told   JSONB := '[]'::jsonb;
+  v_was    BOOLEAN;
+  v_is     BOOLEAN;
+  v_root   BOOLEAN;
+  v_path   TEXT;
+  ${scope.declare.join("\n  ")}
+BEGIN
+  ${scope.body}
+  FOR v_t IN SELECT jsonb_array_elements(p_rows) LOOP
+    v_was := (v_t->'before') ? p_name;
+    v_is  := (v_t->'holders') ? p_name;
+    CONTINUE WHEN NOT v_was AND NOT v_is;
+    CONTINUE WHEN v_was AND v_is AND (v_t ? 'carried');   -- carried along, and its either way: unchanged for it
+    v_root := v_single AND (v_t->>'coll') = ${lit(doc.root)};
+    v_path := CASE WHEN v_root THEN _delta_build_path(v_t->>'coll') ELSE _delta_build_path(v_t->>'coll', v_t->>'id') END;
+    IF v_was AND v_is THEN   -- stayed: what changed
+      v_told := v_told || COALESCE((SELECT jsonb_agg(jsonb_build_object('op', 'replace', 'path', v_path || _delta_build_path(f), 'value', v) ORDER BY f COLLATE "C")
+                                      FROM jsonb_each(${after}) AS e(f, v) WHERE v IS DISTINCT FROM v_t->'was'->f), '[]'::jsonb);
+    ELSIF v_is THEN
+      v_told := v_told || jsonb_build_array(jsonb_build_object('op', CASE WHEN v_root THEN 'replace' ELSE 'add' END, 'path', v_path, 'value', ${after}));
+    ELSIF v_root THEN   -- gone: ${doc.implied ? "the empty root it then opens with" : "null"}
+      v_told := v_told || jsonb_build_array(jsonb_build_object('op', 'replace', 'path', v_path, 'value', ${gone}));
+    ELSE
+      v_told := v_told || jsonb_build_array(jsonb_build_object('op', 'remove', 'path', v_path));
+    END IF;
+  END LOOP;
+  RETURN v_told;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+}
+
+/** The SQL that answers what each of `docs` is told of a write: a function per document, and `_delta_told` sending each to its own. */
+export function compileTold(schema: Schema, docs: DocDef[]): string {
+  const dispatch = `CREATE OR REPLACE FUNCTION _delta_told(p_def _delta_docs, p_target TEXT, p_rows JSONB)
+RETURNS JSONB AS $$
+BEGIN
+  CASE p_def.prefix
+${docs.map((d) => `    WHEN ${lit(d.prefix)} THEN RETURN ${toldFunction(d.prefix)}(p_target, p_rows);`).join("\n")}
+    ELSE RETURN _delta_told_framework(p_def, p_target, p_rows);
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+  return [...docs.map((d) => toldOf(schema, d)), dispatch, ""].join("\n\n");
+}

package/src/postgres/auth-jwt-sql.ts

@@ -3,7 +3,7 @@
  *
  * These are split out of `auth-jwt.ts` so the `delta init` CLI (which only
  * needs the file path) can run in projects that haven't installed jose.
- * Consumers of the `@blueshed/delta/auth-jwt` subpath still get these via
+ * Consumers of the `dzql/auth-jwt` subpath still get these via
  * re-export from `auth-jwt.ts`.
  */
 import type { Pool } from "pg";

package/src/postgres/auth-jwt.ts

@@ -2,7 +2,7 @@
  * Auth-JWT — reference `DeltaAuth` implementation using JWTs (jose) and
  * Postgres stored functions for credential verification.
  *
- * Ship this as an opt-in subpath: `@blueshed/delta/auth-jwt`. Users who want
+ * Ship this as an opt-in subpath: `dzql/auth-jwt`. Users who want
  * a different auth scheme (sessions, OAuth, magic links, none) implement
  * their own `DeltaAuth` instead.
  *
@@ -13,7 +13,7 @@
  *
  * Both are overridable via the `loginSql` / `registerSql` options.
  *
- *   import { jwtAuth } from "@blueshed/delta/auth-jwt";
+ *   import { jwtAuth } from "dzql/auth-jwt";
  *
  *   const auth = jwtAuth({
  *     pool,

package/src/postgres/bootstrap.ts

@@ -4,7 +4,7 @@
  * consumer's `init_db/` directory.
  *
  *   import { Pool } from "pg";
- *   import { applyFramework } from "@blueshed/delta/postgres";
+ *   import { applyFramework } from "dzql/postgres";
  *
  *   const pool = new Pool({ connectionString: process.env.PG_URL });
  *   await applyFramework(pool);
@@ -23,7 +23,7 @@ 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`). */
+ *  separately (see `dzql/auth-jwt` → `applyAuthJwtSchema`). */
 export function frameworkSqlFiles(): string[] {
   return readdirSync(FRAMEWORK_SQL_DIR)
     .filter((f) => /^001[a-z]?-.+\.sql$/.test(f))