dzql 0.9.0 → 0.10.0

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))

package/src/postgres/codegen.ts

@@ -14,7 +14,7 @@
  *
  * Drive it from your project's `types.ts`:
  *
- *   import { generateSql } from "@blueshed/delta/postgres";
+ *   import { generateSql } from "dzql/postgres";
  *   import { schema, docs } from "./types";
  *   await Bun.write("init_db/003-tables.sql", generateSql(schema, docs));
  *
@@ -27,6 +27,16 @@ import { lit, columnSqlType, sqlDefault, findCascadeOn } from "./sql";
 import { defaultForType, q } from "@blueshed/delta/backend";
 import { assertScopeKeys } from "@blueshed/delta/backend";
 import { compileOpens } from "../compile/opens";
+import { compileHolds } from "../compile/holds";
+import { compileInScope } from "../compile/scope";
+import { compileHolders } from "../compile/holders";
+import { compileResolve } from "../compile/resolve";
+import { compileRootThere } from "../compile/root";
+import { compileColumns } from "../compile/columns";
+import { compileRows } from "../compile/rows";
+import { compileCascades } from "../compile/cascades";
+import { compileLedger } from "../compile/ledger";
+import { compileTold } from "../compile/told";
 
 export interface GenerateSqlOptions {
   /** Header comment included at the top of the file. */
@@ -170,6 +180,6 @@ export function generateSql(
   lines.push("");
 
   // each document opened by SQL compiled for it (dzql), which docTypeFromDef calls
-  lines.push("", compileOpens(schema, docs));
+  lines.push("", compileOpens(schema, docs), "", compileHolds(schema, docs), "", compileInScope(schema, docs), "", compileTold(schema, docs), "", compileHolders(schema, docs), "", compileResolve(schema, docs), "", compileRootThere(schema, docs), "", compileColumns(schema, docs), "", compileRows(schema), "", compileCascades(schema), "", compileLedger(schema, docs));
   return lines.join("\n");
 }

package/src/postgres/index.ts

@@ -1,5 +1,5 @@
 /**
- * @blueshed/delta/postgres — Postgres backend for delta-doc.
+ * dzql/postgres — delta's Postgres backend, compiled from its definitions.
  *
  * Schema + stored functions + LISTEN dispatch. Tables are generated from
  * a TypeScript schema definition; all mutations go through stored functions
@@ -9,7 +9,7 @@
  *   import {
  *     defineSchema, defineDoc,
  *     createDocListener, docTypeFromDef,
- *   } from "@blueshed/delta/postgres";
+ *   } from "dzql/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

package/src/postgres/pglite.ts

@@ -4,7 +4,7 @@
  * The same stored functions, the same listener, the same documents as a
  * Postgres server, on PGlite (Postgres compiled to WASM): no database to run,
  * the data in a directory (or in memory). `openPglite()` answers the slice of
- * `pg`'s Pool delta uses, so everything in `@blueshed/delta/postgres` runs on
+ * `pg`'s Pool delta uses, so everything in `dzql/postgres` runs on
  * it unchanged:
  *
  *   const pool = await openPglite("./data");        // or openPglite() in memory

package/src/sql/001a-delta-meta.sql

@@ -136,7 +136,7 @@ $$;
 -- It used to be merged into the broadcast row, acked, and dropped (or cast) by
 -- jsonb_populate_record: stored otherwise than told. id, the parent key and
 -- the temporal columns are the row's own.
-CREATE OR REPLACE FUNCTION _delta_assert_fields(
+CREATE OR REPLACE FUNCTION _delta_assert_fields_framework(
   p_collection TEXT, p_columns JSONB, p_parent_fk TEXT, p_value JSONB
 ) RETURNS void LANGUAGE plpgsql IMMUTABLE AS $$
 DECLARE
@@ -178,6 +178,13 @@ BEGIN
 END;
 $$;
 
+-- The checks every write asks: the framework's, until dzql's compiler
+-- (`compileColumns`) replaces this with one that checks each column set it
+-- compiled by its own statements, and any other by the framework's.
+CREATE OR REPLACE FUNCTION _delta_assert_fields(
+  p_collection TEXT, p_columns JSONB, p_parent_fk TEXT, p_value JSONB
+) RETURNS void LANGUAGE sql IMMUTABLE AS $$ SELECT _delta_assert_fields_framework(p_collection, p_columns, p_parent_fk, p_value); $$;
+
 -- Pick the source relation for a collection.
 --   temporal + no timestamp → current_<table> view
 --   temporal + timestamp    → base <table> (caller filters with _delta_temporal_where)

package/src/sql/001b-delta-scope.sql

@@ -51,7 +51,7 @@ $$ LANGUAGE sql STABLE;
 -- how the fan-out reads a name opened before a rule refused it (_delta_doc_holds).
 -- ---------------------------------------------------------------------------
 
-CREATE OR REPLACE FUNCTION _delta_resolve_scope(p_def _delta_docs, p_doc_name TEXT, p_refuse BOOLEAN)
+CREATE OR REPLACE FUNCTION _delta_resolve_scope_framework(p_def _delta_docs, p_doc_name TEXT, p_refuse BOOLEAN)
 RETURNS JSONB AS $$
 DECLARE
   v_doc_id    TEXT;
@@ -285,6 +285,12 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql STABLE;
 
+-- The resolver every caller asks: the framework's, until dzql's compiler
+-- (`compileResolve`) replaces it with one sending each document it compiled
+-- to its own.
+CREATE OR REPLACE FUNCTION _delta_resolve_scope(p_def _delta_docs, p_doc_name TEXT, p_refuse BOOLEAN)
+RETURNS JSONB LANGUAGE sql STABLE AS $$ SELECT _delta_resolve_scope_framework(p_def, p_doc_name, p_refuse); $$;
+
 -- The resolver as every caller but the fan-out asks it: a value refused is raised.
 CREATE OR REPLACE FUNCTION _delta_resolve_scope(p_def _delta_docs, p_doc_name TEXT)
 RETURNS JSONB LANGUAGE sql STABLE AS $$
@@ -323,7 +329,7 @@ $$;
 -- so the gate can't be used to probe for ids.
 -- ---------------------------------------------------------------------------
 
-CREATE OR REPLACE FUNCTION _delta_row_in_scope(
+CREATE OR REPLACE FUNCTION _delta_row_in_scope_framework(
   p_def            _delta_docs,
   p_doc_name       TEXT,
   p_collection_key TEXT,
@@ -413,6 +419,12 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql STABLE;
 
+-- _delta_row_in_scope: as the framework reads a definition (above), until dzql's generateSql
+-- compiles the app's documents: it then sends each to its own dzql_in_scope__<prefix>, and any
+-- other (registered by hand, or by another generateSql) here.
+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 LANGUAGE sql STABLE AS $$ SELECT _delta_row_in_scope_framework(p_def, p_doc_name, p_collection_key, p_id); $$;
+
 -- ---------------------------------------------------------------------------
 -- Who holds a row: the fan-out (todo #28)
 --
@@ -459,7 +471,7 @@ $$ LANGUAGE plpgsql STABLE;
 -- _delta_doc_holds: does the document `p_doc_name` (of `p_def`) hold `p_row`
 -- of `p_coll`? Judged on the row's values, so a row as it was before a write
 -- is judged as well as one as it is after -- the same rule delta_open reads by.
-CREATE OR REPLACE FUNCTION _delta_doc_holds(p_def _delta_docs, p_doc_name TEXT, p_coll TEXT, p_row JSONB)
+CREATE OR REPLACE FUNCTION _delta_doc_holds_framework(p_def _delta_docs, p_doc_name TEXT, p_coll TEXT, p_row JSONB)
 RETURNS BOOLEAN AS $$
 DECLARE
   v_scope JSONB;
@@ -503,6 +515,12 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql STABLE;
 
+-- _delta_doc_holds: as the framework reads a definition (above), until dzql's generateSql
+-- compiles the app's documents: it then sends each to its own dzql_holds__<prefix>, and any
+-- other (registered by hand, or by another generateSql) here.
+CREATE OR REPLACE FUNCTION _delta_doc_holds(p_def _delta_docs, p_doc_name TEXT, p_coll TEXT, p_row JSONB)
+RETURNS BOOLEAN LANGUAGE sql STABLE AS $$ SELECT _delta_doc_holds_framework(p_def, p_doc_name, p_coll, p_row); $$;
+
 -- _delta_holders: the documents that hold `p_row` of `p_coll` -- every one
 -- open now (a name in _delta_held, todo #73), and the writer's own `p_writer`.
 -- A single-mode document of an unscoped definition is found by its name,
@@ -527,7 +545,7 @@ $$ LANGUAGE plpgsql STABLE;
 -- that applied the framework, owning the tables without FORCE ROW LEVEL
 -- SECURITY, or with BYPASSRLS; applied as the app's own role, it sees what
 -- the writer sees, as before.
-CREATE OR REPLACE FUNCTION _delta_holders(p_coll TEXT, p_row JSONB, p_writer TEXT)
+CREATE OR REPLACE FUNCTION _delta_holders_framework(p_coll TEXT, p_row JSONB, p_writer TEXT, p_skip TEXT[])
 RETURNS TEXT[] AS $$
 DECLARE
   v_def   _delta_docs;
@@ -547,7 +565,7 @@ BEGIN
 
   FOR v_def IN
     SELECT * FROM _delta_docs
-     WHERE root_collection = p_coll OR p_coll = ANY(include)
+     WHERE (root_collection = p_coll OR p_coll = ANY(include)) AND NOT (prefix = ANY(p_skip))
   LOOP
     v_all := v_def.scope <> '{}'::jsonb
              OR (p_coll IS DISTINCT FROM v_def.root_collection AND v_coll.parent_collection IS NULL);
@@ -572,6 +590,15 @@ END;
 $$ LANGUAGE plpgsql VOLATILE SECURITY DEFINER;
 -- the search path it was applied with, and pg_temp last: a caller's temporary
 -- tables never stand in for delta's own (pg_temp is searched first unless named)
+DO $$ BEGIN
+  EXECUTE format('ALTER FUNCTION _delta_holders_framework(TEXT, JSONB, TEXT, TEXT[]) SET search_path = %s, pg_temp', COALESCE(NULLIF(current_setting('search_path'), ''), 'public'));
+END $$;
+
+-- `p_skip`: the prefixes asked already, by the compiled `_delta_holders`
+-- (dzql's `compileHolders`), which replaces this one: each document it
+-- compiled asked by its own lookups, the rest by the framework's.
+CREATE OR REPLACE FUNCTION _delta_holders(p_coll TEXT, p_row JSONB, p_writer TEXT)
+RETURNS TEXT[] LANGUAGE sql VOLATILE SECURITY DEFINER AS $$ SELECT _delta_holders_framework(p_coll, p_row, p_writer, ARRAY[]::text[]); $$;
 DO $$ BEGIN
   EXECUTE format('ALTER FUNCTION _delta_holders(TEXT, JSONB, TEXT) SET search_path = %s, pg_temp', COALESCE(NULLIF(current_setting('search_path'), ''), 'public'));
 END $$;

package/src/sql/001c-delta-read.sql

@@ -212,8 +212,7 @@ BEGIN
   END IF;
   SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = p_def.root_collection;
   IF NOT FOUND THEN RETURN; END IF;
-  EXECUTE format('SELECT EXISTS (SELECT 1 FROM %I WHERE id = $1)', _delta_source_view(v_coll.table_name, v_coll.temporal))
-    INTO v_exists USING p_id;
+  v_exists := _delta_row_there(p_def.root_collection, p_id);
   IF v_exists THEN RETURN; END IF;
   -- Not there, as the writer reads it: made under the add rule (todo #71) -- an
   -- id the serial has handed out is taken, whether a row RLS hides holds it or
@@ -225,7 +224,7 @@ BEGIN
   END IF;
   v_row := _delta_implied_root(p_def, p_id);
   IF v_coll.temporal THEN v_row := v_row || jsonb_build_object('valid_from', p_ts, 'valid_to', NULL); END IF;
-  EXECUTE _delta_insert_sql(v_coll.table_name, v_row) USING v_row;
+  PERFORM _delta_row_add(p_def.root_collection, v_coll.table_name, v_row);
 END;
 $$ LANGUAGE plpgsql;
 
@@ -235,17 +234,12 @@ DECLARE
   v_doc    JSONB := COALESCE(_delta_open(p_doc_name, TRUE), '{}'::jsonb);
   v_def    _delta_docs := _delta_find_doc(p_doc_name);
   v_scope  JSONB;
-  v_coll   RECORD;
-  v_exists BOOLEAN;
 BEGIN
   IF NOT COALESCE(v_def.implied, FALSE) THEN RETURN v_doc; END IF;
   v_scope := _delta_resolve_scope(v_def, p_doc_name);
   IF (v_scope->>'mode') <> 'single' THEN RETURN v_doc; END IF;
-  SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = v_def.root_collection;
-  IF NOT FOUND THEN RETURN v_doc; END IF;
-  EXECUTE format('SELECT EXISTS (SELECT 1 FROM %I WHERE id = $1)', _delta_source_view(v_coll.table_name, v_coll.temporal))
-    INTO v_exists USING (v_scope->'values'->>'id')::BIGINT;
-  IF v_exists THEN RETURN v_doc; END IF;
+  -- (its root collection is there: _delta_open raised otherwise)
+  IF _delta_row_there(v_def.root_collection, (v_scope->'values'->>'id')::BIGINT) THEN RETURN v_doc; END IF;
   RETURN v_doc || jsonb_build_object(v_def.root_collection, 'null'::jsonb);
 END;
 $$ LANGUAGE plpgsql;
@@ -351,7 +345,7 @@ $$ LANGUAGE plpgsql STABLE;
 -- whole: what the ledger's inverse and a walk's guard read.
 -- ---------------------------------------------------------------------------
 
-CREATE OR REPLACE FUNCTION _delta_open(p_doc_name TEXT, p_whole BOOLEAN)
+CREATE OR REPLACE FUNCTION _delta_open_framework(p_doc_name TEXT, p_whole BOOLEAN)
 RETURNS JSONB AS $$
 DECLARE
   v_def       _delta_docs;
@@ -445,6 +439,11 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql;
 
+-- the framework's, until dzql's compiler (`compileLedger`) sends each document
+-- it compiled to its own open, shown or whole
+CREATE OR REPLACE FUNCTION _delta_open(p_doc_name TEXT, p_whole BOOLEAN)
+RETURNS JSONB LANGUAGE sql AS $$ SELECT _delta_open_framework(p_doc_name, p_whole); $$;
+
 CREATE OR REPLACE FUNCTION delta_open(p_doc_name TEXT)
 RETURNS JSONB LANGUAGE sql AS $$ SELECT _delta_open(p_doc_name, FALSE); $$;