@clivly/core 0.9.7 → 0.10.0

package/dist/builder.mjs

@@ -0,0 +1,589 @@
+import { n as PROJECTION_KEY_PATTERN, t as BASE_REF } from "./projection-SCNrLJMV.mjs";
+import { i as primaryKeyColumns, n as coversUniqueKey, r as hasRichMeta } from "./schema-meta-Ac7938mT.mjs";
+//#region src/path-compiler.ts
+/**
+* Compiles picked paths into a `ProjectionMapping` whose joins are in
+* dependency order.
+*
+* This is the last step of the derived-object builder: the user has browsed
+* outward from a starting list and picked fields, and this turns those picks
+* into the existing projection contract — unchanged, so validation, view
+* compilation, paging and sync all consume it as they already do.
+*
+* Four properties carry the weight:
+*
+* 1. **Joins dedupe by edge path, not by table.** Ten fields reached through
+*    the same chain of relationships produce one join. Two chains that land on
+*    the same table through *different* foreign keys stay two joins, because
+*    they are two genuinely different relationships. The ordered edge path is
+*    the join's identity.
+*
+* 2. **Dependency order.** Joins are emitted shortest-prefix-first, so a
+*    join's ON condition only ever references the base table or a join already
+*    declared above it. `validateProjection`'s forward-reference check is the
+*    external proof of this, and SQL requires it.
+*
+* 3. **No raw table name is ever an alias.** Every join key is derived from
+*    the full edge path — including which FK column each hop followed — and
+*    uniquified deterministically. A table-derived alias would silently
+*    collapse two different relationships into one.
+*
+* 4. **Collections never compile.** A path that crosses a to-many edge
+*    resolves to many rows, not a value. Emitting one as a join would fan the
+*    output out and quietly duplicate or collapse mirror rows at sync time.
+*    Asked to compile one, this throws rather than emitting something
+*    plausible.
+*
+* No table, column, or relationship is ever named in this file — the only
+* inputs are the schema, the starting table, and the user's picks.
+*/
+/** The reserved binding name; the view always projects identity as `id`. */
+const RESERVED_FIELD = "id";
+/**
+* Thrown when picks cannot compile to a valid projection.
+*
+* A distinct class so a builder UI can tell "this cannot be expressed" apart
+* from a genuine bug, and so callers can catch it narrowly. Failing loudly is
+* the point: the alternative — emitting a plausible-looking mapping — is the
+* defect class this whole body of work exists to close.
+*/
+var PathCompileError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PathCompileError";
+	}
+};
+/**
+* Reduce an arbitrary identifier to the projection key charset.
+*
+* Table and column names come from the host's schema and are not constrained
+* to `PROJECTION_KEY_PATTERN` — they may carry capitals, spaces, or leading
+* digits. Sanitizing is lossy on purpose (two different names can reduce to
+* the same token), which is exactly why the caller disambiguates afterwards
+* rather than trusting this to be injective.
+*/
+function sanitize(part) {
+	return part.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+/**
+* A key candidate for the join reached by `edges`.
+*
+* Every hop contributes both the FK column it followed and the table it landed
+* on. Carrying the column is what keeps two FKs into the same table apart:
+* without it, both hops would reduce to the destination table's name and the
+* two relationships would collide into one alias.
+*/
+function keyCandidate(edges) {
+	const joined = edges.flatMap((edge) => [sanitize(edge.fromColumn), sanitize(edge.toTable)]).filter(Boolean).join("_");
+	return PROJECTION_KEY_PATTERN.test(joined) ? joined : `j_${joined}`;
+}
+/** The ordered prefixes of a path, longest last. Each prefix is one join. */
+function prefixesOf(edges) {
+	return edges.map((_, index) => edges.slice(0, index + 1));
+}
+/**
+* Identity of a join: the full ordered edge path, including direction and both
+* column halves of every hop.
+*
+* This is the deduplication key and it is exact — unlike the *display* key,
+* nothing here is sanitized or lossy, so two distinct relationships can never
+* be conflated into one join.
+*/
+function prefixIdentity(edges) {
+	return edges.map((e) => `${e.direction}:${e.fromTable}.${e.fromColumn}->${e.toTable}.${e.toColumn}`).join("|");
+}
+/** Assigns each distinct edge path a unique, deterministic key. */
+var JoinKeyAllocator = class {
+	byIdentity = /* @__PURE__ */ new Map();
+	taken = /* @__PURE__ */ new Set([BASE_REF]);
+	/**
+	* The key for this edge path, allocating one on first sight.
+	*
+	* Collisions are resolved by a counter rather than by anything derived from
+	* call order beyond first-sight order, which is itself deterministic
+	* because joins are visited in a fixed sorted order. The same picks
+	* therefore always produce the same keys.
+	*/
+	keyFor(edges) {
+		const identity = prefixIdentity(edges);
+		const existing = this.byIdentity.get(identity);
+		if (existing) return existing;
+		const candidate = keyCandidate(edges);
+		let key = candidate;
+		let suffix = 2;
+		while (this.taken.has(key)) {
+			key = `${candidate}_${suffix}`;
+			suffix += 1;
+		}
+		this.taken.add(key);
+		this.byIdentity.set(identity, key);
+		return key;
+	}
+};
+/** The ref an edge path resolves to: `base` for the root, else a join key. */
+function refTableFor(edges, allocator) {
+	return edges.length === 0 ? BASE_REF : allocator.keyFor(edges);
+}
+function buildJoin(edges, allocator) {
+	const edge = edges.at(-1);
+	if (!edge) throw new PathCompileError("cannot build a join from an empty path");
+	const parentRef = refTableFor(edges.slice(0, -1), allocator);
+	const key = allocator.keyFor(edges);
+	const left = {
+		table: parentRef,
+		column: edge.fromColumn
+	};
+	const right = {
+		table: key,
+		column: edge.toColumn
+	};
+	return {
+		key,
+		table: edge.toTable,
+		type: "left",
+		on: [{
+			left,
+			op: "eq",
+			right
+		}]
+	};
+}
+function assertCompilable(field, startTable) {
+	const path = field.path;
+	if (!path || path.edges.length === 0) return;
+	if (path.isCollection) throw new PathCompileError(`field "${field.name}" is reached through a collection (a to-one relationship is required); a collection is many rows, not a value, so it must be started as its own list rather than compiled into a join`);
+	const first = path.edges[0];
+	if (first && first.fromTable !== startTable) throw new PathCompileError(`field "${field.name}" follows a path starting at "${first.fromTable}", not the starting table "${startTable}"`);
+}
+function validatePicks(options) {
+	const { pickedFields, startTable } = options;
+	if (pickedFields.length === 0) throw new PathCompileError("at least one field must be picked");
+	const seen = /* @__PURE__ */ new Set();
+	for (const field of pickedFields) {
+		if (field.name === RESERVED_FIELD) throw new PathCompileError(`"${RESERVED_FIELD}" is a reserved field name — the view always projects identity as "${RESERVED_FIELD}"`);
+		if (seen.has(field.name)) throw new PathCompileError(`duplicate field name "${field.name}"`);
+		seen.add(field.name);
+		assertCompilable(field, startTable);
+	}
+}
+/**
+* The starting table's single-column primary key.
+*
+* Fails closed on absent or composite keys rather than guessing a column: an
+* identity that is not provably unique per row is the failure mode that
+* silently duplicates or collapses mirror rows at sync time.
+*/
+function basePrimaryKey(schema, startTable) {
+	const table = schema.find((t) => t.name === startTable);
+	if (!table) throw new PathCompileError(`starting table "${startTable}" is not in the discovered schema`);
+	const pk = primaryKeyColumns(table);
+	const [column] = pk;
+	if (!column) throw new PathCompileError(`"${startTable}" has no discovered single-column primary key, which a derived object needs to identify its rows`);
+	if (pk.length > 1) throw new PathCompileError(`"${startTable}" has a composite primary key (${pk.join(", ")}), which cannot be used as a derived object's identity`);
+	return column;
+}
+/**
+* Every distinct edge-path prefix used by at least one picked field, ordered
+* shortest first.
+*
+* Ordering by depth is what puts joins in dependency order: a prefix of length
+* n can only reference the base table or its own length n-1 prefix, both of
+* which sort strictly earlier. Ties within a depth break on the exact path
+* identity, so the order is total and stable across runs.
+*/
+function requiredPrefixes(pickedFields) {
+	const byIdentity = /* @__PURE__ */ new Map();
+	for (const field of pickedFields) for (const prefix of prefixesOf(field.path?.edges ?? [])) {
+		const identity = prefixIdentity(prefix);
+		if (!byIdentity.has(identity)) byIdentity.set(identity, prefix);
+	}
+	return [...byIdentity.entries()].sort(([leftId, left], [rightId, right]) => {
+		const byDepth = left.length - right.length;
+		if (byDepth !== 0) return byDepth;
+		if (leftId === rightId) return 0;
+		return leftId < rightId ? -1 : 1;
+	}).map(([, prefix]) => prefix);
+}
+/**
+* Compile picked fields into a projection mapping.
+*
+* Throws `PathCompileError` when the picks cannot be expressed — a collection
+* path, a missing primary key, a reserved or duplicated field name. Every
+* mapping it returns satisfies `projectionSchema` and, given a schema whose
+* tables carry rich metadata, `validateProjection`.
+*/
+function compilePaths(options) {
+	const { entityKey, pickedFields, schema, startTable } = options;
+	validatePicks(options);
+	const identityColumn = basePrimaryKey(schema, startTable);
+	const allocator = new JoinKeyAllocator();
+	const joins = requiredPrefixes(pickedFields).map((prefix) => buildJoin(prefix, allocator));
+	const fieldBindings = {};
+	for (const field of pickedFields) {
+		const table = refTableFor(field.path?.edges ?? [], allocator);
+		fieldBindings[field.name] = { from: {
+			table,
+			column: field.column
+		} };
+	}
+	return {
+		version: 1,
+		kind: "projection",
+		entityKey,
+		baseTable: startTable,
+		joins,
+		fieldBindings,
+		identity: {
+			kind: "base_pk",
+			column: identityColumn
+		}
+	};
+}
+//#endregion
+//#region src/relationship-graph.ts
+const NO_RICH_META_REASON$1 = { code: "no-rich-meta" };
+/** Every edge whose `fromTable` is `table`, in either direction. */
+function edgesFrom(graph, table) {
+	return graph.edges.filter((edge) => edge.fromTable === table);
+}
+function childToParentCardinality(parentTable, parentColumn) {
+	return coversUniqueKey(parentTable, [parentColumn]) ? "to-one" : "to-many";
+}
+function parentToChildCardinality(childTable, childFkColumn) {
+	return coversUniqueKey(childTable, [childFkColumn]) ? "to-one" : "to-many";
+}
+/**
+* Build the bidirectional relationship graph for a discovered schema.
+*
+* No table, column, or relationship is ever named in this function — the
+* only input is the schema itself.
+*/
+function buildRelationshipGraph(schema) {
+	const tablesByName = new Map(schema.map((table) => [table.name, table]));
+	const nodes = schema.map((table) => hasRichMeta(table) ? {
+		table: table.name,
+		offerable: true
+	} : {
+		table: table.name,
+		offerable: false,
+		reason: NO_RICH_META_REASON$1
+	});
+	const edges = [];
+	for (const table of schema) {
+		if (!hasRichMeta(table)) continue;
+		for (const column of table.columnsMeta) {
+			const ref = column.references;
+			if (!ref) continue;
+			const parentTable = tablesByName.get(ref.table);
+			if (!(parentTable && hasRichMeta(parentTable))) continue;
+			edges.push({
+				fromTable: table.name,
+				fromColumn: column.name,
+				toTable: parentTable.name,
+				toColumn: ref.column,
+				direction: "child-to-parent",
+				cardinality: childToParentCardinality(parentTable, ref.column)
+			});
+			edges.push({
+				fromTable: parentTable.name,
+				fromColumn: ref.column,
+				toTable: table.name,
+				toColumn: column.name,
+				direction: "parent-to-child",
+				cardinality: parentToChildCardinality(table, column.name)
+			});
+		}
+	}
+	return {
+		nodes,
+		edges
+	};
+}
+//#endregion
+//#region src/path-enumeration.ts
+/**
+* Breadth-first enumeration of the paths reachable from a starting table.
+*
+* This is the "browse outward" engine behind the derived-object builder: the
+* user picks a starting list and we show them what else is reachable, without
+* ever naming a join, a base table, or an ON condition.
+*
+* Three properties matter enough to be spelled out:
+*
+* 1. **Cycles terminate.** A table already on a path is not revisited, so a
+*    self-referencing table yields its one-hop neighbours and stops. Parallel
+*    edges are still distinct: edge identity is the FK column pair, not the
+*    table pair, so two FKs into the same table stay two relationships.
+*
+* 2. **To-many is sticky.** Once a path crosses a to-many edge, everything at
+*    or beyond it is a *collection* — a list of rows, not a single value. Those
+*    paths are not pickable columns and must never be compiled into joins; the
+*    UI shows them with a "start a list of X" action instead.
+*
+* 3. **Truncation is reported, never silent.** Hitting a budget is part of the
+*    return value so the UI can say deeper paths are hidden and offer a
+*    narrower search, rather than quietly showing a partial answer as if it
+*    were the whole one.
+*
+* No table, column, or relationship is ever named here — the only inputs are
+* the graph and the starting table.
+*/
+/** Spec-mandated: how many edges deep a path may go. */
+const MAX_HOPS = 3;
+/** Spec-mandated: how many candidate paths may be considered before stopping. */
+const MAX_CANDIDATES = 200;
+/** Spec-mandated: how many ranked results may be displayed. */
+const MAX_RESULTS = 50;
+/**
+* `direction` is part of the key, not decoration. A column that is both a PK
+* and a self-FK (`t.id` referencing `t.id`) emits two genuinely different
+* edges — one child-to-parent, one parent-to-child — whose table/column
+* halves are identical. Without `direction` they collapse to one key, which
+* makes two distinct paths indistinguishable to the comparator and leaves
+* `Array.prototype.sort` free to order them either way.
+*/
+function edgeKey(edge) {
+	return `${edge.direction}:${edge.fromTable}.${edge.fromColumn}->${edge.toTable}.${edge.toColumn}`;
+}
+function pathKey(edges) {
+	return edges.map(edgeKey).join("|");
+}
+/**
+* Does the path's destination carry a column named exactly `field`?
+*
+* Only an exact match counts. A fuzzy match here would reorder results for
+* reasons a user cannot see, and the ordering is load-bearing downstream.
+*/
+function matchesField(path, field, columnsByTable) {
+	if (!field) return false;
+	const columns = columnsByTable?.get(path.toTable);
+	return columns ? columns.includes(field) : false;
+}
+/**
+* Total order over paths: hop count, then exact field match, then the stable
+* key. The key tiebreak is what makes the order total — without it, equal-rank
+* paths would keep their input order, which is stable per run but would drift
+* the moment edge construction changed.
+*
+* Returns 0 on equal keys rather than an arbitrary 1. A comparator that
+* answers 1 for both (a, b) and (b, a) is *inconsistent*, and
+* `Array.prototype.sort` is explicitly allowed to order such elements however
+* it likes — which would make Task 5's ordering invariant flake rather than
+* fail cleanly. Keys are unique in practice now that `edgeKey` carries
+* `direction`, so this is defence against the class, not a live collision.
+*/
+function comparePaths(left, right, field, columnsByTable) {
+	const byHops = left.edges.length - right.edges.length;
+	if (byHops !== 0) return byHops;
+	const leftMatch = matchesField(left, field, columnsByTable);
+	if (leftMatch !== matchesField(right, field, columnsByTable)) return leftMatch ? -1 : 1;
+	if (left.key === right.key) return 0;
+	return left.key < right.key ? -1 : 1;
+}
+/**
+* Should this edge be followed from `path`?
+*
+* A self-referencing FK is a real relationship a user browses to (a row's
+* parent row), so it is offered as a one-hop path even though it lands back
+* on the starting table. It is never extended: the destination is already on
+* the path, so the next level rejects it and the cycle terminates.
+*/
+function canFollow(entry, edge) {
+	const isSelfEdgeFromStart = entry.path.edges.length === 0 && edge.toTable === edge.fromTable;
+	return !entry.visited.has(edge.toTable) || isSelfEdgeFromStart;
+}
+function extend(entry, edge) {
+	const edges = [...entry.path.edges, edge];
+	return {
+		path: {
+			edges,
+			toTable: edge.toTable,
+			isCollection: entry.path.isCollection || edge.cardinality === "to-many",
+			key: pathKey(edges)
+		},
+		visited: /* @__PURE__ */ new Set([...entry.visited, edge.toTable])
+	};
+}
+/**
+* Expand one breadth-first level, appending to `candidates`.
+*
+* Returns the next frontier, or `undefined` when the candidate budget ran out
+* mid-level — the caller treats that as truncation and stops.
+*/
+function expandLevel(graph, frontier, candidates, maxCandidates) {
+	const next = [];
+	for (const entry of frontier) for (const edge of edgesFrom(graph, entry.path.toTable)) {
+		if (!canFollow(entry, edge)) continue;
+		if (candidates.length >= maxCandidates) return;
+		const extended = extend(entry, edge);
+		candidates.push(extended.path);
+		next.push(extended);
+	}
+	return next;
+}
+/**
+* Enumerate every path reachable from `startTable`, ranked and budgeted.
+*
+* Breadth-first, so the candidate budget always cuts the deepest frontier
+* rather than an arbitrary slice of a half-explored level.
+*
+* Note the order of operations: ranking happens *after* the candidate budget
+* has already stopped the walk. A path that would have ranked highly but sits
+* beyond the 200th candidate is therefore never seen, and no amount of
+* ranking recovers it. That is inherent to bounding the search rather than a
+* defect — and it is precisely why truncation is reported, so the UI can
+* offer a narrower search instead of implying the list is complete.
+*/
+function enumeratePaths(graph, startTable, options = {}) {
+	const maxHops = options.maxHops ?? 3;
+	const maxCandidates = options.maxCandidates ?? 200;
+	const maxResults = options.maxResults ?? 50;
+	const candidates = [];
+	let truncatedBy;
+	let frontier = [{
+		path: {
+			edges: [],
+			toTable: startTable,
+			isCollection: false,
+			key: ""
+		},
+		visited: /* @__PURE__ */ new Set([startTable])
+	}];
+	for (let hop = 0; hop < maxHops && frontier.length > 0; hop += 1) {
+		const next = expandLevel(graph, frontier, candidates, maxCandidates);
+		if (!next) {
+			truncatedBy = "candidate-budget";
+			break;
+		}
+		frontier = next;
+	}
+	const columnsByTable = options.columnsByTable;
+	const ranked = [...candidates].sort((left, right) => comparePaths(left, right, options.field, columnsByTable));
+	const paths = ranked.slice(0, maxResults);
+	if (!truncatedBy && ranked.length > maxResults) truncatedBy = "result-limit";
+	return {
+		paths,
+		truncated: Boolean(truncatedBy),
+		truncatedBy,
+		candidatesConsidered: candidates.length
+	};
+}
+//#endregion
+//#region src/starting-record-change.ts
+/** Does this table have a column of exactly this name? */
+function hasColumn(schema, table, column) {
+	const found = schema.find((entry) => entry.name === table);
+	return found ? found.columns.includes(column) : false;
+}
+/**
+* The route a pick would have from the new starting record, or `null` when it
+* has none.
+*
+* Returns `{ path: undefined }` — deliberately distinct from `null` — when the
+* field is a column of the new starting record itself. That is a survivor
+* reached by no route, which is exactly what `PickedField.path` being absent
+* means to `compilePaths`.
+*/
+function repoint(schema, paths, toTable, pick) {
+	if (hasColumn(schema, toTable, pick.column)) return { path: void 0 };
+	const destination = pick.path?.toTable ?? void 0;
+	const candidates = paths.filter((path) => !path.isCollection);
+	if (destination !== void 0) {
+		const match = candidates.find((path) => path.toTable === destination && hasColumn(schema, path.toTable, pick.column));
+		return match ? { path: match } : null;
+	}
+	const match = candidates.find((path) => hasColumn(schema, path.toTable, pick.column));
+	return match ? { path: match } : null;
+}
+/**
+* Identify the connection a pick travelled over, for counting.
+*
+* The path key, not the destination table: two FKs from one table into the
+* same table — a ticket's assignee and its reviewer — are two genuinely
+* different connections that both end at `users`. Counting by destination
+* would collapse them into one and under-report what the user loses.
+*
+* `null` means the pick was a column of the starting record, which is not a
+* connection.
+*/
+function connectionOf(pick) {
+	if (!pick.path || pick.path.edges.length === 0) return null;
+	return pick.path.key;
+}
+/**
+* Classify what changing the starting record does to a set of picked fields.
+*
+* Pure and total: an unknown `to` table simply has no reachable paths, so
+* every pick that is not one of its own columns is reported removed. It never
+* throws, because its caller is a confirmation dialog that must be able to
+* render an answer for any proposed change, including a nonsensical one.
+*/
+function classifyStartingRecordChange(options) {
+	const { from, picks, schema, to } = options;
+	if (from === to) return {
+		keptFields: [...picks],
+		removedConnectionCount: 0,
+		removedFields: []
+	};
+	const { paths } = enumeratePaths(buildRelationshipGraph(schema), to);
+	const keptFields = [];
+	const removedFields = [];
+	const removedConnections = /* @__PURE__ */ new Set();
+	for (const pick of picks) {
+		const repointed = repoint(schema, paths, to, pick);
+		if (repointed) {
+			keptFields.push({
+				column: pick.column,
+				name: pick.name,
+				...repointed.path ? { path: repointed.path } : {}
+			});
+			continue;
+		}
+		removedFields.push(pick);
+		const connection = connectionOf(pick);
+		if (connection !== null) removedConnections.add(connection);
+	}
+	return {
+		keptFields,
+		removedConnectionCount: removedConnections.size,
+		removedFields
+	};
+}
+//#endregion
+//#region src/starting-record-eligibility.ts
+const NO_RICH_META_REASON = { code: "no-rich-meta" };
+const COMPOSITE_PK_REASON = { code: "composite-pk" };
+const NO_PRIMARY_KEY_REASON = { code: "no-primary-key" };
+/**
+* List every table in the discovered schema with its starting-record
+* eligibility, in schema order.
+*
+* No table, column, or relationship is ever named in this function — the
+* only input is the schema itself.
+*/
+function listStartingRecordOptions(schema) {
+	return schema.map((table) => {
+		if (!hasRichMeta(table)) return {
+			table: table.name,
+			offerable: false,
+			reason: NO_RICH_META_REASON
+		};
+		const pk = primaryKeyColumns(table);
+		if (pk.length > 1) return {
+			table: table.name,
+			offerable: false,
+			reason: COMPOSITE_PK_REASON
+		};
+		if (pk.length === 0) return {
+			table: table.name,
+			offerable: false,
+			reason: NO_PRIMARY_KEY_REASON
+		};
+		return {
+			table: table.name,
+			offerable: true
+		};
+	});
+}
+//#endregion
+export { MAX_CANDIDATES, MAX_HOPS, MAX_RESULTS, PathCompileError, buildRelationshipGraph, classifyStartingRecordChange, compilePaths, edgesFrom, enumeratePaths, listStartingRecordOptions };

package/dist/drizzle.d.cts

@@ -1,4 +1,4 @@
-import { m as DiscoveredSchemaTable, p as DiscoveredColumnMeta } from "./entity-config-buOIVtMM.cjs";
+import { m as DiscoveredSchemaTable, p as DiscoveredColumnMeta } from "./entity-config-DCa785OE.cjs";
 import { Table } from "drizzle-orm";
 //#region src/drizzle.d.ts
 /**

package/dist/drizzle.d.mts

@@ -1,4 +1,4 @@
-import { m as DiscoveredSchemaTable, p as DiscoveredColumnMeta } from "./entity-config-buOIVtMM.mjs";
+import { m as DiscoveredSchemaTable, p as DiscoveredColumnMeta } from "./entity-config-DCa785OE.mjs";
 import { Table } from "drizzle-orm";
 //#region src/drizzle.d.ts
 /**