@voltro/database 0.85.0 → 0.86.0

package/THIRD-PARTY-NOTICES.md

@@ -1,42 +1,14 @@
 # Third-Party Notices — @voltro/database
 
-This package depends on the open-source software listed below. Each is the
+This package uses the open-source software listed below. Each is the
 property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/database itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (4 packages).
+Generated from the resolved runtime dependency closure (3 packages).
 
 ---
 
-## layerr@3.0.0
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2020 Perry Mitchell
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ## typeid-js@1.2.0
 
 License: Apache-2.0
@@ -245,14 +217,14 @@ Apache License
    limitations under the License.
 ```
 
-## ulidx@2.4.1
+## ulid@3.0.2
 
 License: MIT
 
 ```
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2021 Perry Mitchell
+Copyright (c) 2017 Alizain Feerasta
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/actorSnapshot.js

@@ -0,0 +1,24 @@
+import { eq as e } from "./predicate.js";
+//#region src/actorSnapshot.ts
+var t = (e) => typeof e == "string" && e !== "" ? e : null, n = async (n, r, i) => {
+	if (r != null && r !== "") try {
+		let a = (await n.query({
+			table: "actors",
+			predicate: e("id", r),
+			order: [],
+			take: 1,
+			skip: void 0,
+			projection: void 0
+		}))[0];
+		return a === void 0 ? void 0 : {
+			id: r,
+			type: t(a.kind) ?? i,
+			displayName: t(a.displayName),
+			email: t(a.email)
+		};
+	} catch {
+		return;
+	}
+};
+//#endregion
+export { n as resolveActorSnapshot };

package/dist/arrayCodec.js

@@ -0,0 +1,32 @@
+//#region src/arrayCodec.ts
+var e = (e) => e === "mysql" || e === "mariadb" || e === "mssql" || e === "sqlite", t = (e) => {
+	let t = [];
+	for (let [n, r] of Object.entries(e.fields)) r.type === "array" && t.push(n);
+	return t;
+}, n = (n, r, i) => {
+	if (!e(i) || !r) return n;
+	let a = t(r);
+	if (a.length === 0) return n;
+	let o = { ...n };
+	for (let e of a) {
+		let t = o[e];
+		Array.isArray(t) && (o[e] = JSON.stringify(t));
+	}
+	return o;
+}, r = (n, r, i) => {
+	if (!e(i) || !r) return n;
+	let a = t(r);
+	return a.length === 0 ? n : n.map((e) => {
+		let t;
+		for (let n of a) {
+			let r = e[n];
+			if (r != null && !Array.isArray(r) && typeof r == "string") try {
+				let i = JSON.parse(r);
+				Array.isArray(i) && (t ||= { ...e }, t[n] = i);
+			} catch {}
+		}
+		return t ?? e;
+	});
+};
+//#endregion
+export { r as deserializeArraysOnRead, n as serializeArraysForWrite };

package/dist/branchExecute.js

@@ -0,0 +1,92 @@
+import { branchNamespaceName as e, enforceBranchLimits as t, planBranch as n, planBranchTeardownFor as r, resolveBranchMechanism as i } from "./branching.js";
+//#region src/branchExecute.ts
+var a = async (t, r) => {
+	let a = e(t.appSlug, t.prNumber), o = i({
+		seed: t.seed,
+		...t.dbUrl === void 0 ? {} : { dbUrl: t.dbUrl },
+		...t.prefer === void 0 ? {} : { prefer: t.prefer }
+	}), s = n({
+		mechanism: o,
+		branchId: a,
+		tableNames: t.tableNames,
+		seed: t.seed,
+		...t.parentNamespace === void 0 ? {} : { parentNamespace: t.parentNamespace },
+		...t.foreignKeys === void 0 ? {} : { foreignKeys: t.foreignKeys },
+		...t.indexNames === void 0 ? {} : { indexNames: t.indexNames },
+		...t.neonParentBranch === void 0 ? {} : { neonParentBranch: t.neonParentBranch }
+	});
+	if (o === "neon-cow") return {
+		branchId: a,
+		mechanism: o,
+		steps: s,
+		connectionString: await r.neonBranchCreate(a, t.neonParentBranch ?? "main")
+	};
+	await r.createNamespace(a);
+	for (let e of t.tableNames) await r.createTable(a, e);
+	for (let e of t.indexNames ?? []) await r.restoreIndexName(a, e);
+	if (t.seed === "copy") {
+		if (t.parentNamespace === void 0 || t.parentNamespace === "") throw Error("provisionBranch: seed 'copy' requires parentNamespace");
+		for (let e of t.tableNames) await r.copyTable(t.parentNamespace, a, e);
+	}
+	for (let e of t.foreignKeys ?? []) await r.addForeignKey(a, e);
+	return {
+		branchId: a,
+		mechanism: o,
+		steps: s
+	};
+}, o = async (e, t, n) => {
+	let i = r(t, e);
+	return t === "neon-cow" ? await n.neonBranchDelete(e) : await n.dropNamespace(e), i;
+}, s = (e, n, r) => t(e, n, r), c = (e) => `"${e.replace(/"/g, "\"\"")}"`, l = {
+	cascade: "CASCADE",
+	restrict: "RESTRICT",
+	setNull: "SET NULL",
+	noAction: "NO ACTION"
+}, u = (e) => `'${e.replace(/'/g, "''")}'`, d = (e, t) => {
+	let n = t.columns.map(u).join(", ");
+	return `DO $voltro_branch$
+DECLARE derived name;
+BEGIN
+  SELECT i.relname INTO derived
+    FROM pg_index x
+    JOIN pg_class i ON i.oid = x.indexrelid
+    JOIN pg_class c ON c.oid = x.indrelid
+    JOIN pg_namespace nsp ON nsp.oid = c.relnamespace
+   WHERE nsp.nspname = ${u(e)}
+     AND c.relname = ${u(t.table)}
+     AND NOT x.indisprimary
+     AND x.indisunique = ${t.unique ? "true" : "false"}
+     AND i.relname <> ${u(t.name)}
+     AND pg_get_expr(x.indpred, x.indrelid) IS NOT DISTINCT FROM ${t.where === void 0 ? "NULL" : u(t.where)}
+     AND (
+       SELECT array_agg(att.attname::text ORDER BY k.ord)
+         FROM unnest(x.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord)
+         JOIN pg_attribute att ON att.attrelid = c.oid AND att.attnum = k.attnum
+     ) = ARRAY[${n}]::text[]
+   LIMIT 1;
+  IF derived IS NOT NULL THEN
+    EXECUTE format('ALTER INDEX %I.%I RENAME TO %I',
+      ${u(e)}, derived, ${u(t.name)});
+  END IF;
+END
+$voltro_branch$`;
+}, f = (e, t) => {
+	let n = t.onDelete === void 0 ? "" : ` ON DELETE ${l[t.onDelete]}`, r = t.onUpdate === void 0 ? "" : ` ON UPDATE ${l[t.onUpdate]}`;
+	return `ALTER TABLE ${c(e)}.${c(t.table)} ADD FOREIGN KEY (${c(t.column)}) REFERENCES ${c(e)}.${c(t.targetTable)} (${c(t.targetColumn)})${n}${r}`;
+}, p = (e) => {
+	let t = () => {
+		throw Error("namespace branch executor: Neon ops require a neon-cow executor (use a Neon connection for copy-on-write branches)");
+	};
+	return {
+		createNamespace: (t) => e.run(`CREATE SCHEMA IF NOT EXISTS ${c(t)}`),
+		createTable: (t, n) => e.run(`CREATE TABLE IF NOT EXISTS ${c(t)}.${c(n)} (LIKE ${c(n)} INCLUDING ALL)`),
+		copyTable: (t, n, r) => e.run(`INSERT INTO ${c(n)}.${c(r)} SELECT * FROM ${c(t)}.${c(r)}`),
+		addForeignKey: (t, n) => e.run(f(t, n)),
+		restoreIndexName: (t, n) => e.run(d(t, n)),
+		dropNamespace: (t) => e.run(`DROP SCHEMA IF EXISTS ${c(t)} CASCADE`),
+		neonBranchCreate: t,
+		neonBranchDelete: t
+	};
+};
+//#endregion
+export { s as admitBranch, p as makeNamespaceBranchExecutor, a as provisionBranch, o as teardownBranch };

package/dist/branching.js

@@ -0,0 +1,106 @@
+import { sanitizeIdentifierFragment as e } from "./namespace.js";
+//#region src/branching.ts
+var t = 63, n = "br_pr", r = class extends Error {
+	_tag = "BranchNameInvalid";
+	constructor(e) {
+		super(e), this.name = "BranchNameInvalid";
+	}
+}, i = (i, a) => {
+	if (!Number.isInteger(a) || a < 0) throw new r(`prNumber must be a non-negative integer, got ${String(a)}`);
+	let o = e(i);
+	if (o.replace(/_/g, "") === "") throw new r(`app slug '${i}' has no usable identifier characters`);
+	let s = `${n}${a}_${o}`;
+	if (s.length > t) throw new r(`branch namespace '${s}' exceeds the ${t}-byte identifier limit — use a shorter app slug`);
+	return s;
+}, a = (e) => e.startsWith(n), o = {
+	requested: {
+		provision: "provisioning",
+		destroy: "destroying"
+	},
+	provisioning: {
+		provisioned: "ready",
+		fail: "failed"
+	},
+	ready: { destroy: "destroying" },
+	failed: {
+		provision: "provisioning",
+		destroy: "destroying"
+	},
+	destroying: {
+		destroyed: "destroyed",
+		fail: "failed"
+	},
+	destroyed: {}
+}, s = class extends Error {
+	from;
+	event;
+	_tag = "BranchTransitionInvalid";
+	constructor(e, t) {
+		super(`invalid branch transition: ${e} --${t}-->`), this.from = e, this.event = t, this.name = "BranchTransitionInvalid";
+	}
+}, c = (e, t) => {
+	let n = o[e][t];
+	if (n === void 0) throw new s(e, t);
+	return n;
+}, l = (e, t, n, i, a = [], o = []) => {
+	if (n === "copy" && (i === void 0 || i === "")) throw new r("seed 'copy' requires a parentNamespace to snapshot from");
+	let s = [{
+		kind: "create-namespace",
+		detail: e
+	}];
+	for (let n of t) s.push({
+		kind: "create-table",
+		table: n,
+		detail: `${e}.${n}`
+	});
+	for (let t of o) s.push({
+		kind: "restore-index-name",
+		table: t.table,
+		detail: `${e}.${t.table} ${t.unique ? "UNIQUE " : ""}(${t.columns.join(", ")}) → ${t.name}`
+	});
+	if (n === "copy") for (let n of t) s.push({
+		kind: "copy-table",
+		table: n,
+		detail: `${i}.${n} → ${e}.${n}`
+	});
+	for (let t of a) s.push({
+		kind: "copy-foreign-key",
+		table: t.table,
+		detail: `${e}.${t.table}.${t.column} → ${e}.${t.targetTable}.${t.targetColumn}`
+	});
+	return n === "fresh" && s.push({
+		kind: "seed",
+		detail: `run boot seeds into ${e}`
+	}), s;
+}, u = (e) => {
+	if (!a(e)) throw new r(`refusing to plan teardown of '${e}' — not a branch namespace`);
+	return [{
+		kind: "drop-namespace",
+		detail: e
+	}];
+}, d = (e) => {
+	if (e === void 0 || e === "") return !1;
+	try {
+		let t = new URL(e).hostname.toLowerCase();
+		return /(^|\.)neon\.(tech|build)$/.test(t);
+	} catch {
+		return /\bneon\.(tech|build)\b/i.test(e);
+	}
+}, f = (e) => e.prefer === void 0 ? e.seed === "copy" && d(e.dbUrl) ? "neon-cow" : "namespace" : e.prefer, p = (e, t = {}) => [{
+	kind: "neon-branch-create",
+	detail: `${t.parentBranch ?? "main"} → ${e} (copy-on-write)`
+}], m = (e) => {
+	if (!a(e)) throw new r(`refusing to plan teardown of '${e}' — not a branch namespace`);
+	return [{
+		kind: "neon-branch-delete",
+		detail: e
+	}];
+}, h = (e) => e.mechanism === "neon-cow" ? p(e.branchId, e.neonParentBranch === void 0 ? {} : { parentBranch: e.neonParentBranch }) : l(e.branchId, e.tableNames, e.seed, e.parentNamespace, e.foreignKeys, e.indexNames), g = (e, t) => e === "neon-cow" ? m(t) : u(t), _ = (e, t, n) => {
+	let r = e.filter((e) => e.state !== "destroyed" && e.state !== "destroying"), i = r.filter((e) => n - e.createdAtMs > t.ttlMs).map((e) => e.namespace), a = new Set(i);
+	return {
+		evict: i,
+		rejectNew: r.filter((e) => !a.has(e.namespace)).length >= t.maxBranches
+	};
+};
+//#endregion
+export { r as BranchNameInvalid, s as BranchTransitionInvalid, i as branchNamespaceName, _ as enforceBranchLimits, a as isBranchNamespace, d as isNeonConnection, c as nextBranchState, h as planBranch, l as planBranchProvision, u as planBranchTeardown, g as planBranchTeardownFor, p as planNeonBranchProvision, m as planNeonBranchTeardown, f as resolveBranchMechanism };

package/dist/bulkInsertLimits.js

@@ -0,0 +1,25 @@
+//#region src/bulkInsertLimits.ts
+var e = {
+	postgres: { maxBindParameters: 32767 },
+	mysql: { maxBindParameters: 65535 },
+	mariadb: { maxBindParameters: 65535 },
+	mssql: {
+		maxBindParameters: 2098,
+		maxRowsPerStatement: 1e3
+	},
+	sqlite: { maxBindParameters: 32766 },
+	turso: { maxBindParameters: 32766 }
+}, t = (t) => e[t], n = (e) => {
+	let t = /* @__PURE__ */ new Set();
+	for (let n of e) for (let e of Object.keys(n)) t.add(e);
+	return t.size;
+}, r = (e, t) => {
+	if (t === void 0 || e.length === 0) return [e];
+	let r = Math.max(1, n(e)), i = Math.floor(t.maxBindParameters / r), a = t.maxRowsPerStatement ?? Infinity, o = Math.max(1, Math.min(i, a));
+	if (e.length <= o) return [e];
+	let s = [];
+	for (let t = 0; t < e.length; t += o) s.push(e.slice(t, t + o));
+	return s;
+};
+//#endregion
+export { e as BULK_INSERT_LIMITS, t as bulkInsertLimitsFor, r as chunkRowsForInsert, n as columnsPerRow };

package/dist/cdcOffsetsTables.js

@@ -0,0 +1,19 @@
+import { id as e, text as t, timestamp as n } from "./columns.js";
+import { table as r } from "./table.js";
+//#region src/cdcOffsetsTables.ts
+var i = "_voltro_cdc_offsets", a = r(i, {
+	id: e({ prefix: "cdcoff" }),
+	replicaId: t(),
+	streamName: t(),
+	binlogFile: t(),
+	binlogPosition: t(),
+	updatedAt: n()
+}).index(["replicaId"]), o = r(i, {
+	id: e({ prefix: "cdcoff" }),
+	replicaId: t(),
+	streamName: t(),
+	ctVersion: t(),
+	updatedAt: n()
+}).index(["replicaId"]);
+//#endregion
+export { i as CDC_OFFSETS_TABLE, a as _voltroCdcOffsetsTable, o as _voltroMssqlCdcOffsetsTable };

package/dist/changeEvent.js

@@ -0,0 +1,41 @@
+//#region src/changeEvent.ts
+var e = (e, t) => ({
+	...t,
+	...e,
+	origin: e.origin ?? "injected"
+}), t = (e, t, n = {}) => ({
+	table: e,
+	op: "insert",
+	old: null,
+	new: t,
+	...n
+}), n = (e, t, n, r = {}) => ({
+	table: e,
+	op: "update",
+	old: t,
+	new: n,
+	...r
+}), r = (e, t, n = {}) => ({
+	table: e,
+	op: "delete",
+	old: t,
+	new: null,
+	...n
+}), i = (e, t, n = {}) => {
+	let { at: r = "2026-01-01T00:00:00.000Z", column: i = "deletedAt", ...a } = n;
+	return {
+		table: e,
+		op: "update",
+		old: {
+			...t,
+			[i]: null
+		},
+		new: {
+			...t,
+			[i]: r
+		},
+		...a
+	};
+};
+//#endregion
+export { r as changeDelete, t as changeInsert, i as changeSoftDelete, n as changeUpdate, e as externalChangeEvent };

package/dist/changeIdentity.js

@@ -0,0 +1,65 @@
+import { createHash as e } from "node:crypto";
+//#region src/changeIdentity.ts
+var t = (e) => e == null ? "null" : e instanceof Date ? JSON.stringify(e.toISOString()) : typeof e == "bigint" ? JSON.stringify(e.toString()) : Array.isArray(e) ? `[${e.map(t).join(",")}]` : typeof e == "object" ? `{${Object.entries(e).filter(([, e]) => e !== void 0).sort(([e], [t]) => e < t ? -1 : +(e > t)).map(([e, n]) => `${JSON.stringify(e)}:${t(n)}`).join(",")}}` : JSON.stringify(e) ?? "null", n = (n) => e("sha256").update([
+	n.pipe,
+	n.op,
+	n.key,
+	t(n.next),
+	t(n.prev)
+].join("\0")).digest("hex").slice(0, 32), r = (e, t) => `${e}:${t}`, i = (e) => {
+	let t = e.lastIndexOf(":");
+	if (t <= 0) return null;
+	let n = Number(e.slice(t + 1));
+	return !Number.isInteger(n) || n < 0 ? null : {
+		digest: e.slice(0, t),
+		occurrence: n
+	};
+}, a = class {
+	#e = /* @__PURE__ */ new Map();
+	#t;
+	#n;
+	constructor(e) {
+		this.#t = e.windowMs, this.#n = Math.max(1, e.maxEntries);
+	}
+	get size() {
+		return this.#e.size;
+	}
+	next(e, t) {
+		let n = this.#e.get(e);
+		if (n === void 0) return this.#e.set(e, {
+			count: 1,
+			lastMs: t
+		}), this.#r(), 0;
+		n.lastMs = t;
+		let r = n.count;
+		return n.count += 1, this.#e.delete(e), this.#e.set(e, n), r;
+	}
+	seedFromChangeKeys(e, t) {
+		for (let n of e) {
+			let e = i(n);
+			if (e === null) continue;
+			let r = this.#e.get(e.digest), a = Math.max(r?.count ?? 0, e.occurrence + 1);
+			this.#e.set(e.digest, {
+				count: a,
+				lastMs: r?.lastMs ?? t
+			});
+		}
+		this.#r();
+	}
+	prune(e) {
+		let t = e - this.#t;
+		for (let [e, n] of this.#e) n.lastMs < t && this.#e.delete(e);
+	}
+	#r() {
+		for (; this.#e.size > this.#n;) {
+			let e = this.#e.keys().next();
+			if (e.done === !0) return;
+			this.#e.delete(e.value);
+		}
+	}
+}, o = "VOLTRO_CHANGE_CLAIMS_TTL_HOURS", s = 1, c = (e = process.env) => {
+	let t = Number(e[o]);
+	return (Number.isFinite(t) && t > 0 ? t : 1) * 2 * 36e5;
+};
+//#endregion
+export { o as CHANGE_CLAIM_TTL_ENV, s as DEFAULT_CHANGE_CLAIM_TTL_HOURS, a as OccurrenceCounter, t as canonicalJson, n as changeDigest, r as composeChangeKey, c as occurrenceWindowMs, i as parseChangeKey };

package/dist/changeListenerCeiling.js

@@ -0,0 +1,6 @@
+//#region src/changeListenerCeiling.ts
+var e = 512, t = (e) => {
+	e.setMaxListeners(512);
+};
+//#endregion
+export { e as CHANGE_LISTENER_CEILING, t as raiseChangeListenerCeiling };

package/dist/columnReference.js

@@ -0,0 +1,17 @@
+//#region src/columnReference.ts
+var e = (e) => {
+	if (e.length === 0) throw RangeError("Column reference must not be empty");
+	return {
+		_tag: "ColumnReference",
+		column: e
+	};
+}, t = (e) => typeof e == "object" && !!e && "_tag" in e && e._tag === "ColumnReference" && "column" in e && typeof e.column == "string", n = [
+	"eq",
+	"neq",
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+];
+//#endregion
+export { n as columnComparisonOperators, e as columnRef, t as isColumnReference };