@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/core/interpolation.js

@@ -0,0 +1,191 @@
+/**
+ * What a tag does with its interpolations, in every dialect (chant #3196,
+ * #3212): splice plain values into the token list as SQL text while
+ * references stay `ref` tokens, render a span with its references written as
+ * names, record which props each spliced value fed, locate a parse error on
+ * its template line, and read column lineage off a view's select list.
+ *
+ * The dialect supplies its tokenizer rules, which values are its objects and
+ * column references, how a reference renders, and how a select-list name
+ * reads ({@link TemplateDialect}).
+ */
+import { isTrivia, tokenize, tokenizeText, untokenize } from "./tokens.js";
+import { interpolationLine, spliceText, SqlTemplateError } from "./template.js";
+/** Record that the spliced text inside `span` fed `path`. */
+export function feed(ctx, span, path) {
+    if (!span)
+        return;
+    for (let i = span.from; i < span.to; i++) {
+        const splice = ctx.tokens[i].splice;
+        if (splice !== undefined)
+            ctx.fed[splice].add(path);
+    }
+}
+/**
+ * Splice every interpolation that is not a reference into the token list as
+ * SQL text. References stay `ref` tokens for the parser and the entity to see.
+ */
+export function splice(d, tag, parts, values) {
+    const out = [];
+    for (const t of tokenize(parts, d.lexical)) {
+        if (t.kind !== "ref") {
+            out.push(t);
+            continue;
+        }
+        const value = values[t.part];
+        if (d.isObject(value) || d.isColumnRef(value)) {
+            out.push(t);
+            continue;
+        }
+        const text = spliceText(value);
+        if (typeof text !== "string") {
+            throw new SqlTemplateError(tag, `the interpolation on template line ${interpolationLine(parts, t.part)} is ${text.error}`, t.part, parts[t.part].length);
+        }
+        try {
+            for (const s of tokenizeText(text, t.part, d.lexical))
+                out.push({ ...s, splice: t.part });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new SqlTemplateError(tag, `the text interpolated on template line ${interpolationLine(parts, t.part)} does not tokenize: ${message}`, t.part, parts[t.part].length);
+        }
+    }
+    return out;
+}
+/** A span's text, interpolations rendered, trimmed. With `path`, the span's spliced text is recorded as feeding it. */
+export function spanText(ctx, span, path) {
+    if (!span || span.to <= span.from)
+        return undefined;
+    if (path)
+        feed(ctx, span, path);
+    return untokenize(ctx.tokens.slice(span.from, span.to), (i) => ctx.d.renderReference(ctx.values[i], i)).trim();
+}
+/** A parsed statement's unknown clauses as props carry them; undefined when there are none. */
+export function unparsedClauses(ctx, unknown) {
+    if (!unknown || unknown.length === 0)
+        return undefined;
+    const render = (i) => ctx.d.renderReference(ctx.values[i], i);
+    return unknown.map((u) => {
+        const before = untokenize(ctx.tokens.slice(0, u.span.from), render).replace(/^\s+/, "");
+        return {
+            clause: u.clause,
+            text: spanText(ctx, u.span, "unparsed") ?? u.clause,
+            ...(u.column !== undefined ? { column: u.column } : {}),
+            line: before.split("\n").length,
+        };
+    });
+}
+/** A parse error as the tag reports it: on the template line, or in the interpolated text it came from. */
+export function templateSyntaxError(tag, parts, err) {
+    const where = err.token?.splice !== undefined
+        ? `in the text interpolated on template line ${interpolationLine(parts, err.token.splice)}`
+        : `on template line ${parts.slice(0, err.part).join("${}").split("\n").length + parts[err.part].slice(0, err.offset).split("\n").length - 1}`;
+    return new SqlTemplateError(tag, `${err.message} (${where})`, err.part, err.offset);
+}
+/**
+ * Column-level lineage of a view's SELECT: one edge per item of the top-level
+ * select list. FROM, WHERE and GROUP BY stay text; the objects they
+ * interpolate land in `reads`. A column written by name inside the SQL is not
+ * lineage: only references are (#3047, "no parsing of SQL for names").
+ */
+export function lineage(ctx, select) {
+    const { d } = ctx;
+    const sig = [];
+    for (let i = select.from; i < select.to; i++)
+        if (!isTrivia(ctx.tokens[i]))
+            sig.push(i);
+    const tok = (i) => ctx.tokens[i];
+    const isKw = (i, w) => tok(i).kind === "ident" && tok(i).text.toUpperCase() === w;
+    let depth = 0;
+    let selectAt = -1;
+    let fromAt = sig.length;
+    const commas = [];
+    for (let k = 0; k < sig.length; k++) {
+        const t = tok(sig[k]);
+        if (t.kind === "punct" && t.text === "(")
+            depth++;
+        else if (t.kind === "punct" && t.text === ")")
+            depth--;
+        else if (depth === 0 && selectAt < 0 && isKw(sig[k], "SELECT")) {
+            selectAt = k;
+            if (sig[k + 1] !== undefined && isKw(sig[k + 1], "DISTINCT")) {
+                selectAt = k + 1;
+                // `DISTINCT ON (a, b)`: the parenthesized list is not a select-list item.
+                if (d.lineage?.distinctOn && sig[k + 2] !== undefined && isKw(sig[k + 2], "ON") && tok(sig[k + 3] ?? -1)?.text === "(") {
+                    let nest = 0;
+                    let j = k + 3;
+                    for (; j < sig.length; j++) {
+                        const x = tok(sig[j]);
+                        if (x.kind === "punct" && x.text === "(")
+                            nest++;
+                        else if (x.kind === "punct" && x.text === ")" && --nest === 0)
+                            break;
+                    }
+                    selectAt = j;
+                    k = j;
+                }
+            }
+            else if (sig[k + 1] !== undefined && d.lineage?.distinctOn && isKw(sig[k + 1], "ALL"))
+                selectAt = k + 1;
+        }
+        else if (depth === 0 && selectAt >= 0 && fromAt === sig.length && isKw(sig[k], "FROM"))
+            fromAt = k;
+        else if (depth === 0 && selectAt >= 0 && fromAt === sig.length && t.kind === "punct" && t.text === ",")
+            commas.push(k);
+    }
+    const edges = [];
+    if (selectAt >= 0) {
+        const bounds = [selectAt, ...commas, fromAt];
+        for (let b = 0; b + 1 < bounds.length; b++) {
+            const items = sig.slice(bounds[b] + 1, bounds[b + 1]);
+            if (items.length === 0)
+                continue;
+            let output;
+            let exprItems = items;
+            const asAt = items.findIndex((i) => isKw(i, "AS"));
+            if (asAt >= 0 && asAt === items.length - 2) {
+                output = d.identValue(tok(items[asAt + 1]).text);
+                exprItems = items.slice(0, asAt);
+            }
+            else if (items.length === 1) {
+                const t = tok(items[0]);
+                if (t.kind === "ref" && d.isColumnRef(ctx.values[t.part]))
+                    output = ctx.values[t.part].attribute;
+                else if (t.kind === "ident" || t.kind === "qident")
+                    output = d.identValue(t.text);
+            }
+            else if (items.length === 3 && tok(items[1]).text === "." && (tok(items[2]).kind === "ident" || tok(items[2]).kind === "qident")) {
+                output = d.identValue(tok(items[2]).text);
+            }
+            else if (d.lineage?.qualifiedRefs && items.length === 3 && tok(items[1]).text === "." && tok(items[2]).kind === "ref" && d.isColumnRef(ctx.values[tok(items[2]).part])) {
+                // `alias.${t.columns.c}` names its output after the column.
+                output = ctx.values[tok(items[2]).part].attribute;
+            }
+            else if (d.lineage?.aliasWithoutAs && items.length >= 2) {
+                // `expr name`: an alias without AS. The name follows an operand, never an operator or `.`.
+                const last = tok(items[items.length - 1]);
+                const before = tok(items[items.length - 2]);
+                const keyword = (t) => (t.kind === "ident" ? d.lineage?.keyword?.(t) : undefined);
+                const operandEnd = before.kind === "ref" || before.kind === "string" || before.kind === "number" || before.kind === "qident" || before.kind === "param" ||
+                    (before.kind === "ident" && keyword(before) === undefined) ||
+                    (before.kind === "punct" && (before.text === ")" || before.text === "]"));
+                const label = last.kind === "qident" || (last.kind === "ident" && keyword(last) !== "reserved");
+                if (label && operandEnd) {
+                    output = d.identValue(last.text);
+                    exprItems = items.slice(0, -1);
+                }
+            }
+            if (output === undefined && d.lineage?.outputOf)
+                output = d.lineage.outputOf(exprItems.map(tok), (t) => (t.kind === "ref" ? ctx.values[t.part] : undefined));
+            const refs = exprItems.filter((i) => tok(i).kind === "ref").map((i) => tok(i).part);
+            const exprSpan = { from: exprItems[0], to: exprItems[exprItems.length - 1] + 1, refs };
+            edges.push({
+                output: output ?? d.unnamedOutput(b + 1),
+                expr: spanText(ctx, exprSpan) ?? "",
+                from: [...new Set(refs.map((i) => ctx.values[i]).filter((v) => d.isColumnRef(v)))],
+            });
+        }
+    }
+    const reads = [...new Set(select.refs.map((i) => ctx.values[i]).filter((v) => d.isObject(v)))];
+    return { edges, reads };
+}

package/dist/core/normalize.js

@@ -0,0 +1,43 @@
+/**
+ * Normalization helpers that hold in every dialect. A dialect's normalization
+ * undoes what its own server rewrites (quoting, type aliases, default
+ * levels), by rule over its own parse; these are the pieces that are not any
+ * one database's grammar.
+ */
+/**
+ * The name in a `-- previously: <name>` comment, when the text holds one: the
+ * rename hint, before a `CREATE` for an object or on a column's line for a
+ * column. The name may be quoted with backquotes or double quotes.
+ */
+export function previouslyIn(comments) {
+    for (const c of comments) {
+        const m = /^--\s*previously\s*:\s*([`"]?)([^\s`"]+)\1\s*$/i.exec(c.trim());
+        if (m)
+            return m[2];
+    }
+    return undefined;
+}
+/**
+ * Split canonical text (tokens joined by single spaces) on its top-level
+ * commas, outside parentheses and brackets.
+ */
+export function splitTopLevel(text) {
+    const parts = [];
+    let depth = 0;
+    let cur = [];
+    for (const tok of text.split(" ")) {
+        if (tok === "(" || tok === "[")
+            depth++;
+        if (tok === ")" || tok === "]")
+            depth--;
+        if (tok === "," && depth === 0) {
+            parts.push(cur.join(" "));
+            cur = [];
+        }
+        else
+            cur.push(tok);
+    }
+    if (cur.length)
+        parts.push(cur.join(" "));
+    return parts.filter((p) => p.length > 0);
+}

package/dist/core/ownership.js

@@ -0,0 +1,119 @@
+/**
+ * chant's ownership marker as a trailer on an object's own comment, in every
+ * dialect that can comment on its objects (#3208).
+ *
+ * The marker never replaces the user's comment, which is a declared property.
+ * It is appended as a bracketed trailer,
+ *
+ *     Raw events [chant managed-by=chant stack=shop env=prod]
+ *
+ * and taken off again wherever chant reads a definition, so planning, the deep
+ * diff and import compare and write the declared comment alone. Someone who
+ * edits the comment by hand and drops the trailer makes the object read as
+ * foreign, which is the safe direction: it is never pruned, and the next apply
+ * of its declaration stamps it again.
+ *
+ * Values are percent-encoded outside `[A-Za-z0-9._-]`, so the trailer never
+ * holds a quote, a backslash, a space or a bracket of its own.
+ *
+ * Where the comment lives in a statement, and so how a trailer comes off a
+ * printed `CREATE`, is the dialect's grammar and stays with the dialect.
+ */
+import { OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+/** The keys inside the trailer. */
+export const COMMENT_OWNERSHIP_KEYS = {
+    managedBy: "managed-by",
+    stack: "stack",
+    env: "env",
+};
+/**
+ * The trailer key on the objects that hold effect receipts. Like a
+ * migration's working objects, they are chant's own bookkeeping and never
+ * part of a declared schema.
+ */
+export const RECEIPTS_TRAILER_KEY = "receipts";
+const VALUE = "[A-Za-z0-9._%-]*";
+/** One `key=value` pair of a trailer, as a regular expression source. */
+export const TRAILER_PAIR = `[A-Za-z0-9._-]+=${VALUE}`;
+/** The trailer at the end of a comment's text. */
+const TRAILER = new RegExp(`(?:^|\\s+)\\[chant((?: ${TRAILER_PAIR})+)\\]$`);
+const encode = (v) => v.replace(/[^A-Za-z0-9._-]/g, (c) => [...new TextEncoder().encode(c)].map((b) => `%${b.toString(16).toUpperCase().padStart(2, "0")}`).join(""));
+const decode = (v) => {
+    try {
+        return decodeURIComponent(v);
+    }
+    catch {
+        return v;
+    }
+};
+/**
+ * The trailer for a marker: `[chant managed-by=chant stack=<stack> env=<env>]`.
+ * `extra` appends more pairs after the marker's own; a migration Op uses them
+ * to say which migration an object it made belongs to.
+ * Keys are `[A-Za-z0-9._-]+`; values are encoded like the rest.
+ */
+export function markerTrailer(marker, extra = {}) {
+    const k = COMMENT_OWNERSHIP_KEYS;
+    const pairs = [`${k.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE}`];
+    if (marker?.stack)
+        pairs.push(`${k.stack}=${encode(marker.stack)}`);
+    if (marker?.env)
+        pairs.push(`${k.env}=${encode(marker.env)}`);
+    for (const [key, value] of Object.entries(extra)) {
+        if (!/^[A-Za-z0-9._-]+$/.test(key))
+            throw new Error(`ownership trailer key ${JSON.stringify(key)} is not [A-Za-z0-9._-]+`);
+        pairs.push(`${key}=${encode(value)}`);
+    }
+    return `[chant ${pairs.join(" ")}]`;
+}
+/** A comment's text with the trailer taken off. */
+export function stripMarker(comment) {
+    return comment.replace(TRAILER, "");
+}
+/** The comment to set: the declared comment, then the trailer (with `extra` pairs, see {@link markerTrailer}). */
+export function stampedComment(declared, marker, extra) {
+    const own = stripMarker(declared ?? "");
+    return own ? `${own} ${markerTrailer(marker, extra)}` : markerTrailer(marker, extra);
+}
+/** Every pair in a comment's trailer, decoded, or undefined when it has no trailer. */
+export function readTrailerPairs(comment) {
+    const m = TRAILER.exec(comment ?? "");
+    if (!m)
+        return undefined;
+    return new Map(m[1]
+        .trim()
+        .split(" ")
+        .map((p) => {
+        const at = p.indexOf("=");
+        return [p.slice(0, at), decode(p.slice(at + 1))];
+    }));
+}
+/** Whether a comment carries chant's managed-by marker and any of `keys` in its trailer. */
+export function hasChantTrailerKey(comment, keys) {
+    const pairs = readTrailerPairs(comment);
+    return pairs?.get(COMMENT_OWNERSHIP_KEYS.managedBy) === OWNERSHIP_MANAGED_BY_VALUE && keys.some((k) => pairs.has(k));
+}
+/** The marker a comment carries, or undefined when it carries none. */
+export function readMarker(comment) {
+    const pairs = readTrailerPairs(comment);
+    if (!pairs)
+        return undefined;
+    const k = COMMENT_OWNERSHIP_KEYS;
+    const managedBy = pairs.get(k.managedBy);
+    if (managedBy === undefined)
+        return undefined;
+    const stack = pairs.get(k.stack);
+    const env = pairs.get(k.env);
+    return { managedBy, ...(stack ? { stack } : {}), ...(env ? { env } : {}) };
+}
+/** Whether a comment carries chant's managed-by marker. */
+export function isChantManaged(comment) {
+    return readMarker(comment)?.managedBy === OWNERSHIP_MANAGED_BY_VALUE;
+}
+/** Whether the comment's marker is exactly this project's: managed by chant, same stack, same env. */
+export function carriesMarker(comment, marker) {
+    const m = readMarker(comment);
+    if (m?.managedBy !== OWNERSHIP_MANAGED_BY_VALUE)
+        return false;
+    return (m.stack ?? undefined) === (marker?.stack || undefined) && (m.env ?? undefined) === (marker?.env || undefined);
+}

package/dist/core/receipts.js

@@ -0,0 +1,22 @@
+/**
+ * Effect receipts kept on the database server itself, in every dialect
+ * (concepts/effect-receipts.mdx).
+ *
+ * A receipt is the proof that one effect ran, kept where the effect happened.
+ * A migration Op's backfill copies data on the server, so its receipts are
+ * rows on the same server, bound to the object they witness, and read and
+ * written over the connection the copy already uses. They die with the data
+ * when the Op's onFailure drops it, which a receipt kept in git would not.
+ *
+ * A dialect's store implements this interface over its own client and keeps
+ * the receipts in a table whose comment carries the ownership trailer with
+ * the `receipts` key (`./ownership.ts`), so schema reads leave it out. A
+ * migration's store is reached by its backfill directly. The store `effect()`
+ * steps use (`../receipts.ts`) is registered as the `receiptRead` /
+ * `receiptWrite` activities only as a fallback, so it never takes over
+ * another configured lexicon's receipt row.
+ */
+/** The receipt's address: `<stack>/<env>/<effect>`, the same fields an ownership marker carries. */
+export function receiptAddress(identity, effect) {
+    return `${identity.stack || "-"}/${identity.env || "-"}/${effect}`;
+}

package/dist/core/references.js

@@ -0,0 +1,61 @@
+/**
+ * References between schema objects, in every dialect: column lineage, the
+ * name a reference is written under in a build's output, and the order
+ * objects are created in.
+ */
+import { isAttrRefLike } from "@intentius/chant/utils";
+/**
+ * A reference as a build's output writes it: an entity's export name, or
+ * `export.column` for a column. Undefined when the target is not exported.
+ */
+export function referenceName(value, names) {
+    if (isAttrRefLike(value)) {
+        const parent = value.parent.deref();
+        const owner = parent ? names.get(parent) : undefined;
+        return owner ? `${owner}.${value.attribute}` : undefined;
+    }
+    return names.get(value);
+}
+/** Lineage edges with their column references written as `export.column`. */
+export function lineageJson(edges, names) {
+    return edges.map((e) => ({
+        output: e.output,
+        expr: e.expr,
+        from: e.from.map((r) => referenceName(r, names) ?? null),
+    }));
+}
+/**
+ * Export names in creation order: an object after everything it references,
+ * and after the names in `extra` (an object read from a `.sql` file that a
+ * template names as text, `../sql-files.ts`).
+ * Ties break by export name, so the order is the same however the files were
+ * discovered. A reference cycle is an error naming the cycle.
+ */
+export function applyOrder(objects, names, extra) {
+    const deps = new Map();
+    for (const [name, obj] of objects) {
+        const on = new Set(extra?.get(name)?.filter((d) => d !== name && objects.has(d)) ?? []);
+        for (const ref of obj.dependsOn) {
+            const parent = isAttrRefLike(ref) ? ref.parent.deref() : ref;
+            const dep = parent ? names.get(parent) : undefined;
+            if (dep !== undefined && dep !== name && objects.has(dep))
+                on.add(dep);
+        }
+        deps.set(name, [...on].sort());
+    }
+    const order = [];
+    const done = new Set();
+    const visit = (n, stack) => {
+        if (done.has(n))
+            return;
+        if (stack.includes(n))
+            throw new Error(`sql: a reference cycle between schema objects: ${[...stack, n].join(" -> ")}`);
+        for (const d of deps.get(n) ?? [])
+            visit(d, [...stack, n]);
+        done.add(n);
+        order.push(n);
+    };
+    for (const n of [...objects.keys()].sort())
+        visit(n, []);
+    return order;
+}

package/dist/core/statements.js

@@ -0,0 +1,42 @@
+/**
+ * The statements a schema change takes, rendered offline (#3644), the same
+ * shape in every dialect: what `diffStatements`
+ * (`../migration-statements.ts`) returns and `chant sql diff --statements
+ * --json` prints, for a migration file to hold.
+ *
+ * Every value is plain JSON: strings, booleans, arrays and objects, no
+ * `undefined` left in, so the document reads back as it was written. Steps
+ * are in the order they run.
+ */
+/** A classified change as a step names it, with no `undefined` fields. */
+export function statementChange(c) {
+    return {
+        rule: c.rule,
+        class: c.class,
+        field: c.field,
+        ...(c.before !== undefined ? { before: c.before } : {}),
+        ...(c.after !== undefined ? { after: c.after } : {}),
+        ...(c.destructive ? { destructive: true } : {}),
+        ...(c.note !== undefined ? { note: c.note } : {}),
+    };
+}
+/** The steps as a migration file's SQL: each statement after a comment naming its object, rule and class; an Op or manual step as a comment. */
+export function renderStatements(doc) {
+    const out = [];
+    for (const s of doc.steps) {
+        if (s.kind === "statement") {
+            const notes = [s.transactional || doc.dialect !== "postgres" ? "" : "outside a transaction", s.waitsForMutation ? "waits for its mutation" : "", s.destructive ? "destructive" : ""].filter(Boolean);
+            out.push(`-- ${s.object} (${s.name}): ${s.rule} ${s.class}${notes.length ? `, ${notes.join(", ")}` : ""}`);
+            if (s.precheck)
+                out.push(`-- pre-check, must return 0 (${s.precheck.detail}): ${s.precheck.sql}`);
+            out.push(`${s.sql};`, "");
+        }
+        else if (s.kind === "op") {
+            out.push(`-- ${s.object} (${s.name}): ${s.changes.map((c) => c.rule).join(", ")} made by ${s.op}, not a statement:`, `--   ${s.declaration}`, "");
+        }
+        else {
+            out.push(`-- ${s.object} (${s.name}): ${s.changes.map((c) => c.rule).join(", ")} has no statement and no Op: ${s.detail}`, "");
+        }
+    }
+    return out.join("\n");
+}

package/dist/core/template.js

@@ -0,0 +1,79 @@
+/**
+ * The tagged-template plumbing every dialect's tags share: reading a
+ * template's raw parts, what a non-reference interpolation splices in, and
+ * the error a tag throws with the template line it happened on.
+ *
+ * Tokenizing and parsing the spliced statement is the dialect's own.
+ */
+/** A spliced value meant as a string literal. A dialect's `literal()` makes one with its own quoting. */
+export class SqlLiteral {
+    constructor(sql) {
+        this.sql = sql;
+        Object.freeze(this);
+    }
+}
+/** An error from a tag: the statement kind, the template line, and what went wrong. */
+export class SqlTemplateError extends Error {
+    constructor(tag, message, part, offset) {
+        super(`${tag}\`...\`: ${message}`);
+        this.part = part;
+        this.offset = offset;
+        this.name = "SqlTemplateError";
+    }
+}
+/**
+ * A template's parts as the SQL reads them: the raw text, so a backslash in a
+ * regex or an escape stays as written, with the two escapes a template
+ * literal forces undone. `` \` `` is a backquote and `\${` is `${`; neither
+ * can be written in a template any other way.
+ */
+export function templateParts(strings) {
+    const raw = strings.raw ?? strings;
+    return raw.map(unescapeTemplateDelimiters);
+}
+export function unescapeTemplateDelimiters(part) {
+    return part.replace(/\\(`|\$\{)/g, "$1");
+}
+/** Where interpolation `index` sits in the template, for a message: the line of the template it is on. */
+export function interpolationLine(parts, index) {
+    return parts.slice(0, index + 1).join("${}").split("\n").length;
+}
+/** A value's kind, for a message. */
+export function describeValue(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return typeof value === "object" ? `an object (${Object.prototype.toString.call(value)})` : `a ${typeof value}`;
+}
+/**
+ * The SQL text a non-reference value splices in, or an error message: a
+ * string is SQL text, a number, bigint or boolean its literal, `null` is
+ * `NULL`, a {@link SqlLiteral} its quoted form. Anything else has no SQL form.
+ */
+export function spliceText(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? String(value) : { error: `the number ${value} has no SQL form` };
+    }
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (value === null)
+        return "NULL";
+    if (value instanceof SqlLiteral)
+        return value.sql;
+    if (value === undefined) {
+        return {
+            error: "undefined. A column is referenced through `.columns` (`${events.columns.user_id}`, not " +
+                "`${events.user_id}`), and a column name that does not exist is undefined too",
+        };
+    }
+    return { error: `${describeValue(value)}, which has no SQL form` };
+}
+/** `o` without its `undefined` and `false` fields, so props hold only what the DDL says. */
+export const stripUnset = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined && v !== false));

package/dist/core/testing/http-stub.js

@@ -0,0 +1,21 @@
+/**
+ * A stand-in HTTP server for tests, in every dialect: listens on a random
+ * loopback port and answers each request's body with what `answer` returns.
+ * A dialect's fake server (the ClickHouse HTTP interface answering its
+ * catalog reads) is built on it. Not a SQL engine.
+ */
+import { createServer } from "node:http";
+export async function startHttpStub(answer) {
+    const server = createServer((req, res) => {
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", () => {
+            const { status, text } = answer(body, req);
+            res.statusCode = status;
+            res.end(text);
+        });
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", () => r()));
+    const { port } = server.address();
+    return { url: `http://127.0.0.1:${port}`, close: () => new Promise((r) => server.close(() => r())) };
+}