@voltro/database 0.85.0 → 0.87.0

package/dist/indexAudit.js

@@ -0,0 +1,61 @@
+import { ansi as e } from "@voltro/logger";
+//#region src/indexAudit.ts
+var t = (e) => {
+	if (typeof e == "string") return e;
+	if ("jsonPath" in e) {
+		let { column: t, path: n, numeric: r } = e.jsonPath;
+		return `(json:${t}->${n.join(".")}${r ? "::num" : ""})`;
+	}
+	return `(${e.expr})`;
+}, n = (e) => e.map(t), r = (e, n) => {
+	if (e.length !== n.length) return !1;
+	for (let r = 0; r < e.length; r++) if (t(e[r]) !== t(n[r])) return !1;
+	return !0;
+}, i = (e, n) => {
+	if (e.length >= n.length) return !1;
+	for (let r = 0; r < e.length; r++) if (t(e[r]) !== t(n[r])) return !1;
+	return !0;
+}, a = (e) => {
+	let t = [], a = e.appliedIndexes, o = e.tableName;
+	for (let e = 0; e < a.length; e++) {
+		let s = a[e];
+		for (let c = e + 1; c < a.length; c++) {
+			let e = a[c];
+			if (r(s.fields, e.fields)) {
+				let [r, i] = s.name < e.name ? [s, e] : [e, s];
+				t.push({
+					kind: "duplicate-fields",
+					table: o,
+					redundant: r,
+					coveredBy: i,
+					message: `'${o}' has two indexes on the same fields [${n(s.fields).join(", ")}]: '${s.name}' and '${e.name}'. The B-tree engine builds both, costing write throughput + disk space for no read benefit. Drop '${r.name}' (or '${i.name}' if you prefer the other name). Applies to every supported dialect (Postgres / MySQL / MariaDB / MSSQL / SQLite).`
+				});
+			} else i(s.fields, e.fields) ? t.push({
+				kind: "redundant-prefix",
+				table: o,
+				redundant: s,
+				coveredBy: e,
+				message: `'${o}' index '${s.name}' on [${n(s.fields).join(", ")}] is a leading prefix of '${e.name}' on [${n(e.fields).join(", ")}]. Every B-tree dialect we support (Postgres / MySQL / MariaDB / MSSQL / SQLite) can serve a [${n(s.fields).join(", ")}] query from '${e.name}' too via the leading-prefix rule, so '${s.name}' adds write cost without read benefit. Drop '${s.name}' — unless you specifically need a smaller index for cache locality on a write-heavy table (rare; profile first).`
+			}) : i(e.fields, s.fields) && t.push({
+				kind: "redundant-prefix",
+				table: o,
+				redundant: e,
+				coveredBy: s,
+				message: `'${o}' index '${e.name}' on [${n(e.fields).join(", ")}] is a leading prefix of '${s.name}' on [${n(s.fields).join(", ")}]. Every B-tree dialect we support (Postgres / MySQL / MariaDB / MSSQL / SQLite) can serve a [${n(e.fields).join(", ")}] query from '${s.name}' too via the leading-prefix rule, so '${e.name}' adds write cost without read benefit. Drop '${e.name}' — unless you specifically need a smaller index for cache locality on a write-heavy table (rare; profile first).`
+			});
+		}
+	}
+	return t;
+}, o = (e) => {
+	let t = [];
+	for (let n of e) t.push(...a(n));
+	return t;
+}, s = "\x1B[", c = `${s}38;2;245;158;11m`, l = `${s}38;2;16;185;129m`, u = (t, n) => `${t}${n}${e.reset}`, d = (e, t, n) => e ? typeof t == "function" ? t(n) : u(t, n) : n, f = (t, r = {}) => {
+	let i = r.color ?? !0, a = r.indent ?? "  ", o = (t) => d(i, e.dim, t.padEnd(11)), s = (t) => d(i, (t) => e.bold(e.brand(t)), t), u = (t) => d(i, e.brightRed24, t), f = (e) => d(i, l, e), p = (e) => d(i, c, e), m = (t) => d(i, e.dim, t), h = `${p("index audit")} ${m("·")} ${d(i, e.bold, t.kind)}`, g = t.redundant.fields.length, _ = n(t.coveredBy.fields.slice(g)), v = (e, t) => {
+		let n = e.slice(0, t), r = e.slice(t), i = [];
+		return n.length > 0 && i.push(f(`[${n.join(", ")}]`)), r.length > 0 && i.push(p(`+ [${r.join(", ")}]`)), i.join(" ");
+	}, y = [];
+	return y.push(h), y.push(""), y.push(`${o("table")}${s(t.table)}`), y.push(""), y.push(`${o("redundant")}${u(t.redundant.name)}`), y.push(`${o("")}${v(n(t.redundant.fields), g)}`), y.push(""), y.push(`${o("covered by")}${f(t.coveredBy.name)}`), y.push(`${o("")}${v(n(t.coveredBy.fields), g)}`), _.length > 0 && y.push(`${o("")}${m(`└ extra columns: ${_.join(", ")}`)}`), y.push(""), t.kind === "redundant-prefix" ? (y.push(`${o("why")}B-tree indexes serve queries that filter on a LEADING PREFIX of`), y.push(`${o("")}their column list. The wider index already covers every`), y.push(`${o("")}query the narrower one can serve.`), y.push(`${o("")}${m("Same rule on Postgres / MySQL / MariaDB / MSSQL / SQLite.")}`)) : (y.push(`${o("why")}Two indexes on the same columns under different names.`), y.push(`${o("")}The B-tree engine builds both — same coverage, double cost.`), y.push(`${o("")}${m("Same rule on Postgres / MySQL / MariaDB / MSSQL / SQLite.")}`)), y.push(""), y.push(`${o("cost")}Every ${s("INSERT")} / ${s("UPDATE")} / ${s("DELETE")} on this table writes`), y.push(`${o("")}to ${d(i, e.bold, "both")} B-trees. Pure write overhead, zero read benefit.`), y.push(""), y.push(`${o("fix")}Drop  ${u(t.redundant.name)}`), y.push(`${o("")}${m("Keep only if profiling shows the smaller index gives a")}`), y.push(`${o("")}${m("measurable cache-locality boost on a write-heavy hot path.")}`), y.push(`${o("")}${m("Silence with VOLTRO_INDEX_AUDIT=off if intentional.")}`), y.map((e) => `${a}${e}`).join("\n");
+};
+//#endregion
+export { o as auditAllTableIndexes, a as auditTableIndexes, f as formatIndexAuditIssue };

package/dist/indexStorage.js

@@ -0,0 +1,58 @@
+import { resolveGinOpclass as e } from "./ginIndex.js";
+import { vectorDistanceToOpclass as t } from "./table.js";
+//#region src/indexStorage.ts
+var n = (e, n = "float32") => {
+	let r = e?.hnsw, i = r?.m ?? 16, a = r?.efConstruction ?? 64;
+	for (let [e, t] of Object.entries({
+		m: i,
+		efConstruction: a
+	})) if (!Number.isSafeInteger(t) || t <= 0) throw Error(`HNSW ${e} must be a positive safe integer`);
+	let o = r?.opclass ?? t(r?.distance, n);
+	if (!/^[a-z_][a-z0-9_$]*(?:\.[a-z_][a-z0-9_$]*)?$/i.test(o)) throw Error("HNSW opclass must be an unquoted, optionally schema-qualified identifier");
+	return {
+		m: i,
+		efConstruction: a,
+		opclass: o.toLowerCase().replace(/^public\./, "")
+	};
+}, r = (e, t) => t === void 0 || t === "postgres" ? e ?? "btree" : e === "hnsw" || e === "gin" && (t === "mysql" || t === "mariadb") ? null : "btree", i = (t, r) => {
+	let i = t === "gin" ? e(r) : void 0, a = i !== void 0 && [
+		"array_ops",
+		"jsonb_ops",
+		"tsvector_ops"
+	].includes(i);
+	return {
+		...t !== void 0 && t !== "btree" ? { kind: t } : {},
+		...t === "hnsw" ? { kindOptions: { hnsw: n(r) } } : {},
+		...i !== void 0 && !a ? { kindOptions: { gin: { opclass: i } } } : {}
+	};
+}, a = (t, r, i = "float32") => {
+	if (t === void 0 || t === "btree") return {
+		using: "",
+		withSuffix: "",
+		skip: !1
+	};
+	if (!/^[a-z_][a-z0-9_]*$/i.test(t)) throw Error("Index kind must be an SQL access-method identifier");
+	if (t === "gin") {
+		let t = e(r);
+		return {
+			using: " USING GIN",
+			withSuffix: "",
+			...t === void 0 ? {} : { opclass: t },
+			skip: !1
+		};
+	}
+	if (t !== "hnsw") return {
+		using: ` USING ${t.toUpperCase()}`,
+		withSuffix: "",
+		skip: !1
+	};
+	let a = n(r, i);
+	return {
+		using: " USING hnsw",
+		withSuffix: ` WITH (m = ${a.m}, ef_construction = ${a.efConstruction})`,
+		opclass: a.opclass,
+		skip: !1
+	};
+};
+//#endregion
+export { r as indexKindForDialect, i as indexStorageShape, a as pgIndexClauses, n as resolveHnswOptions };

package/dist/joinCompiler.js

@@ -0,0 +1,160 @@
+import { persistedColumns as e } from "./columns.js";
+import { authoredError as t } from "./dbCause.js";
+import { decimalEqualityKey as n } from "./decimalComparison.js";
+import { inferForeignKey as r, validateRelationConfig as i } from "./relations.js";
+import { getRelations as a } from "./relationsRegistry.js";
+//#region src/joinCompiler.ts
+var o = class extends Error {
+	_tag = "EagerCardinalityError";
+	constructor(e) {
+		super(e), this.name = "EagerCardinalityError";
+	}
+}, s = (e) => {
+	let { relationName: t, sourceTableName: n, targetTableName: r, foreignKey: i, sourceKey: a } = e, o = r === n;
+	return `relation '${t}' on '${n}' is declared \`one\`, but ${r}.${i} matches MORE than one row for the same ${n}.${a} — so there is no single related row to return.` + (o ? ` Because this relation is self-referential, check which side the key is on: \`foreignKey: '${i}'\` means "rows whose ${i} points AT me" (my children — there can be many). If you meant "the row my ${i} points to" (my parent), that is \`sourceKey: '${i}'\`.` : " Use `many(...)` if several are expected, or narrow the key.");
+}, c = async (e, n, r, o) => {
+	if (e.length === 0) return e;
+	let s = a(r.tableName);
+	if (s === void 0) throw t(`cannot eager-load on '${r.tableName}': no relations registered. Did you forget to declare \`relations(${r.tableName}, ...)\` or import the file that does?`);
+	let c = e.map((e) => ({ ...e }));
+	for (let [e, a] of Object.entries(n)) {
+		let n = s[e];
+		if (n === void 0) {
+			let n = Object.keys(s).join(", ") || "<none>";
+			throw t(`unknown relation '${e}' on '${r.tableName}'. Registered relations: ${n}.`);
+		}
+		i(r, e, n), await l(c, e, n, a === !0 ? {} : a, r, o);
+	}
+	return c;
+}, l = async (e, t, n, r, i, a) => {
+	switch (n.kind) {
+		case "one":
+			await u(e, t, n, r, i, a);
+			return;
+		case "many":
+			await d(e, t, n, r, i, a);
+			return;
+		case "manyToMany":
+			await p(e, t, n, r, i, a);
+			return;
+	}
+}, u = async (e, t, n, i, a, c) => {
+	let l = n.target(), u = n.sourceKey ?? h(a, l.tableName);
+	if (u !== void 0) {
+		let n = g(e, u), r = n.length === 0 ? [] : await _(l, "id", n, i, c), o = new Map(r.map((e) => [m(l, "id", e.id), e]));
+		for (let n of e) {
+			let e = m(a, u, n[u]);
+			n[t] = e == null ? null : o.get(e) ?? null;
+		}
+		await v(r, i.with, l, c);
+		return;
+	}
+	let d = n.foreignKey ?? r(l, a.tableName, t), f = n.sourceKey ?? "id", p = g(e, f), y = p.length === 0 ? [] : await _(l, d, p, i, c), b = /* @__PURE__ */ new Map();
+	for (let e of y) {
+		let n = m(l, d, e[d]);
+		if (b.has(n)) throw new o(s({
+			relationName: t,
+			sourceTableName: a.tableName,
+			targetTableName: l.tableName,
+			foreignKey: d,
+			sourceKey: f
+		}));
+		b.set(n, e);
+	}
+	for (let n of e) {
+		let e = m(a, f, n[f]);
+		n[t] = e == null ? null : b.get(e) ?? null;
+	}
+	await v(y, i.with, l, c);
+}, d = async (e, t, n, i, a, o) => {
+	let s = n.target(), c = n.foreignKey ?? r(s, a.tableName, t), l = n.sourceKey ?? "id", u = g(e, l), d = f(i), p = u.length === 0 ? [] : await _(s, c, u, d, o), h = /* @__PURE__ */ new Map(), y = i.offset ?? 0, b = Number.isSafeInteger(y) && y >= 0 && (i.limit === void 0 || Number.isSafeInteger(i.limit) && i.limit >= 0), x = /* @__PURE__ */ new Map();
+	for (let e of p) {
+		let t = m(s, c, e[c]);
+		if (b) {
+			let e = x.get(t) ?? 0;
+			if (x.set(t, e + 1), e < y || i.limit !== void 0 && e - y >= i.limit) continue;
+		}
+		let n = h.get(t);
+		n ? n.push(e) : h.set(t, [e]);
+	}
+	if (!b && (i.limit !== void 0 || i.offset !== void 0)) {
+		let e = i.limit;
+		for (let [t, n] of h) {
+			let r = e === void 0 ? n.slice(y) : n.slice(y, y + e);
+			h.set(t, r);
+		}
+	}
+	for (let n of e) {
+		let e = m(a, l, n[l]);
+		n[t] = h.get(e) ?? [];
+	}
+	i.with !== void 0 && await v([...h.values()].flat(), i.with, s, o);
+}, f = (e) => {
+	let { limit: t, offset: n, ...r } = e;
+	return r;
+}, p = async (t, n, r, i, a, o) => {
+	let s = r.target(), c = r.through(), l = g(t, "id");
+	if (l.length === 0) {
+		for (let e of t) e[n] = [];
+		return;
+	}
+	let u = {
+		column: r.sourceKey,
+		op: "in",
+		value: l
+	}, d = i.onJunction === void 0 ? u : { and: [u, i.onJunction] }, f = await o({
+		table: c.tableName,
+		predicate: d,
+		order: [],
+		take: void 0,
+		skip: void 0,
+		projection: void 0
+	});
+	if (f.length === 0) {
+		for (let e of t) e[n] = [];
+		return;
+	}
+	let p = await _(s, "id", g(f, r.targetKey), i, o), h = new Map(p.map((e) => [m(s, "id", e.id), e]));
+	await v(p, i.with, s, o);
+	let y = i.junction === void 0 ? void 0 : i.junction === !0 ? e(c) : i.junction, b = /* @__PURE__ */ new Map();
+	for (let e of f) {
+		let t = m(c, r.sourceKey, e[r.sourceKey]), n = m(c, r.targetKey, e[r.targetKey]), i = h.get(n);
+		if (i === void 0) continue;
+		let a = y === void 0 ? i : {
+			...i,
+			_junction: Object.fromEntries(y.map((t) => [t, e[t]]))
+		}, o = b.get(t);
+		o ? o.push(a) : b.set(t, [a]);
+	}
+	for (let e of t) e[n] = b.get(m(a, "id", e.id)) ?? [];
+}, m = (e, t, r) => e.fields[t]?.type === "decimal" ? n(r) ?? r : r, h = (e, t) => {
+	for (let [n, r] of Object.entries(e.fields)) if (r.type === "reference" && r.references?.()?.tableName === t) return n;
+}, g = (e, t) => {
+	let n = /* @__PURE__ */ new Set();
+	for (let r of e) {
+		let e = r[t];
+		e != null && n.add(e);
+	}
+	return [...n];
+}, _ = (e, t, n, r, i) => {
+	let a = {
+		column: t,
+		op: "in",
+		value: n
+	}, o = r.where === void 0 ? a : { and: [r.where, a] };
+	return i({
+		table: e.tableName,
+		predicate: o,
+		order: r.orderBy ?? [],
+		take: r.limit,
+		skip: r.offset,
+		projection: void 0
+	});
+}, v = async (e, t, n, r) => {
+	t !== void 0 && e.length !== 0 && (await c(e, t, n, r)).forEach((t, n) => {
+		let r = e[n];
+		for (let [e, n] of Object.entries(t)) e in r || (r[e] = n);
+	});
+}, y = (e) => e.eager !== void 0 && Object.keys(e.eager).length > 0;
+//#endregion
+export { o as EagerCardinalityError, c as attachEagerLoads, y as hasEagerLoads, s as oneCardinalityMessage };