@pvidaal07/heydb 0.0.0-stage → 2.0.0-beta.0

package/lib/model/diff.ts

@@ -0,0 +1,218 @@
+import { formatName } from "./names.ts";
+import { sortSnapshot } from "./order.ts";
+import type { Column, ForeignKey, Index, Routine, Schema, Snapshot, Table, Trigger } from "./snapshot.ts";
+
+// The schema hash says WHETHER the structure changed; the diff says WHAT
+// changed. Both must agree: the diff compares exactly the fields hash.ts
+// copies into its canonical form, and nothing else (never capture time,
+// engine version, row estimates or warnings). If hash.ts gains a field, this
+// file must compare it too; a test checks that both always agree.
+//
+// Objects are matched by name. A renamed column therefore shows up as one
+// removed and one added column: the catalog cannot tell a rename from a drop
+// plus a create, and a wrong guess would be worse than no guess.
+
+export type ChangeKind = "added" | "removed" | "modified";
+
+export type ChangeObject =
+	| "database"
+	| "schema"
+	| "table"
+	| "view"
+	| "column"
+	| "index"
+	| "foreignKey"
+	| "trigger"
+	| "routine";
+
+export interface Change {
+	readonly kind: ChangeKind;
+	readonly object: ChangeObject;
+	/**
+	 * Canonical name of the object. Indexes, foreign keys and triggers belong to a
+	 * table, so they are named like a column of it: "shop.shop.orders.idx_customer".
+	 */
+	readonly target: string;
+	/** For modified objects, one line per changed field, e.g. "type: int → bigint". */
+	readonly details: readonly string[];
+}
+
+export function diffSnapshots(before: Snapshot, after: Snapshot): Change[] {
+	const changes: Change[] = [];
+	const add = (kind: ChangeKind, object: ChangeObject, target: string, details: readonly string[] = []) =>
+		changes.push({ kind, object, target, details });
+
+	// sortSnapshot puts both sides in canonical form first (columns by position,
+	// trigger events sorted), so lists compare exactly as the hash sees them.
+	const a = sortSnapshot(before);
+	const b = sortSnapshot(after);
+
+	matchByKey(a.databases, b.databases, (database) => database.name, {
+		added: (database) => add("added", "database", databaseName(database.name)),
+		removed: (database) => add("removed", "database", databaseName(database.name)),
+		both: (old, current) =>
+			matchByKey(old.schemas, current.schemas, (schema) => schema.name, {
+				added: (schema) => add("added", "schema", formatName({ database: current.name, schema: schema.name })),
+				removed: (schema) => add("removed", "schema", formatName({ database: current.name, schema: schema.name })),
+				both: (oldSchema, schema) => diffSchema(current.name, oldSchema, schema, add),
+			}),
+	});
+
+	return changes.sort(compareChanges);
+}
+
+type AddChange = (kind: ChangeKind, object: ChangeObject, target: string, details?: readonly string[]) => void;
+
+function diffSchema(database: string, before: Schema, after: Schema, add: AddChange): void {
+	const schema = after.name;
+	const tableName = (table: Table) => formatName({ database, schema, table: table.name });
+
+	matchByKey(before.tables, after.tables, (table) => table.name, {
+		added: (table) => add("added", table.kind, tableName(table)),
+		removed: (table) => add("removed", table.kind, tableName(table)),
+		both: (old, current) => diffTable(tableName(current), { database, schema, table: current.name }, old, current, add),
+	});
+
+	// MySQL lets a procedure and a function share a name, so the kind is part of
+	// the key: a procedure replaced by a function is one removed and one added.
+	const routineName = (routine: Routine) => formatName({ database, schema, table: routine.name });
+	matchByKey(before.routines, after.routines, (routine) => `${routine.kind}\u0000${routine.name}`, {
+		added: (routine) => add("added", "routine", routineName(routine), [routine.kind]),
+		removed: (routine) => add("removed", "routine", routineName(routine), [routine.kind]),
+		both: () => {},
+	});
+}
+
+interface TableRef {
+	readonly database: string;
+	readonly schema: string;
+	readonly table: string;
+}
+
+function diffTable(target: string, ref: TableRef, before: Table, after: Table, add: AddChange): void {
+	const details = present([
+		field("kind", before.kind, after.kind),
+		field("comment", quote(before.comment), quote(after.comment)),
+		field("storage engine", quote(before.storageEngine), quote(after.storageEngine)),
+		field("primary key", list(before.primaryKey), list(after.primaryKey)),
+		before.viewDefinition === after.viewDefinition ? null : "definition changed",
+	]);
+	if (details.length > 0) add("modified", after.kind, target, details);
+
+	const childName = (name: string) => formatName({ ...ref, column: name });
+	const diffChildren = <T extends { readonly name: string }>(
+		object: ChangeObject,
+		old: readonly T[],
+		current: readonly T[],
+		compare: (a: T, b: T) => string[],
+	) =>
+		matchByKey(old, current, (item) => item.name, {
+			added: (item) => add("added", object, childName(item.name)),
+			removed: (item) => add("removed", object, childName(item.name)),
+			both: (a, b) => {
+				const changed = compare(a, b);
+				if (changed.length > 0) add("modified", object, childName(b.name), changed);
+			},
+		});
+
+	diffChildren("column", before.columns, after.columns, compareColumns);
+	diffChildren("index", before.indexes, after.indexes, compareIndexes);
+	diffChildren("foreignKey", before.foreignKeys, after.foreignKeys, compareForeignKeys);
+	diffChildren("trigger", before.triggers, after.triggers, compareTriggers);
+}
+
+function compareColumns(a: Column, b: Column): string[] {
+	return present([
+		field("position", String(a.position), String(b.position)),
+		field("type", a.type, b.type),
+		field("nullable", String(a.nullable), String(b.nullable)),
+		field("default", quote(a.default), quote(b.default)),
+		field("comment", quote(a.comment), quote(b.comment)),
+		field("auto increment", String(a.autoIncrement), String(b.autoIncrement)),
+		field("generated", generated(a.generated), generated(b.generated)),
+		field("collation", quote(a.collation), quote(b.collation)),
+	]);
+}
+
+function compareIndexes(a: Index, b: Index): string[] {
+	return present([
+		field("columns", list(a.columns), list(b.columns)),
+		field("unique", String(a.unique), String(b.unique)),
+		field("method", a.method, b.method),
+	]);
+}
+
+function compareForeignKeys(a: ForeignKey, b: ForeignKey): string[] {
+	return present([
+		field("columns", list(a.columns), list(b.columns)),
+		field("references", references(a), references(b)),
+		field("onDelete", a.onDelete, b.onDelete),
+		field("onUpdate", a.onUpdate, b.onUpdate),
+	]);
+}
+
+function compareTriggers(a: Trigger, b: Trigger): string[] {
+	return present([field("timing", a.timing, b.timing), field("events", list(a.events), list(b.events))]);
+}
+
+// Pairs up two lists by key and calls one handler per key: only in `before`
+// (removed), only in `after` (added), or in both. The final sort fixes the order.
+function matchByKey<T>(
+	before: readonly T[],
+	after: readonly T[],
+	key: (item: T) => string,
+	on: { added: (item: T) => void; removed: (item: T) => void; both: (before: T, after: T) => void },
+): void {
+	const old = new Map(before.map((item) => [key(item), item]));
+	const current = new Map(after.map((item) => [key(item), item]));
+	for (const [name, item] of old) {
+		const match = current.get(name);
+		if (match === undefined) on.removed(item);
+		else on.both(item, match);
+	}
+	for (const [name, item] of current) {
+		if (!old.has(name)) on.added(item);
+	}
+}
+
+/** "name: before → after", or null when both sides print the same. */
+function field(name: string, before: string, after: string): string | null {
+	return before === after ? null : `${name}: ${before} → ${after}`;
+}
+
+function present(details: (string | null)[]): string[] {
+	return details.filter((detail) => detail !== null);
+}
+
+// Free text is quoted SQL-style so null, "" and the text "NULL" never look alike.
+function quote(value: string | null): string {
+	return value === null ? "null" : `'${value.replaceAll("'", "''")}'`;
+}
+
+function list(items: readonly string[]): string {
+	return `(${items.join(", ")})`;
+}
+
+function generated(value: Column["generated"]): string {
+	return value === null ? "null" : `${value.expression} ${value.stored ? "STORED" : "VIRTUAL"}`;
+}
+
+function references(foreignKey: ForeignKey): string {
+	const { database, schema, table, columns } = foreignKey.references;
+	return `${formatName({ database, schema, table })}${list(columns)}`;
+}
+
+// formatName needs at least a schema. Formatting with an empty schema (always
+// written as "") and cutting it off reuses its quoting rule for a database alone.
+function databaseName(name: string): string {
+	return formatName({ database: name, schema: "" }).slice(0, -'.""'.length);
+}
+
+function compareChanges(a: Change, b: Change): number {
+	return compareText(a.target, b.target) || compareText(a.object, b.object) || compareText(a.kind, b.kind);
+}
+
+// Plain code-unit comparison, like byName: the order never depends on the locale.
+function compareText(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0;
+}

package/lib/model/hash.ts

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+
+import { sortSnapshot } from "./order.ts";
+import type { Column, Database, ForeignKey, Index, Schema, Snapshot, Table } from "./snapshot.ts";
+
+// The schema hash is a fingerprint of the STRUCTURE only. Two captures of an
+// unchanged database must produce the same hash on any machine, so the
+// canonical form:
+//
+// 1. Copies fields explicitly (a whitelist). Anything not listed here — capture
+//    time, engine version, row estimates, warnings — never affects the hash,
+//    even if a future engine adapter adds new fields.
+// 2. Sorts first with sortSnapshot (order.ts), the same rules the snapshot
+//    files use: unordered collections by name, columns by position, and
+//    meaningful lists (key and index columns) untouched.
+//
+// Changing this canonical form changes every hash: treat it as a breaking change.
+
+export function schemaHash(snapshot: Snapshot): string {
+	const canonical = sortSnapshot(snapshot).databases.map(canonicalDatabase);
+	const digest = createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+	return `sha256:${digest}`;
+}
+
+function canonicalDatabase(database: Database) {
+	return { name: database.name, schemas: database.schemas.map(canonicalSchema) };
+}
+
+function canonicalSchema(schema: Schema) {
+	return {
+		name: schema.name,
+		tables: schema.tables.map(canonicalTable),
+		routines: schema.routines.map((routine) => ({ name: routine.name, kind: routine.kind })),
+	};
+}
+
+function canonicalTable(table: Table) {
+	return {
+		name: table.name,
+		kind: table.kind,
+		comment: table.comment,
+		storageEngine: table.storageEngine,
+		columns: table.columns.map(canonicalColumn),
+		primaryKey: [...table.primaryKey],
+		indexes: table.indexes.map(canonicalIndex),
+		foreignKeys: table.foreignKeys.map(canonicalForeignKey),
+		triggers: table.triggers.map((trigger) => ({
+			name: trigger.name,
+			timing: trigger.timing,
+			events: [...trigger.events],
+		})),
+		viewDefinition: table.viewDefinition,
+	};
+}
+
+function canonicalColumn(column: Column) {
+	return {
+		name: column.name,
+		position: column.position,
+		type: column.type,
+		nullable: column.nullable,
+		default: column.default,
+		comment: column.comment,
+		autoIncrement: column.autoIncrement,
+		generated: column.generated && { expression: column.generated.expression, stored: column.generated.stored },
+		collation: column.collation,
+	};
+}
+
+function canonicalIndex(index: Index) {
+	return { name: index.name, columns: [...index.columns], unique: index.unique, method: index.method };
+}
+
+function canonicalForeignKey(foreignKey: ForeignKey) {
+	const { references } = foreignKey;
+	return {
+		name: foreignKey.name,
+		columns: [...foreignKey.columns],
+		references: {
+			database: references.database,
+			schema: references.schema,
+			table: references.table,
+			columns: [...references.columns],
+		},
+		onDelete: foreignKey.onDelete,
+		onUpdate: foreignKey.onUpdate,
+	};
+}

package/lib/model/names.ts

@@ -0,0 +1,141 @@
+// Canonical names give every object one unambiguous address:
+//
+//   database.schema.table.column
+//
+// Three levels before the column are needed because PostgreSQL has
+// database → schema → table. In MySQL and MariaDB the schema equals the
+// database, so "shop.shop.orders" is the canonical name of table "orders".
+//
+// Real names may contain dots ("v1.old"), so a segment that contains a dot or a
+// double quote, or is empty, is wrapped in double quotes, with inner quotes
+// doubled — the same rule SQL uses for quoted identifiers.
+
+export interface ObjectRef {
+	readonly database: string;
+	readonly schema: string;
+	readonly table?: string;
+	readonly column?: string;
+}
+
+const QUOTE = '"';
+
+export function formatName(ref: ObjectRef): string {
+	if (ref.column !== undefined && ref.table === undefined) {
+		throw new Error(`column "${ref.column}" needs a table`);
+	}
+	const segments = [ref.database, ref.schema];
+	if (ref.table !== undefined) segments.push(ref.table);
+	if (ref.column !== undefined) segments.push(ref.column);
+	return segments.map(formatSegment).join(".");
+}
+
+/**
+ * Names a database on its own, with the quoting rule of every segment:
+ * shop stays shop, v1.old becomes "v1.old". The first segment of every
+ * canonical name inside that database is exactly this text.
+ */
+export function formatDatabaseName(database: string): string {
+	return formatSegment(database);
+}
+
+/**
+ * The name to show people and agents. In MySQL and MariaDB the schema repeats
+ * the database, and "shop.shop.orders.total" makes them read (and pay for) the
+ * same word twice, so it prints as "shop.orders.total", the way MySQL itself
+ * names it. When the schema differs (PostgreSQL) every level stays.
+ *
+ * Display only: snapshots, knowledge files and ids keep the canonical name.
+ * resolveTable and resolveColumn accept both, so whatever heydb prints can be
+ * typed back.
+ */
+export function displayName(ref: ObjectRef): string {
+	if (ref.schema !== ref.database) return formatName(ref);
+	if (ref.column !== undefined && ref.table === undefined) {
+		throw new Error(`column "${ref.column}" needs a table`);
+	}
+	const segments = [ref.database];
+	if (ref.table !== undefined) segments.push(ref.table);
+	if (ref.column !== undefined) segments.push(ref.column);
+	return segments.map(formatSegment).join(".");
+}
+
+/** displayName of a canonical name such as "shop.shop.orders". */
+export function displayNameOf(canonical: string): string {
+	return displayName(parseName(canonical));
+}
+
+function formatSegment(segment: string): string {
+	const needsQuotes = segment === "" || segment.includes(".") || segment.includes(QUOTE);
+	if (!needsQuotes) return segment;
+	return QUOTE + segment.replaceAll(QUOTE, QUOTE + QUOTE) + QUOTE;
+}
+
+export function parseName(text: string): ObjectRef {
+	const segments = parseSegments(text);
+	if (segments.length < 2 || segments.length > 4) {
+		throw new Error(`invalid name "${text}": expected 2 to 4 segments, got ${segments.length}`);
+	}
+	const [database, schema, table, column] = segments as [string, string, string?, string?];
+	return {
+		database,
+		schema,
+		...(table !== undefined && { table }),
+		...(column !== undefined && { column }),
+	};
+}
+
+/**
+ * Splits a dotted name into its segments with the same quoting rules as
+ * parseName, but accepts any number of them. People and agents write partial
+ * names ("orders", "shop.orders"); this reads them without guessing what each
+ * segment is.
+ *
+ * Reads one segment at a time. A segment is either quoted ("...") or plain
+ * text up to the next dot. After each segment we must be at the end of the
+ * text or at a dot that starts the next segment.
+ */
+export function parseSegments(text: string): string[] {
+	const segments: string[] = [];
+	let index = 0;
+
+	while (true) {
+		if (text[index] === QUOTE) {
+			const quoted = readQuoted(text, index);
+			segments.push(quoted.value);
+			index = quoted.end;
+		} else {
+			const dot = text.indexOf(".", index);
+			const end = dot === -1 ? text.length : dot;
+			const plain = text.slice(index, end);
+			if (plain === "") throw new Error(`invalid name "${text}": empty segment must be written as ""`);
+			if (plain.includes(QUOTE)) throw new Error(`invalid name "${text}": quote inside unquoted segment "${plain}"`);
+			segments.push(plain);
+			index = end;
+		}
+
+		if (index === text.length) return segments;
+		if (text[index] !== ".") {
+			throw new Error(`invalid name "${text}": unexpected "${text[index]}" after closing quote`);
+		}
+		index += 1;
+	}
+}
+
+// Starts at an opening quote; returns the unquoted value and the index after the closing quote.
+function readQuoted(text: string, start: number): { value: string; end: number } {
+	let value = "";
+	let index = start + 1;
+	while (index < text.length) {
+		if (text[index] === QUOTE) {
+			if (text[index + 1] === QUOTE) {
+				value += QUOTE;
+				index += 2;
+				continue;
+			}
+			return { value, end: index + 1 };
+		}
+		value += text[index];
+		index += 1;
+	}
+	throw new Error(`invalid name "${text}": unterminated quote`);
+}

package/lib/model/order.ts

@@ -0,0 +1,47 @@
+import type { Snapshot, Table, Warning } from "./snapshot.ts";
+
+// Ordering rules shared by everything that needs a stable snapshot (the hash,
+// the files written to disk):
+// - collections whose order carries no meaning are sorted by name (warnings by
+//   code, target and message);
+// - columns are sorted by their position in the table;
+// - lists whose order DOES carry meaning are kept as they are: primary key
+//   columns, index columns, foreign key columns.
+
+// Returns a sorted copy; never mutates the input. Plain code-unit comparison
+// (not localeCompare) so the result does not depend on the machine's locale.
+export function byName<T extends { readonly name: string }>(items: readonly T[]): T[] {
+	return [...items].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/** A copy of the snapshot with every unordered collection in canonical order. */
+export function sortSnapshot(snapshot: Snapshot): Snapshot {
+	return {
+		...snapshot,
+		databases: byName(snapshot.databases).map((database) => ({
+			...database,
+			schemas: byName(database.schemas).map((schema) => ({
+				...schema,
+				tables: byName(schema.tables).map(sortTable),
+				routines: byName(schema.routines),
+			})),
+		})),
+		warnings: [...snapshot.warnings].sort(compareWarnings),
+	};
+}
+
+function compareWarnings(a: Warning, b: Warning): number {
+	const keyA = `${a.code}\u0000${a.target ?? ""}\u0000${a.message}`;
+	const keyB = `${b.code}\u0000${b.target ?? ""}\u0000${b.message}`;
+	return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
+}
+
+function sortTable(table: Table): Table {
+	return {
+		...table,
+		columns: [...table.columns].sort((a, b) => a.position - b.position),
+		indexes: byName(table.indexes),
+		foreignKeys: byName(table.foreignKeys),
+		triggers: byName(table.triggers).map((trigger) => ({ ...trigger, events: [...trigger.events].sort() })),
+	};
+}