@mason-data/cli 0.0.0-stage → 0.6.2

package/dist/src/duck/late.js

@@ -0,0 +1,221 @@
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const kindOf = (n) => isObject(n) ? Object.keys(n)[0] ?? null : null;
+const bodyOf = (n) => n[kindOf(n)];
+const S = (sval) => ({ String: { sval } });
+const ref = (...names) => ({ ColumnRef: { fields: names.map(S) } });
+const LATE = "__mason_late";
+/** what may stand in a select list that is computed after the limit: one value per row, reading its row alone */
+const ROW_WISE = new Set(["ColumnRef", "A_Const", "ParamRef", "FuncCall", "TypeCast", "A_Expr", "BoolExpr", "CaseExpr", "CaseWhen",
+    "CoalesceExpr", "NullTest", "BooleanTest", "MinMaxExpr", "A_ArrayExpr", "A_Indirection", "A_Indices", "CollateClause", "NamedArgExpr",
+    "RowExpr", "SQLValueFunction", "TypeName", "String", "Integer", "Float", "Boolean", "List"]);
+/** DuckDB's set-returning functions: a row each would be many */
+const SETS = new Set(["unnest", "generate_series", "range", "generate_subscripts", "json_each", "json_tree"]);
+/** Postgres's analysis: no query of the statement aggregates, windows, returns sets from its list or holds a subquery
+ *  expression — so every row of every SELECT is one row of its FROM, and a select list reads its own row alone */
+function rowWiseStatement(tree) {
+    let queries = 0, ok = true;
+    const visit = (v) => {
+        if (!ok)
+            return;
+        if (Array.isArray(v)) {
+            for (const x of v)
+                visit(x);
+            return;
+        }
+        if (v === null || typeof v !== "object")
+            return;
+        if (v._node === "QUERY") {
+            queries++;
+            for (const f of ["hasAggs", "hasWindowFuncs", "hasTargetSRFs", "hasSubLinks"])
+                if (v[f] !== "false") {
+                    ok = false;
+                    return;
+                }
+        }
+        for (const [k, x] of Object.entries(v))
+            if (k !== "_node")
+                visit(x);
+    };
+    visit(tree);
+    return ok && queries > 0;
+}
+/** every node of a select-list expression is row-wise, and it computes something (a plain column needs no deferring) */
+function rowWise(n) {
+    let ok = true, computes = false;
+    const visit = (v) => {
+        if (!ok)
+            return;
+        if (Array.isArray(v)) {
+            v.forEach(visit);
+            return;
+        }
+        if (!isObject(v))
+            return;
+        const k = kindOf(v);
+        if (/^[A-Z]/.test(k) && isObject(v[k])) {
+            if (!ROW_WISE.has(k)) {
+                ok = false;
+                return;
+            }
+            const b = bodyOf(v);
+            if (k === "FuncCall") {
+                const name = b.funcname.map((x) => bodyOf(x).sval).join(".").toLowerCase();
+                if (b.over !== undefined || b.agg_star === true || b.agg_distinct === true || b.agg_order !== undefined || b.agg_filter !== undefined || SETS.has(name)) {
+                    ok = false;
+                    return;
+                }
+            }
+            if (k === "ColumnRef" && b.fields.some((f) => kindOf(f) === "A_Star")) {
+                ok = false;
+                return;
+            }
+            if (k !== "ColumnRef" && k !== "A_Const" && k !== "ParamRef" && k !== "String" && k !== "Integer" && k !== "Float" && k !== "Boolean")
+                computes = true;
+            for (const x of Object.values(b))
+                visit(x);
+            return;
+        }
+        for (const x of Object.values(v))
+            visit(x);
+    };
+    visit(n);
+    return { ok, computes };
+}
+/** the same tree with every ColumnRef replaced by `__mason_late.<the column it is read as>` */
+function overLate(n, columns) {
+    if (Array.isArray(n))
+        return n.map((x) => overLate(x, columns));
+    if (!isObject(n))
+        return n;
+    if (kindOf(n) === "ColumnRef" && isObject(n.ColumnRef)) {
+        const key = JSON.stringify(n.ColumnRef.fields);
+        let name = columns.get(key);
+        if (name === undefined) {
+            name = `__mason_c${columns.size + 1}`;
+            columns.set(key, name);
+        }
+        return ref(LATE, name);
+    }
+    return Object.fromEntries(Object.entries(n).map(([k, v]) => [k, overLate(v, columns)]));
+}
+/**
+ * The statement with every sorted, limited SELECT written with its select list computed after its limit (see above),
+ * or null where none is. `tree` is the rewrite's DuckDB tree, `analysis` Postgres's of the original.
+ */
+export function selectListAfterLimit(tree, analysis) {
+    if (!rowWiseStatement(analysis))
+        return null;
+    let changed = false;
+    // bottom up: a SELECT's derived tables and WITH queries first, then the SELECT (never what it was written as)
+    const visit = (n) => {
+        if (Array.isArray(n))
+            return n.map(visit);
+        if (!isObject(n))
+            return n;
+        const out = Object.fromEntries(Object.entries(n).map(([k, v]) => [k, visit(v)]));
+        if (kindOf(out) !== "SelectStmt")
+            return out;
+        // a set operation's arms are SELECT bodies of their own (libpg-query writes them unwrapped)
+        const body = bodyOf(out);
+        for (const arm of ["larg", "rarg"]) {
+            if (!isObject(body[arm]))
+                continue;
+            const late = afterLimit({ SelectStmt: body[arm] });
+            if (late !== null) {
+                body[arm] = bodyOf(late);
+                changed = true;
+            }
+        }
+        const late = afterLimit(out);
+        if (late === null)
+            return out;
+        changed = true;
+        return late;
+    };
+    const written = visit(tree);
+    return changed ? written : null;
+}
+/** one SELECT written so, or null where it is not so shaped */
+function afterLimit(select) {
+    const s = bodyOf(select);
+    if (s.op !== undefined && s.op !== "SETOP_NONE")
+        return null;
+    for (const f of ["withClause", "distinctClause", "groupClause", "havingClause", "windowClause", "lockingClause", "intoClause", "valuesLists"]) {
+        if (s[f] !== undefined && !(Array.isArray(s[f]) && s[f].length === 0))
+            return null;
+    }
+    if (s.limitCount === undefined || (s.limitOption !== undefined && s.limitOption !== "LIMIT_OPTION_COUNT" && s.limitOption !== "LIMIT_OPTION_DEFAULT"))
+        return null;
+    const targets = s.targetList;
+    const sorts = s.sortClause;
+    if (targets === undefined || sorts === undefined || sorts.length === 0)
+        return null;
+    let computes = false;
+    for (const t of targets) {
+        if (kindOf(t) !== "ResTarget")
+            return null;
+        const r = rowWise(bodyOf(t).val);
+        if (!r.ok)
+            return null;
+        computes ||= r.computes;
+    }
+    if (!computes)
+        return null;
+    // each sort key as an expression over the FROM clause: an ordinal or an output column's name is that output's own
+    // expression, as Postgres reads it (an output name before an input column's)
+    const outputName = (t) => {
+        const b = bodyOf(t);
+        if (typeof b.name === "string")
+            return b.name;
+        const v = b.val;
+        if (kindOf(v) === "ColumnRef") {
+            const last = bodyOf(v).fields.at(-1);
+            return kindOf(last) === "String" ? bodyOf(last).sval : null;
+        }
+        return null;
+    };
+    const keys = [];
+    for (const sort of sorts) {
+        if (kindOf(sort) !== "SortBy")
+            return null;
+        const b = bodyOf(sort);
+        if (b.useOp !== undefined)
+            return null;
+        const node = b.node;
+        let target;
+        if (kindOf(node) === "A_Const" && isObject(bodyOf(node).ival)) {
+            target = targets[Number(bodyOf(node).ival.ival ?? 0) - 1];
+            if (target === undefined)
+                return null;
+        }
+        else if (kindOf(node) === "ColumnRef" && bodyOf(node).fields.length === 1) {
+            const name = bodyOf(bodyOf(node).fields[0]).sval;
+            const named = targets.filter((t) => outputName(t) === name);
+            if (named.length > 1)
+                return null;
+            target = named[0];
+        }
+        if (target !== undefined) {
+            // a sort by a computed output computes it for every row anyway: nothing to defer
+            if (rowWise(bodyOf(target).val).computes)
+                return null;
+            keys.push(structuredClone(bodyOf(target).val));
+        }
+        else if (kindOf(node) === "A_Const")
+            return null;
+        else
+            keys.push(structuredClone(node));
+    }
+    const columns = new Map();
+    const list = targets.map((t) => ({ ResTarget: { ...bodyOf(t), val: overLate(bodyOf(t).val, columns) } }));
+    const inner = { ...s, targetList: [
+            ...[...columns].map(([fields, name]) => ({ ResTarget: { name, val: { ColumnRef: { fields: JSON.parse(fields) } } } })),
+            ...keys.map((k, i) => ({ ResTarget: { name: `__mason_o${i + 1}`, val: k } })),
+        ], sortClause: sorts.map((sort, i) => ({ SortBy: { ...bodyOf(sort), node: keys[i] } })) };
+    return { SelectStmt: {
+            targetList: list,
+            fromClause: [{ RangeSubselect: { subquery: { SelectStmt: inner }, alias: { aliasname: LATE } } }],
+            sortClause: sorts.map((sort, i) => ({ SortBy: { ...bodyOf(sort), node: ref(LATE, `__mason_o${i + 1}`) } })),
+            limitOption: "LIMIT_OPTION_DEFAULT", op: "SETOP_NONE",
+        } };
+}

package/dist/src/duck/libc-order.js

@@ -0,0 +1,190 @@
+/**
+ * TEXT IN A GLIBC LOCALE'S ORDER, MEASURED FROM THE SOURCE (the BI-tools test of #517: Metabase's field lists
+ * under en_US.utf8 listed Hangul, `$` / `€` and U+FFFD elsewhere than Postgres, and `s < 'b'` counted other rows). The
+ * order was emulated from assumptions until then — ICU's order of the letters and digits, the rest ignored, then the
+ * punctuation by its bytes — and glibc differs from each: Hangul has no letter weight in it, `$` and `€` have one where
+ * `@` and `~` have none, U+FFFD sorts after the letters. So the order is no longer assumed: it is READ from the source
+ * database, once (read-only SELECTs, a few seconds), kept in the copy (`mason.libc_order`, src/duck/store.ts), read again
+ * when the database's collation version moves (`pg_database.datcollversion`: glibc's), and every sort key is built from it.
+ *
+ * What glibc compares, as measured (Postgres 18 / glibc 2.41 en_US.utf8, the disposable server's):
+ *  1. the FIRST level: a weight per character that has one (letters, digits, `$`, U+FFFD; not punctuation, Hangul or
+ *     spaces), compared in order. Read as CLASSES: the characters in the database's order, two neighbours x < y in one
+ *     class when x||'b' > y||'a' (only the second character told them apart). A character equal there to a string of
+ *     others (ß = ss, æ = ae, fi = fi) is that string: proposed by its compatibility decomposition, kept only when the
+ *     source says it is equal;
+ *  2. accents, then 3. case: ICU's second and third levels over the characters of level 1 (the source's own agree
+ *     with them over everything the sample below holds; nothing here reads them from the source);
+ *  4. the LAST level: for each character that has a weight there (punctuation, spaces, Hangul's one shared weight,
+ *     Latin letters; not CJK), the pair (its position in the string, its weight), position first — `三 < :三` (`三` has
+ *     none) and `가三 < 三가` both follow. The punctuation's weights are their order (they differ in nothing else); a
+ *     character of level 1 is placed among them by binary search (p||x < x exactly when p's weight is below x's), and
+ *     one placed below all of them has none when x||chr(1) is not below chr(1)||x;
+ *  5. a tie at every level is Postgres's byte order (`varstr_cmp`'s strcmp), which the caller adds.
+ * Held against the source's ORDER BY over 30,000 random strings of 17 scripts and symbol sets: 2 out of order, both
+ * full-width digits beside Hangul. Not covered, so REFUSED by name when a value holding one is ordered
+ * (`libc-uncovered`): a combining mark (glibc weighs `e` + U+0301 otherwise than ICU), a Thai or Lao vowel written
+ * before its consonant (glibc reorders them), a code point this Node does not know as assigned, a private use one. A
+ * known difference (`libc-symbol-punctuation`): punctuation right after a digit or symbol outranks a case difference
+ * after it in glibc (`1-X < 1x`), and not here.
+ */
+import { gapMark } from "./gaps.js";
+import { PgEvalError } from "./pg-eval.js";
+const MAX = 0x110000;
+/** The code points read from the source: assigned, not private use, not a surrogate (the rest are uncovered). */
+export function assignedCodePoints() {
+    const out = [];
+    for (let g = 1; g < MAX; g++) {
+        if (g >= 0xd800 && g <= 0xdfff)
+            continue;
+        if (/[\p{Cn}\p{Co}]/u.test(String.fromCodePoint(g)))
+            continue;
+        out.push(g);
+    }
+    return out;
+}
+/** what glibc orders otherwise than this ordering: combining marks, Thai and Lao vowels written before their consonant */
+const UNCOVERED = /[\p{M}เ-ไເ-ໄ]/u;
+const ints = (xs) => `'{${xs.join(",")}}'::int[]`;
+const texts = (xs) => `ARRAY[${xs.map((x) => `'${x.replaceAll("'", "''")}'`).join(",")}]::text[]`;
+/** Reads the source database's order of text (its default collation), as the module's header says. */
+export async function readLibcOrder(query, collate, version) {
+    const points = assignedCodePoints();
+    const l1 = new Uint32Array(MAX), l4 = new Uint32Array(MAX), uncovered = new Uint8Array(MAX).fill(1);
+    // each character: whether it has a first-level weight ('b'||c < 'ba' and c||'b' > 'aa' only for one that has none);
+    // those that have one in the database's order, each marked when its neighbour below is of its class; the rest in
+    // the database's order, each marked when its neighbour below has the same last-level weight (pp > c only then)
+    const rows = await query(`WITH c AS (SELECT g, chr(g) AS ch FROM unnest(${ints(points)}) AS u(g)),
+    k AS (SELECT g, ch, ('b' || ch < 'ba') AND (ch || 'b' > 'aa') AS ignored FROM c),
+    n AS (SELECT g, ch, lag(ch) OVER (ORDER BY ch) AS prev, row_number() OVER (ORDER BY ch) AS pos FROM k WHERE NOT ignored),
+    i AS (SELECT g, ch, lag(ch) OVER (ORDER BY ch) AS prev, row_number() OVER (ORDER BY ch) AS pos FROM k WHERE ignored)
+    SELECT 'n', g::text, coalesce(prev || 'b' > ch || 'a', false)::text, pos::text FROM n
+    UNION ALL SELECT 'i', g::text, coalesce(prev || prev > ch, false)::text, pos::text FROM i`);
+    // each kind in the database's order
+    rows.sort((a, b) => a[0] === b[0] ? Number(a[3]) - Number(b[3]) : a[0] < b[0] ? -1 : 1);
+    const weighted = [];
+    const ignoredClasses = []; // one character per last-level weight of the ignored ones, in order
+    let k = 0;
+    for (const [kind, g0, same] of rows) {
+        const g = Number(g0);
+        uncovered[g] = UNCOVERED.test(String.fromCodePoint(g)) ? 1 : 0;
+        if (kind === "n") {
+            if (same !== "true")
+                k++;
+            l1[g] = k;
+            weighted.push(g);
+        }
+        else {
+            if (same !== "true" || ignoredClasses.length === 0)
+                ignoredClasses.push(g);
+            l4[g] = 2 * ignoredClasses.length;
+        }
+    }
+    if (weighted.length === 0 || ignoredClasses.length === 0)
+        throw new Error(`reading how the database orders text (${collate}) found no ${weighted.length === 0 ? "letters" : "punctuation"}: Mason cannot sort text as it does`);
+    // expansions: proposed by each character's compatibility decomposition (its marks dropped) and the letters NFKD keeps
+    // whole, kept where the source says the two are equal at the first level (each sorts after the other given a later b)
+    const proposed = [];
+    for (const g of weighted) {
+        const d = String.fromCodePoint(g).normalize("NFKD").replace(/\p{M}/gu, "");
+        if ([...d].length > 1 && !d.includes("\0"))
+            proposed.push([g, d]);
+    }
+    for (const [ch, e] of [["ß", "ss"], ["ẞ", "SS"], ["æ", "ae"], ["Æ", "AE"], ["œ", "oe"], ["Œ", "OE"], ["þ", "th"], ["Þ", "TH"]])
+        proposed.push([ch.codePointAt(0), e]);
+    const expansions = new Map();
+    for (let at = 0; at < proposed.length; at += 5000) {
+        const part = proposed.slice(at, at + 5000);
+        const eq = await query(`SELECT g::text, ((chr(g) || 'b' > e || 'a') AND (e || 'b' > chr(g) || 'a'))::text FROM unnest(${ints(part.map((p) => p[0]))}, ${texts(part.map((p) => p[1]))}) AS u(g, e)`);
+        eq.forEach(([g, yes], j) => { if (yes === "true")
+            expansions.set(Number(g), [...part[j][1]].map((c) => c.codePointAt(0))); });
+    }
+    // each first-level character's last-level weight, among the ignored ones' by binary search
+    const lo = new Int32Array(weighted.length), hi = new Int32Array(weighted.length).fill(ignoredClasses.length);
+    for (;;) {
+        const idx = [], mid = [];
+        for (let i = 0; i < weighted.length; i++)
+            if (lo[i] < hi[i]) {
+                idx.push(i);
+                mid.push((lo[i] + hi[i]) >> 1);
+            }
+        if (idx.length === 0)
+            break;
+        const below = await query(`SELECT (chr(p) || chr(x) < chr(x))::text FROM unnest(${ints(mid.map((m) => ignoredClasses[m]))}, ${ints(idx.map((i) => weighted[i]))}) WITH ORDINALITY AS u(p, x, n) ORDER BY n`);
+        below.forEach(([b], j) => { const i = idx[j]; if (b === "true")
+            lo[i] = mid[j] + 1;
+        else
+            hi[i] = mid[j]; });
+    }
+    const bottom = [];
+    weighted.forEach((g, i) => { l4[g] = 2 * lo[i] + 1; if (lo[i] === 0)
+        bottom.push(g); });
+    if (bottom.length) {
+        const has = await query(`SELECT x::text, (chr(x) || chr(1) < chr(1) || chr(x))::text FROM unnest(${ints(bottom)}) AS u(x)`);
+        for (const [x, yes] of has)
+            if (yes !== "true")
+                l4[Number(x)] = 0;
+    }
+    return { collate, version, l1, l4, uncovered, expansions };
+}
+/** The characters ICU's accent and case levels read: those with a first-level weight, in order. */
+export function libcKept(o, s) {
+    let kept = "";
+    for (const ch of s)
+        if (o.l1[ch.codePointAt(0)] > 0)
+            kept += ch;
+    return kept;
+}
+const hex6 = (n) => n.toString(16).padStart(6, "0");
+/** ICU's sort key from its accent level on: what follows the first level's terminator (byte 01, at an even offset) */
+function afterPrimary(icuKey) {
+    for (let i = 0; i < icuKey.length; i += 2)
+        if (icuKey.charCodeAt(i) === 48 && icuKey.charCodeAt(i + 1) === 49)
+            return icuKey.slice(i + 2);
+    return "";
+}
+/**
+ * The sort key of `s` as one text that orders as glibc orders (bytewise; a space parts the levels, below every hex digit,
+ * so a shorter level sorts first): the first-level classes, ICU's accent and case levels of `libcKept(s)` (`icuKey`),
+ * the last level's (position, weight) pairs. A value holding a character not covered is refused, naming it.
+ */
+export function libcKey(o, s, icuKey) {
+    let first = "", last = "", at = 0;
+    for (const ch of s) {
+        at++;
+        const g = ch.codePointAt(0);
+        if (o.uncovered[g]) {
+            throw new PgEvalError("0A000", `the text ${JSON.stringify(s.length > 40 ? `${s.slice(0, 40)}…` : s)} holds U+${g.toString(16).toUpperCase().padStart(4, "0")}, which Mason cannot order as the database's collation ${o.collate} does (${gapMark("libc-uncovered")})`);
+        }
+        if (o.l1[g] > 0)
+            for (const x of o.expansions.get(g) ?? [g])
+                if (o.l1[x] > 0)
+                    first += hex6(o.l1[x]);
+        if (o.l4[g] > 0)
+            last += hex6(at) + hex6(o.l4[g]);
+    }
+    return `${first} ${afterPrimary(icuKey)} ${last}`;
+}
+/** The order as bytes, to keep in the copy: the three arrays and the expansions, as JSON. */
+export function encodeLibcOrder(o) {
+    // only the code points that are not 0 / covered: the arrays are mostly empty
+    const sparse = (a, skip) => {
+        const out = [];
+        for (let g = 0; g < MAX; g++)
+            if (a[g] !== skip)
+                out.push([g, a[g]]);
+        return out;
+    };
+    return JSON.stringify({ collate: o.collate, version: o.version, l1: sparse(o.l1, 0), l4: sparse(o.l4, 0), covered: sparse(o.uncovered, 1).map(([g]) => g), expansions: [...o.expansions] });
+}
+export function decodeLibcOrder(text) {
+    const v = JSON.parse(text);
+    const l1 = new Uint32Array(MAX), l4 = new Uint32Array(MAX), uncovered = new Uint8Array(MAX).fill(1);
+    for (const [g, x] of v.l1)
+        l1[g] = x;
+    for (const [g, x] of v.l4)
+        l4[g] = x;
+    for (const g of v.covered)
+        uncovered[g] = 0;
+    return { collate: v.collate, version: v.version, l1, l4, uncovered, expansions: new Map(v.expansions) };
+}

package/dist/src/duck/pg-eval-worker.js

@@ -0,0 +1,34 @@
+/**
+ * POSTGRES'S OWN FUNCTIONS, ON A WORKER (src/duck/pg-eval.ts): a PGlite with no tables, asked by DuckDB's scalar
+ * functions what Postgres makes of a chunk of values — a text read as a date, an interval, a boolean; a jsonpath
+ * evaluated. The main thread blocks on `signal` while this thread answers, so nothing here may wait on the main thread.
+ *
+ * In (on `port`): `{ sql, params, timeZone }`. Out: `{ ok: true, rows }` (each value its text, an array the JSON of its
+ * elements' text, or null) or
+ * `{ ok: false, code, message }` (Postgres's SQLSTATE and words); then `signal[0]` is set to 1 and notified.
+ */
+import { workerData } from "node:worker_threads";
+import { PGlite } from "@electric-sql/pglite";
+const { port, signal } = workerData;
+const db = new PGlite();
+let zone = null;
+const reply = (m) => { port.postMessage(m); Atomics.store(signal, 0, 1); Atomics.notify(signal, 0); };
+port.on("message", (m) => {
+    void (async () => {
+        try {
+            await db.waitReady;
+            if (zone !== m.timeZone) {
+                await db.exec(`SET TimeZone = '${m.timeZone.replace(/'/g, "''")}'`);
+                zone = m.timeZone;
+            }
+            const result = await db.query(m.sql, m.params, { rowMode: "array" });
+            // an array as the JSON of its elements' text (the `list` kind, src/duck/functions.ts)
+            const textOf = (v) => v === null ? null : Array.isArray(v) ? JSON.stringify(v.map(textOf)) : String(v);
+            reply({ ok: true, rows: result.rows.map((r) => r.map(textOf)) });
+        }
+        catch (e) {
+            const err = e;
+            reply({ ok: false, code: typeof err.code === "string" ? err.code : "XX000", message: err.message ?? String(e) });
+        }
+    })();
+});

package/dist/src/duck/pg-eval.js

@@ -0,0 +1,59 @@
+/**
+ * POSTGRES'S OWN FUNCTIONS, A CHUNK AT A TIME (the corpus run's unverified casts). What a text MEANS as a
+ * date, a timestamp, an interval, a boolean, an integer or a numeric is Postgres's input functions' to say — they read
+ * `01/02/2026`, `January 2, 2026`, `J2461043`, `2026-01-02 America/New_York`, `1 day ago`, `P1DT2H`, ` yes `, `0x1F`,
+ * `1_000` — and DuckDB reads ISO alone. So nothing reimplements them: a DuckDB scalar function (src/duck/functions.ts
+ * `__mason_pg_*`) hands its chunk's distinct values to a PGlite on a worker thread (pg-eval-worker.ts), which applies
+ * Postgres's own function under the session's TimeZone and answers each value, or Postgres's error. The same route
+ * answers the few functions DuckDB has no equivalent of (jsonpath's).
+ *
+ * DuckDB calls a scalar function synchronously, so the call BLOCKS the main thread until the worker answers
+ * (`Atomics.wait`, then `receiveMessageOnPort`): about 8 ms for 2,048 values. A worker that does not answer within
+ * `TIMEOUT_MS` is terminated and the statement fails; the next call starts another.
+ */
+import { MessageChannel, receiveMessageOnPort, Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { runnable } from "../lib/runnable.js";
+const TIMEOUT_MS = 30_000;
+export class PgEvalError extends Error {
+    code;
+    constructor(code, message) { super(message); this.code = code; }
+}
+let current = null;
+function start() {
+    const signal = new Int32Array(new SharedArrayBuffer(4));
+    const { port1, port2 } = new MessageChannel();
+    const worker = // `runnable`: the package ships this worker as .js (cli/build.ts), and a URL to the .ts would wait out TIMEOUT_MS and fail
+     new Worker(runnable(fileURLToPath(new URL("./pg-eval-worker.ts", import.meta.url))), { workerData: { port: port2, signal }, transferList: [port2] });
+    // the process may end while it lives: it holds nothing that must be closed
+    worker.unref();
+    port1.unref();
+    worker.on("error", (e) => { console.error(`mason: the Postgres function worker failed: ${e.message}`); if (current?.worker === worker)
+        current = null; });
+    return { worker, port: port1, signal };
+}
+/** Runs one statement on the worker's Postgres and returns its rows as text; Postgres's error is a PgEvalError. */
+export function pgEvalSync(sql, params, timeZone) {
+    current ??= start();
+    const w = current;
+    Atomics.store(w.signal, 0, 0);
+    w.port.postMessage({ sql, params, timeZone });
+    const waited = Atomics.wait(w.signal, 0, 0, TIMEOUT_MS);
+    const got = receiveMessageOnPort(w.port);
+    if (waited === "timed-out" || got === undefined) {
+        current = null;
+        void w.worker.terminate();
+        throw new PgEvalError("57014", `Postgres's function did not answer within ${TIMEOUT_MS / 1000} s (Mason computes it on its own Postgres)`);
+    }
+    const r = got.message;
+    if (!r.ok)
+        throw new PgEvalError(r.code, r.message);
+    return r.rows;
+}
+/** Stops the worker (a store that closes). */
+export async function stopPgEval() {
+    const w = current;
+    current = null;
+    if (w !== null)
+        await w.worker.terminate();
+}