@voltro/database 0.85.0 → 0.87.0

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 };

package/dist/columns.js

@@ -0,0 +1,326 @@
+//#region src/columns.ts
+var e = (e) => {
+	let t = [];
+	for (let [n, r] of Object.entries(e.fields)) r.serverOnly === !0 && t.push(n);
+	return t;
+}, t = (e) => {
+	let t = [];
+	for (let [n, r] of Object.entries(e.fields)) r.crdtManaged === !0 && t.push(n);
+	return t;
+}, n = (e) => {
+	let t = [];
+	for (let [n, r] of Object.entries(e.fields)) {
+		let e = r.readableBy;
+		e !== void 0 && e.length > 0 && t.push({
+			column: n,
+			scopes: e
+		});
+	}
+	return t;
+}, r = (e) => {
+	let t = [];
+	for (let [n, r] of Object.entries(e.fields)) r.crdtManaged === !0 && t.push(n);
+	return t;
+}, i = class e {
+	definition;
+	constructor(e) {
+		this.definition = e;
+	}
+	rejectIfRaw(e) {
+		if (this.definition.type === "raw") throw Error(`raw(...) column rejects .${e}() — the DDL fragment is the single source of truth for type/nullability/default. Encode ${e === "nullable" ? "NULL" : e === "unique" ? "UNIQUE" : "DEFAULT"} directly in the raw fragment instead.`);
+	}
+	nullable() {
+		return this.rejectIfRaw("nullable"), new e({
+			...this.definition,
+			nullable: !0
+		});
+	}
+	externalId() {
+		if (this.rejectIfRaw("externalId"), this.definition.type === "reference" || this.definition.type === "id") throw Error(`.externalId() requires a scalar non-primary-key column (got ${this.definition.type}) — \`reference()\` is local by definition and \`id()\` identifies this row.`);
+		return new e({
+			...this.definition,
+			externalId: !0
+		});
+	}
+	encrypted() {
+		return this.rejectIfRaw("encrypted"), new e({
+			...this.definition,
+			encrypted: !0
+		});
+	}
+	serverOnly() {
+		if (this.rejectIfRaw("serverOnly"), this.definition.crdtManaged === !0) throw Error("serverOnly() on a CRDT column (crdtText()/crdtDoc()) is a contradiction: clients write CRDT updates and must read the merged state back. Remove serverOnly(), or use a plain bytes() column if only the server touches it.");
+		return new e({
+			...this.definition,
+			serverOnly: !0
+		});
+	}
+	readableBy(...t) {
+		if (this.rejectIfRaw("readableBy"), t.length === 0) throw Error(".readableBy() needs at least one scope — a column readable by nobody is .serverOnly(). List the scopes that may read it, e.g. .readableBy('billing:read').");
+		if (t.find((e) => typeof e != "string" || e.trim() === "") !== void 0) throw Error(`.readableBy(...) rejects a blank scope — every scope must be a non-empty string (a blank scope can never be held, so it would hide the column from everyone). Got: ${JSON.stringify(t)}.`);
+		let n = [...new Set(t)];
+		return new e({
+			...this.definition,
+			readableBy: n
+		});
+	}
+	version() {
+		if (this.rejectIfRaw("version"), this.definition.type !== "integer") throw Error(`.version() requires an integer() column (got ${this.definition.type}). The store increments it, so it has to be a number — and a timestamp version reintroduces exactly the clock problem optimistic locking exists to avoid: two writes in the same millisecond are indistinguishable, and replica clocks disagree.`);
+		return new e({
+			...this.definition,
+			versionColumn: !0,
+			hasDefault: !0,
+			defaultValue: 1
+		});
+	}
+	sensitive(t) {
+		return new e({
+			...this.definition,
+			sensitive: { class: t }
+		});
+	}
+	safe() {
+		return new e({
+			...this.definition,
+			safe: !0
+		});
+	}
+	unique(t) {
+		return this.rejectIfRaw("unique"), t?.dedup === void 0 ? new e({
+			...this.definition,
+			unique: !0
+		}) : new e({
+			...this.definition,
+			unique: !0,
+			uniqueSpec: { dedup: t.dedup }
+		});
+	}
+	default(t) {
+		return this.rejectIfRaw("default"), typeof t == "function" ? new e({
+			...this.definition,
+			hasDefault: !0,
+			defaultFactory: t
+		}) : new e({
+			...this.definition,
+			hasDefault: !0,
+			defaultValue: t
+		});
+	}
+	computed(t) {
+		return new e({
+			...this.definition,
+			computed: t
+		});
+	}
+	onUpdate(t) {
+		return new e({
+			...this.definition,
+			onUpdate: t
+		});
+	}
+	generatedAs(t, n) {
+		return new e({
+			...this.definition,
+			generatedAs: {
+				expr: t,
+				stored: n?.stored ?? !1
+			}
+		});
+	}
+	backfill(t, n) {
+		let r = typeof t == "function" ? {
+			kind: "js",
+			fn: t,
+			...n?.batchSize === void 0 ? {} : { batchSize: n.batchSize },
+			...n?.sleepMs === void 0 ? {} : { sleepMs: n.sleepMs }
+		} : {
+			kind: "sql",
+			sql: t,
+			...n?.batchSize === void 0 ? {} : { batchSize: n.batchSize },
+			...n?.sleepMs === void 0 ? {} : { sleepMs: n.sleepMs }
+		};
+		return new e({
+			...this.definition,
+			backfill: r
+		});
+	}
+	renamedFrom(t) {
+		return new e({
+			...this.definition,
+			renamedFrom: t
+		});
+	}
+	narrowedFrom(t, n) {
+		let r = n?.using === void 0 ? { from: t } : {
+			from: t,
+			using: n.using
+		};
+		return new e({
+			...this.definition,
+			narrowedFrom: r
+		});
+	}
+	oneOf(t) {
+		return new e({
+			...this.definition,
+			oneOf: t
+		});
+	}
+	maxLength(t) {
+		return new e({
+			...this.definition,
+			maxLength: t
+		});
+	}
+	check(t) {
+		let n = this.definition.checks ? [...this.definition.checks, t] : [t];
+		return new e({
+			...this.definition,
+			checks: n
+		});
+	}
+	__definition() {
+		return this.definition;
+	}
+}, a = (e) => new i({
+	type: e,
+	nullable: !1,
+	unique: !1,
+	hasDefault: !1
+});
+function o(e) {
+	return new i({
+		type: "id",
+		nullable: !1,
+		unique: !0,
+		hasDefault: !1,
+		idSchemeInput: e
+	});
+}
+var s = () => a("text"), c = () => a("integer"), l = () => a("real"), u = (e, t = 0) => {
+	if (!Number.isInteger(e) || e <= 0) throw Error(`decimal(${String(e)}, ${String(t)}): precision must be a positive integer (the total number of significant digits, e.g. decimal(12, 2)).`);
+	if (!Number.isInteger(t) || t < 0 || t > e) throw Error(`decimal(${String(e)}, ${String(t)}): scale must be an integer between 0 and precision (${e}).`);
+	return new i({
+		type: "decimal",
+		nullable: !1,
+		unique: !1,
+		hasDefault: !1,
+		precision: e,
+		scale: t,
+		sqliteDecimalEncoding: "sortable-v1"
+	});
+}, d = u, f = () => a("bigint"), p = (e, t) => {
+	if (t.length === 0) throw Error(`dbEnum('${e}', []): enum must have at least one value`);
+	return {
+		name: e,
+		values: t,
+		column: () => new i({
+			type: "enum",
+			nullable: !1,
+			unique: !1,
+			hasDefault: !1,
+			enumName: e,
+			enumValues: t
+		})
+	};
+}, m = () => a("boolean"), h = () => a("timestamp"), g = () => a("date"), _ = () => a("json"), v = () => a("bytes"), y = () => new i({
+	type: "bytes",
+	nullable: !0,
+	unique: !1,
+	hasDefault: !1,
+	crdtManaged: !0
+}), b = () => new i({
+	type: "bytes",
+	nullable: !0,
+	unique: !1,
+	hasDefault: !1,
+	crdtManaged: !0
+}), x = () => new i({
+	type: "bytes",
+	nullable: !0,
+	unique: !1,
+	hasDefault: !1,
+	crdtSealed: !0
+}), S = () => new i({
+	type: "bytes",
+	nullable: !0,
+	unique: !1,
+	hasDefault: !1,
+	crdtManaged: !0
+}), C = () => {
+	throw Error("selfReference(): the target is resolved by table() — a column built with selfReference() must be declared inside a table({ … }) literal, not read before the table exists");
+};
+function w(e) {
+	return T(C, e);
+}
+function T(e, t) {
+	return new i({
+		type: "reference",
+		nullable: !1,
+		unique: !1,
+		hasDefault: !1,
+		references: e,
+		referenceStorage: t?.storage ?? "text",
+		referenceColumn: t?.column ?? "id",
+		onDelete: t?.onDelete ?? "restrict",
+		refOnUpdate: t?.onUpdate ?? "noAction",
+		...t?.onSoftDelete === void 0 ? {} : { refOnSoftDelete: t.onSoftDelete },
+		fkAutoIndex: t?.index ?? !0,
+		...t?.orphanPolicy ? { orphanPolicy: t.orphanPolicy } : {}
+	});
+}
+var E = () => new i({
+	type: "text",
+	nullable: !0,
+	unique: !1,
+	hasDefault: !1,
+	dropped: !0
+}), D = (e) => Object.keys(e.fields).filter((t) => e.fields[t]?.dropped !== !0), O = (e, t) => {
+	if (!Number.isInteger(e) || e <= 0) throw Error(`vector(${String(e)}): dimension must be a positive integer (the embedding length, e.g. vector(1536)).`);
+	return new i({
+		type: "vector",
+		nullable: !1,
+		unique: !1,
+		hasDefault: !1,
+		vectorDim: e,
+		vectorPrecision: t?.precision ?? "float32"
+	});
+}, k = (e) => new i({
+	type: "array",
+	nullable: !1,
+	unique: !1,
+	hasDefault: !1,
+	arrayElement: e.__definition().type
+}), A = () => a("interval"), j = (e, t = 4326) => new i({
+	type: "text",
+	nullable: !1,
+	unique: !1,
+	hasDefault: !1,
+	spatial: {
+		kind: "geography",
+		geomKind: e,
+		srid: t
+	}
+}), M = (e, t = 4326) => new i({
+	type: "text",
+	nullable: !1,
+	unique: !1,
+	hasDefault: !1,
+	spatial: {
+		kind: "geometry",
+		geomKind: e,
+		srid: t
+	}
+}), N = (e) => new i({
+	type: "raw",
+	nullable: !1,
+	unique: !1,
+	hasDefault: !1,
+	rawDdl: e
+}), P = (e) => {
+	let t = {};
+	for (let [n, r] of Object.entries(e)) t[n] = r.__definition();
+	return t;
+};
+//#endregion
+export { i as ColumnBuilder, C as SELF_REFERENCE_TARGET, k as array, f as bigint, m as boolean, v as bytes, b as crdtCounter, S as crdtDoc, r as crdtManagedColumns, t as crdtManagedColumnsOf, x as crdtSealed, y as crdtText, g as date, p as dbEnum, u as decimal, E as dropped, j as geography, M as geometry, o as id, c as integer, A as interval, _ as json, P as materializeFields, d as numeric, D as persistedColumns, N as raw, n as readableByColumns, l as real, T as reference, w as selfReference, e as serverOnlyColumns, s as text, h as timestamp, O as vector };

package/dist/committedChanges.js

@@ -0,0 +1,12 @@
+//#region src/committedChanges.ts
+var e = Symbol.for("voltro.database.committedChanges"), t = globalThis, n = t[e] ??= /* @__PURE__ */ new WeakMap(), r = (e, t) => {
+	let r = {};
+	for (let t of e) n.set(t, r);
+	try {
+		for (let n of e) t(n);
+	} finally {
+		for (let t of e) n.delete(t);
+	}
+}, i = (e) => n.get(e);
+//#endregion
+export { i as committedChangeBatchOf, r as emitCommittedChanges };

package/dist/connectionIdentity.js

@@ -0,0 +1,36 @@
+import { createHash as e } from "node:crypto";
+//#region src/connectionIdentity.ts
+var t = {
+	postgres: 5432,
+	mysql: 3306,
+	mariadb: 3306,
+	mssql: 1433
+}, n = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"::1",
+	"[::1]",
+	"0.0.0.0"
+]), r = (e) => {
+	let r = e.host, i = e.port, a = e.database;
+	if (e.url !== void 0 && e.url !== "") try {
+		let t = new URL(e.url);
+		r ??= decodeURIComponent(t.hostname), i === void 0 && t.port !== "" && (i = Number(t.port)), a ??= decodeURIComponent(t.pathname.replace(/^\//, ""));
+	} catch {
+		return;
+	}
+	if (r === void 0 || r === "" || a === void 0 || a === "") return;
+	let o = i ?? t[(e.dialect ?? "").toLowerCase()];
+	if (o === void 0 || !Number.isFinite(o)) return;
+	let s = r.toLowerCase();
+	return {
+		host: n.has(s) ? "localhost" : s,
+		port: o,
+		database: a.toLowerCase()
+	};
+}, i = (t) => {
+	let n = r(t);
+	if (n !== void 0) return e("sha256").update(`${n.host}\u0000${n.port}\u0000${n.database}`).digest("hex").slice(0, 32);
+}, a = (e, t) => e === void 0 || t === void 0 ? "unknown" : e === t ? "same" : "different";
+//#endregion
+export { i as connectionIdentity, r as normaliseTarget, a as sameDatabase };

package/dist/coreTables.js

@@ -0,0 +1,16 @@
+import { id as e, text as t, timestamp as n } from "./columns.js";
+import { table as r } from "./table.js";
+//#region src/coreTables.ts
+var i = r("actors", {
+	id: e(),
+	kind: t().oneOf([
+		"user",
+		"serviceAccount",
+		"apiKey",
+		"system"
+	]).safe(),
+	displayName: t().nullable().sensitive("fullName"),
+	createdAt: n().default("now")
+});
+//#endregion
+export { i as actorsTable };

package/dist/coreTablesRegistry.js

@@ -0,0 +1,10 @@
+//#region src/coreTablesRegistry.ts
+var e = Symbol.for("@voltro/database/coreTablesRegistry"), t = globalThis, n = t[e] ?? (t[e] = {}), r = (e) => {
+	e.actors !== void 0 && (n.actors = e.actors), e.tenants !== void 0 && (n.tenants = e.tenants);
+}, i = (e, t) => () => {
+	let n = e();
+	if (n === void 0) throw Error(`core '${t}' table not registered; expected the framework CLI or your migrate step to call registerCoreTables({ ${t}: () => ${t}Table }) before the database handle is constructed`);
+	return n();
+}, a = () => i(() => n.actors, "actors"), o = () => i(() => n.tenants, "tenants");
+//#endregion
+export { r as registerCoreTables, a as requireActors, o as requireTenants };

package/dist/dataTransfers.js

@@ -0,0 +1,23 @@
+import { boolean as e, id as t, integer as n, text as r, timestamp as i } from "./columns.js";
+import { table as a } from "./table.js";
+//#region src/dataTransfers.ts
+var o = "_voltro_data_transfers", s = a(o, {
+	id: t({ prefix: "dimp" }),
+	startedAt: i().default("now"),
+	finishedAt: i().nullable(),
+	direction: r().default("import"),
+	mode: r(),
+	via: r(),
+	bundle: r().nullable(),
+	sourceFingerprint: r().nullable(),
+	tablesWritten: n().default(0),
+	rowsWritten: n().default(0),
+	failure: r().nullable(),
+	staged: e().nullable(),
+	fieldKeyIds: r().nullable()
+}).renamedFrom("_voltro_data_imports").nonReactive(), c = (e) => {
+	let t = Number.isFinite(e.startedAt.getTime()) ? e.startedAt.toISOString() : "an unknown time", n = e.direction === "import" ? e.mode : `${e.direction} ${e.mode}`, r = e.failure === null ? e.finishedAt === null ? `${n} — started and never reported finishing` : e.direction === "backup" || e.direction === "restore" ? `${n} — finished${e.rowsWritten > 0 ? ` (${e.rowsWritten} blob(s))` : ""}` : `${n} — ${e.rowsWritten} row(s) across ${e.tablesWritten} table(s)` : `FAILED ${n} — ${e.failure}`, i = e.staged === null ? "" : e.staged ? " · staged (target untouched until the swap)" : " · NOT staged (target emptied first)";
+	return `${t} · ${r} · via ${e.via}${i}` + (e.bundle === null ? "" : ` · from ${e.bundle}`) + (e.sourceFingerprint === null ? "" : ` · source schema ${e.sourceFingerprint}`);
+};
+//#endregion
+export { o as DATA_TRANSFERS_TABLE, s as _voltroDataTransfersTable, c as describeTransferRun };