@lobomfz/db 0.4.1 → 0.5.0

package/src/schema-compiler.ts

@@ -0,0 +1,362 @@
+import type { Type } from "arktype";
+
+import type { DbFieldMeta } from "./env.js";
+import type { FtsTableInfo } from "./fts/resolve.js";
+import type { GeneratedPreset } from "./generated.js";
+import type { DesiredColumn, DesiredTable } from "./migration/types.js";
+import type { IndexDefinition, StructureProp } from "./types.js";
+import type { VectorAnchorInfo } from "./vector-index/resolve.js";
+
+type Prop = {
+	key: string;
+	kind: "required" | "optional";
+	domain?: string;
+	nullable?: boolean;
+	isBoolean?: boolean;
+	isInteger?: boolean;
+	isDate?: boolean;
+	isBlob?: boolean;
+	isJson?: boolean;
+	isVector?: boolean;
+	vectorDim?: number;
+	jsonSchema?: Type;
+	meta?: DbFieldMeta;
+	generated?: GeneratedPreset;
+	defaultValue?: unknown;
+};
+
+const typeMap: Record<string, string> = {
+	string: "TEXT",
+	number: "REAL",
+};
+
+export class SchemaCompiler {
+	compileTable(name: string, schema: Type, indexDefs: IndexDefinition[]) {
+		const props = this.parseSchemaProps(schema);
+		const columns = props.map((prop) => this.compileColumn(prop));
+
+		const indexes = indexDefs.map((indexDef) => ({
+			name: this.generateIndexName(name, indexDef.columns, indexDef.unique ?? false),
+			columns: indexDef.columns,
+			sql: this.generateCreateIndexSQL(name, indexDef),
+		}));
+
+		const table: DesiredTable = {
+			name,
+			sql: this.generateCreateTableSQL(name, props),
+			columns,
+			indexes,
+		};
+
+		return {
+			table,
+			tableInfo: this.buildTableInfo(props),
+			vectorAnchor: this.buildVectorAnchorInfo(props),
+		};
+	}
+
+	createWriteSchema(schema: Type) {
+		const autoIncrementColumns = this.parseSchemaProps(schema)
+			.filter((prop) => prop.generated === "autoincrement")
+			.map((prop) => prop.key);
+
+		if (autoIncrementColumns.length === 0) {
+			return schema;
+		}
+
+		return (schema as any).omit(...autoIncrementColumns) as Type;
+	}
+
+	private parseSchemaProps(schema: Type) {
+		const structureProps = (schema as any).structure?.props as StructureProp[] | undefined;
+
+		if (!structureProps) {
+			return [];
+		}
+
+		return structureProps.map((p) => this.normalizeProp(p, schema));
+	}
+
+	private normalizeProp(structureProp: StructureProp, parentSchema: Type) {
+		const { key, value: v, inner } = structureProp;
+		const kind: Prop["kind"] = structureProp.required ? "required" : "optional";
+		const defaultValue = inner.default;
+
+		const concrete = v.branches.filter((b) => b.unit !== null && b.domain !== "undefined");
+		const nullable = concrete.length < v.branches.length;
+
+		const branchMeta = v.branches.find((b) => b.meta && Object.keys(b.meta).length > 0)?.meta;
+		const meta = { ...branchMeta, ...v.meta };
+		const generated = meta._generated === "vector" ? undefined : meta._generated;
+
+		if (meta._generated === "vector") {
+			return {
+				key,
+				kind,
+				nullable,
+				isVector: true,
+				vectorDim: meta._vectorDim,
+				meta,
+				defaultValue,
+			};
+		}
+
+		if (v.proto === Date || concrete.some((b) => b.proto === Date)) {
+			return { key, kind, nullable, isDate: true, generated, defaultValue };
+		}
+
+		if (v.proto === Uint8Array || concrete.some((b) => b.proto === Uint8Array)) {
+			return {
+				key,
+				kind,
+				nullable,
+				isBlob: true,
+				meta,
+				generated,
+				defaultValue,
+			};
+		}
+
+		if (concrete.length > 0 && concrete.every((b) => b.domain === "boolean")) {
+			return { key, kind, nullable, isBoolean: true, generated, defaultValue };
+		}
+
+		if (concrete.some((b) => !!b.structure)) {
+			return {
+				key,
+				kind,
+				nullable,
+				isJson: true,
+				jsonSchema: (parentSchema as any).get(key) as Type,
+				meta,
+				generated,
+				defaultValue,
+			};
+		}
+
+		const branch = concrete[0];
+
+		return {
+			key,
+			kind,
+			nullable,
+			domain: branch?.domain,
+			isInteger: !!branch?.inner?.divisor,
+			meta,
+			generated,
+			defaultValue,
+		};
+	}
+
+	private compileColumn(prop: Prop): DesiredColumn {
+		const isNotNull = this.columnConstraint(prop) === "NOT NULL";
+		const defaultClause = this.defaultClause(prop);
+		const hasLiteralDefault = prop.generated !== "now" && defaultClause !== null;
+
+		return {
+			name: prop.key,
+			addable: !isNotNull || hasLiteralDefault,
+			columnDef: this.addColumnDef(prop),
+			nullableAddDef: this.nullableAddColumnDef(prop),
+			type: this.sqlType(prop),
+			notnull: isNotNull,
+			defaultValue: defaultClause
+				? defaultClause.replace("DEFAULT ", "").replace(/^\((.+)\)$/, "$1")
+				: null,
+			unique: !!prop.meta?.unique,
+			references: prop.meta?.references ?? null,
+			onDelete: prop.meta?.onDelete?.toUpperCase() ?? null,
+		};
+	}
+
+	private sqlType(prop: Prop) {
+		if (prop.isJson) {
+			return "TEXT";
+		}
+
+		if (prop.isBlob || prop.isVector) {
+			return "BLOB";
+		}
+
+		if (prop.isDate || prop.isBoolean || prop.isInteger) {
+			return "INTEGER";
+		}
+
+		if (prop.domain) {
+			return typeMap[prop.domain] ?? "TEXT";
+		}
+
+		return "TEXT";
+	}
+
+	private columnConstraint(prop: Prop) {
+		if (prop.generated === "autoincrement") {
+			return "PRIMARY KEY AUTOINCREMENT";
+		}
+
+		if (prop.meta?.primaryKey) {
+			return "PRIMARY KEY";
+		}
+
+		if (prop.kind === "required" && !prop.nullable) {
+			return "NOT NULL";
+		}
+
+		return null;
+	}
+
+	private defaultClause(prop: Prop) {
+		if (prop.generated === "now") {
+			return "DEFAULT (CAST(unixepoch('subsec') * 1000 AS INTEGER))";
+		}
+
+		if (prop.defaultValue === undefined || prop.generated === "autoincrement") {
+			return null;
+		}
+
+		if (prop.defaultValue === null) {
+			return "DEFAULT NULL";
+		}
+
+		if (typeof prop.defaultValue === "string") {
+			return `DEFAULT '${prop.defaultValue}'`;
+		}
+
+		if (typeof prop.defaultValue === "number" || typeof prop.defaultValue === "boolean") {
+			return `DEFAULT ${prop.defaultValue}`;
+		}
+
+		throw new Error(
+			`Unsupported default value type: ${typeof prop.defaultValue} ${JSON.stringify(prop)}`,
+		);
+	}
+
+	private columnDef(prop: Prop) {
+		return [
+			`"${prop.key}"`,
+			this.sqlType(prop),
+			this.columnConstraint(prop),
+			prop.meta?.unique ? "UNIQUE" : null,
+			this.defaultClause(prop),
+		]
+			.filter(Boolean)
+			.join(" ");
+	}
+
+	private referencesClause(prop: Prop) {
+		const ref = prop.meta?.references;
+
+		if (!ref) {
+			return null;
+		}
+
+		const [table, column] = ref.split(".");
+
+		let clause = ` REFERENCES "${table}"("${column}")`;
+
+		if (prop.meta?.onDelete) {
+			clause += ` ON DELETE ${prop.meta.onDelete.toUpperCase()}`;
+		}
+
+		return clause;
+	}
+
+	private foreignKey(prop: Prop) {
+		const clause = this.referencesClause(prop);
+
+		if (!clause) {
+			return null;
+		}
+
+		return `FOREIGN KEY ("${prop.key}")${clause}`;
+	}
+
+	private addColumnDef(prop: Prop) {
+		return `${this.columnDef(prop)}${this.referencesClause(prop) ?? ""}`;
+	}
+
+	private nullableAddColumnDef(prop: Prop) {
+		return `"${prop.key}" ${this.sqlType(prop)}${this.referencesClause(prop) ?? ""}`;
+	}
+
+	private generateCreateTableSQL(tableName: string, props: Prop[]) {
+		const columns: string[] = [];
+		const fks: string[] = [];
+
+		for (const prop of props) {
+			columns.push(this.columnDef(prop));
+
+			const fk = this.foreignKey(prop);
+
+			if (fk) {
+				fks.push(fk);
+			}
+		}
+
+		return `CREATE TABLE IF NOT EXISTS "${tableName}" (${columns.concat(fks).join(", ")})`;
+	}
+
+	private generateIndexName(tableName: string, columns: string[], unique: boolean) {
+		const prefix = unique ? "ux" : "ix";
+
+		return `${prefix}_${tableName}_${columns.join("_")}`;
+	}
+
+	private generateCreateIndexSQL(tableName: string, indexDef: IndexDefinition) {
+		const indexName = this.generateIndexName(tableName, indexDef.columns, indexDef.unique ?? false);
+		const unique = indexDef.unique ? "UNIQUE " : "";
+		const columns = indexDef.columns.map((c) => `"${c}"`).join(", ");
+
+		return `CREATE ${unique}INDEX "${indexName}" ON "${tableName}" (${columns})`;
+	}
+
+	private buildTableInfo(props: Prop[]): FtsTableInfo {
+		const pkProp = props.find(
+			(p) => p.generated === "autoincrement" || p.meta?.primaryKey === true,
+		);
+
+		return {
+			columns: new Set(props.map((p) => p.key)),
+			pkColumn: pkProp?.key ?? null,
+			pkIsInteger: pkProp ? this.sqlType(pkProp) === "INTEGER" : false,
+			foreignKeys: props.flatMap((p) => {
+				const ref = p.meta?.references;
+
+				if (!ref) {
+					return [];
+				}
+
+				const [referencedTable, referencedColumn] = ref.split(".");
+
+				if (!referencedTable || !referencedColumn) {
+					throw new Error(
+						`Invalid references format "${ref}" for column "${p.key}": expected "table.column"`,
+					);
+				}
+
+				return [{ column: p.key, referencedTable, referencedColumn }];
+			}),
+		};
+	}
+
+	private buildVectorAnchorInfo(props: Prop[]): VectorAnchorInfo {
+		const pkProp = props.find(
+			(p) => p.generated === "autoincrement" || p.meta?.primaryKey === true,
+		);
+
+		const vectorColumns = new Map<string, number>();
+
+		for (const p of props) {
+			if (p.isVector && typeof p.vectorDim === "number") {
+				vectorColumns.set(p.key, p.vectorDim);
+			}
+		}
+
+		return {
+			columns: new Set(props.map((p) => p.key)),
+			pkColumn: pkProp?.key ?? null,
+			pkIsInteger: pkProp ? this.sqlType(pkProp) === "INTEGER" : false,
+			vectorColumns,
+		};
+	}
+}

package/src/types.ts

@@ -1,11 +1,15 @@
-import type { ColumnType, Generated } from "kysely";
+import type { ColumnType, Generated, Kysely } from "kysely";
 import type { Type } from "arktype";
 
+import type { DbFieldMeta } from "./env.js";
+
 export type ArkBranch = {
 	domain?: string;
 	proto?: unknown;
 	unit?: unknown;
 	structure?: unknown;
+	inner?: { divisor?: unknown };
+	meta?: DbFieldMeta;
 };
 
 export type StructureProp = {
@@ -15,6 +19,7 @@ export type StructureProp = {
 	value: Type & {
 		branches: ArkBranch[];
 		proto?: unknown;
+		meta: DbFieldMeta;
 	};
 };
 
@@ -156,6 +161,15 @@ export type JsonValidation = {
 	onRead?: boolean;
 };
 
+export type DataMigration<
+	T extends SchemaRecord,
+	F extends FtsConfig<T> = FtsConfig<T>,
+	V extends VectorIndexConfig<T> = VectorIndexConfig<T>,
+> = {
+	id: string;
+	run: (ctx: { db: Kysely<TablesFromSchemas<T, F, V>> }) => Promise<void> | void;
+};
+
 export type DatabaseOptions<
 	T extends SchemaRecord,
 	F extends FtsConfig<T> = FtsConfig<T>,
@@ -166,4 +180,6 @@ export type DatabaseOptions<
 	pragmas?: DatabasePragmas;
 	validation?: JsonValidation;
 	extensions?: DatabaseExtension[];
+	failOnDataLoss?: boolean;
+	migration?: DataMigration<T, F, V>;
 };