@db3.ai/app 0.1.0-beta.1

package/dist/db/migrations/KnexMigrationRenderer.js

@@ -0,0 +1,390 @@
+/**
+ * Renders a frozen TypeScript Knex migration from a safe schema plan.
+ *
+ * Generated source contains literal table, column, index, and foreign-key
+ * operations. It never imports current models or field implementations.
+ *
+ * @param plan - Pure schema plan with no blocked changes.
+ * @returns Deterministic TypeScript migration source.
+ */
+export function renderKnexMigration(plan) {
+    if (plan.blockedChanges.length > 0) {
+        throw new Error('Cannot render a migration plan containing blocked changes.');
+    }
+    if (plan.safeChanges.length === 0) {
+        throw new Error('Cannot render an empty database migration.');
+    }
+    const lines = [
+        "import type { Knex } from 'knex';",
+        '',
+        '/** Knex migration settings for MariaDB non-transactional DDL. */',
+        'export const config = { transaction: false };',
+        '',
+        '/** Frozen schema lineage recorded when this migration was generated. */',
+        'export const schema = {',
+        `\tfrom: ${quote(plan.fromHash)},`,
+        `\tto: ${quote(plan.toHash)},`,
+        '};',
+        '',
+        '/**',
+        ' * Applies this forward-only generated database migration.',
+        ' *',
+        ' * @param knex - Knex connection managed by the application migration runner.',
+        ' * @returns Promise that resolves after every schema operation completes.',
+        ' */',
+        'export async function up(knex: Knex): Promise<void> {',
+    ];
+    const body = renderMigrationBody(plan.safeChanges);
+    lines.push(...body.map(line => line ? `\t${line}` : ''));
+    lines.push('}', '', '/**', ' * Refuses automatic rollback because generated MariaDB DDL is forward-only.', ' *', ' * @param _knex - Unused Knex connection supplied by the migration runner.', ' * @returns Promise that always rejects before performing database DDL.', ' */', 'export async function down(_knex: Knex): Promise<void> {', "\tthrow new Error('Generated database migrations are forward-only.');", '}', '');
+    return lines.join('\n');
+}
+/**
+ * Orders migration DDL so all new tables exist before foreign keys are added.
+ *
+ * @param changes - Safe normalized schema changes.
+ * @returns TypeScript statements without the outer function indentation.
+ */
+function renderMigrationBody(changes) {
+    const lines = [];
+    const createTables = changes.filter(isChangeKind('create_table'));
+    const otherChanges = changes.filter(change => change.kind !== 'create_table');
+    for (const change of otherChanges) {
+        if (change.kind === 'drop_foreign_key') {
+            appendStatement(lines, renderDropForeignKey(change.tableName, change.foreignKeyName));
+        }
+    }
+    for (const change of otherChanges) {
+        if (change.kind === 'drop_index') {
+            appendStatement(lines, renderDropIndex(change.tableName, change.indexName));
+        }
+    }
+    for (const change of otherChanges) {
+        if (change.kind === 'drop_column') {
+            appendStatement(lines, renderDropColumn(change.tableName, change.columnName));
+        }
+    }
+    for (const change of createTables) {
+        appendStatement(lines, renderCreateTable(change.table));
+    }
+    for (const change of otherChanges) {
+        if (change.kind === 'alter_table_comment') {
+            appendStatement(lines, renderAlterTableComment(change.tableName, change.comment));
+        }
+    }
+    for (const change of otherChanges) {
+        if (change.kind === 'add_column') {
+            appendStatement(lines, renderAddColumn(change.tableName, change.column));
+        }
+        if (change.kind === 'alter_column') {
+            appendStatement(lines, renderAlterColumn(change));
+        }
+    }
+    for (const change of otherChanges) {
+        if (change.kind === 'add_index') {
+            appendStatement(lines, renderAddIndex(change.tableName, change.index));
+        }
+    }
+    const foreignKeys = [
+        ...createTables.flatMap(change => {
+            return change.table.foreignKeys.map(foreignKey => ({
+                tableName: change.table.name,
+                foreignKey,
+            }));
+        }),
+        ...otherChanges.flatMap(change => {
+            return change.kind === 'add_foreign_key'
+                ? [{ tableName: change.tableName, foreignKey: change.foreignKey }]
+                : [];
+        }),
+    ];
+    for (const { tableName, foreignKey } of foreignKeys) {
+        appendStatement(lines, renderAddForeignKey(tableName, foreignKey));
+    }
+    for (const change of otherChanges) {
+        if (change.kind === 'drop_table') {
+            appendStatement(lines, renderDropTable(change.tableName));
+        }
+    }
+    return lines;
+}
+/**
+ * Appends one statement separated from the previous statement by a blank line.
+ *
+ * @param target - Mutable migration body lines.
+ * @param statement - Complete statement lines to append.
+ */
+function appendStatement(target, statement) {
+    if (target.length > 0)
+        target.push('');
+    target.push(...statement);
+}
+/**
+ * Renders one table creation without foreign keys, which are emitted later.
+ *
+ * @param table - Complete desired table definition.
+ * @returns TypeScript statement lines.
+ */
+function renderCreateTable(table) {
+    const lines = [
+        `await knex.schema.createTable(${quote(table.name)}, table => {`,
+    ];
+    for (const column of table.columns) {
+        lines.push(...indent(renderColumn(column, {
+            creation: true,
+            alterNullable: true,
+            alterType: true,
+            alterComment: true,
+        })));
+    }
+    for (const index of table.indexes) {
+        lines.push(...indent(renderIndex(index)));
+    }
+    if (table.comment) {
+        lines.push(`\ttable.comment(${quote(table.comment)});`);
+    }
+    lines.push('});');
+    return lines;
+}
+/**
+ * Renders one nullable-column addition.
+ *
+ * @param tableName - Table receiving the column.
+ * @param column - Desired new column definition.
+ * @returns TypeScript statement lines.
+ */
+function renderAddColumn(tableName, column) {
+    return [
+        `await knex.schema.alterTable(${quote(tableName)}, table => {`,
+        ...indent(renderColumn(column, {
+            creation: true,
+            alterNullable: true,
+            alterType: true,
+            alterComment: true,
+        })),
+        '});',
+    ];
+}
+/**
+ * Renders one safe existing-column alteration.
+ *
+ * @param change - Normalized safe column change.
+ * @returns TypeScript statement lines.
+ */
+function renderAlterColumn(change) {
+    return [
+        `await knex.schema.alterTable(${quote(change.tableName)}, table => {`,
+        ...indent(renderColumn(change.column, {
+            creation: false,
+            alterNullable: change.alterNullable,
+            alterType: change.alterType,
+            alterComment: change.alterComment,
+        })),
+        '});',
+    ];
+}
+/**
+ * Renders one table comment change, using an empty comment to clear it.
+ *
+ * @param tableName - Table receiving the comment.
+ * @param comment - Desired normalized comment.
+ * @returns TypeScript statement lines.
+ */
+function renderAlterTableComment(tableName, comment) {
+    return [
+        `await knex.schema.alterTable(${quote(tableName)}, table => {`,
+        `\ttable.comment(${quote(comment ?? '')});`,
+        '});',
+    ];
+}
+/**
+ * Renders one named index addition.
+ *
+ * @param tableName - Table receiving the index.
+ * @param index - Desired normalized index definition.
+ * @returns TypeScript statement lines.
+ */
+function renderAddIndex(tableName, index) {
+    return [
+        `await knex.schema.alterTable(${quote(tableName)}, table => {`,
+        ...indent(renderIndex(index)),
+        '});',
+    ];
+}
+/**
+ * Renders one named foreign-key addition.
+ *
+ * @param tableName - Local table receiving the constraint.
+ * @param foreignKey - Desired normalized foreign key.
+ * @returns TypeScript statement lines.
+ */
+function renderAddForeignKey(tableName, foreignKey) {
+    const lines = [
+        `await knex.schema.alterTable(${quote(tableName)}, table => {`,
+        '\tlet foreign = table',
+        `\t\t.foreign(${quote(foreignKey.column)}, ${quote(foreignKey.name)})`,
+        `\t\t.references(${quote(foreignKey.referencesColumn)})`,
+        `\t\t.inTable(${quote(foreignKey.referencesTable)});`,
+    ];
+    if (foreignKey.onDelete) {
+        lines.push('', `\tforeign = foreign.onDelete(${quote(foreignKey.onDelete)});`);
+    }
+    if (foreignKey.onUpdate) {
+        lines.push('', `\tforeign.onUpdate(${quote(foreignKey.onUpdate)});`);
+    }
+    lines.push('});');
+    return lines;
+}
+/**
+ * Renders one named foreign-key drop.
+ *
+ * @param tableName - Local table owning the constraint.
+ * @param foreignKeyName - Stable foreign-key name.
+ * @returns TypeScript statement lines.
+ */
+function renderDropForeignKey(tableName, foreignKeyName) {
+    return [
+        `await knex.schema.raw('ALTER TABLE ?? DROP FOREIGN KEY ??', [${quote(tableName)}, ${quote(foreignKeyName)}]);`,
+    ];
+}
+/**
+ * Renders one named index drop.
+ *
+ * @param tableName - Table owning the index.
+ * @param indexName - Stable index name.
+ * @returns TypeScript statement lines.
+ */
+function renderDropIndex(tableName, indexName) {
+    return [
+        `await knex.schema.raw('ALTER TABLE ?? DROP INDEX ??', [${quote(tableName)}, ${quote(indexName)}]);`,
+    ];
+}
+/**
+ * Renders one column drop.
+ *
+ * @param tableName - Table owning the column.
+ * @param columnName - Physical column name.
+ * @returns TypeScript statement lines.
+ */
+function renderDropColumn(tableName, columnName) {
+    return [
+        `await knex.schema.alterTable(${quote(tableName)}, table => {`,
+        `\ttable.dropColumn(${quote(columnName)});`,
+        '});',
+    ];
+}
+/**
+ * Renders one table drop.
+ *
+ * @param tableName - Table to remove.
+ * @returns TypeScript statement lines.
+ */
+function renderDropTable(tableName) {
+    return [
+        `await knex.schema.dropTableIfExists(${quote(tableName)});`,
+    ];
+}
+/**
+ * Renders a column builder inside a small lexical block so every column can
+ * reuse the same readable local variable name.
+ *
+ * @param column - Desired normalized column definition.
+ * @param options - Creation or alteration facets to emit.
+ * @returns TypeScript callback lines.
+ */
+function renderColumn(column, options) {
+    const lines = [
+        '{',
+        `\tconst column = table.specificType(${quote(column.name)}, ${quote(column.type)});`,
+    ];
+    lines.push(column.nullable
+        ? '\tcolumn.nullable();'
+        : '\tcolumn.notNullable();');
+    if (options.creation && column.primary) {
+        lines.push('\tcolumn.primary();');
+    }
+    if (options.creation && column.unique) {
+        lines.push('\tcolumn.unique();');
+    }
+    if (Object.hasOwn(column, 'default')) {
+        lines.push(`\tcolumn.defaultTo(${renderValue(column.default)});`);
+    }
+    if (column.comment || (!options.creation && options.alterComment)) {
+        lines.push(`\tcolumn.comment(${quote(column.comment ?? '')});`);
+    }
+    if (!options.creation) {
+        lines.push(`\tcolumn.alter({ alterNullable: ${options.alterNullable}, alterType: ${options.alterType} });`);
+    }
+    lines.push('}');
+    return lines;
+}
+/**
+ * Renders one normalized index inside a Knex table callback.
+ *
+ * @param index - Desired named index.
+ * @returns TypeScript callback lines.
+ */
+function renderIndex(index) {
+    const columns = renderIndexColumns(index);
+    if (index.type === 'vector') {
+        return [`table.index(${columns}, ${quote(index.name)}, 'vector');`];
+    }
+    if (index.unique) {
+        return [`table.unique(${columns}, ${quote(index.name)});`];
+    }
+    return [`table.index(${columns}, ${quote(index.name)});`];
+}
+/**
+ * Renders scalar or raw ordered index columns.
+ *
+ * @param index - Desired normalized index.
+ * @returns TypeScript expression accepted by Knex index methods.
+ */
+function renderIndexColumns(index) {
+    const columns = index.columns.map(column => {
+        return column.order
+            ? `knex.raw('?? ${column.order}', [${quote(column.name)}])`
+            : quote(column.name);
+    });
+    return columns.length === 1 && !index.columns[0]?.order
+        ? columns[0] ?? '[]'
+        : `[${columns.join(', ')}]`;
+}
+/**
+ * Adds one tab of indentation to rendered callback lines.
+ *
+ * @param lines - Lines to indent.
+ * @returns New indented line collection.
+ */
+function indent(lines) {
+    return lines.map(line => line ? `\t${line}` : '');
+}
+/**
+ * Renders a JSON-safe schema value as a TypeScript literal.
+ *
+ * @param value - Frozen static database default.
+ * @returns TypeScript literal expression.
+ */
+function renderValue(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Renders a string as a deterministic double-quoted literal.
+ *
+ * @param value - String to quote.
+ * @returns JSON-compatible TypeScript string literal.
+ */
+function quote(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Builds a type guard for one discriminant kind.
+ *
+ * @param kind - Safe change kind to retain.
+ * @returns Array-filter predicate narrowing to that change kind.
+ */
+function isChangeKind(kind) {
+    return (change) => {
+        return change.kind === kind;
+    };
+}

package/dist/db/migrations/ModelSchemaCollector.d.ts

@@ -0,0 +1,29 @@
+import type { ActiveRecordClass } from '../ActiveRecord.js';
+import type { DatabaseDialect } from '../dialects/index.js';
+import type { SchemaSnapshot, SchemaValue } from './contracts/index.js';
+/**
+ * Collects a deterministic serializable schema snapshot from ActiveRecord
+ * model metadata.
+ *
+ * @param models - Complete model registry owned by the application.
+ * @param dialect - Database dialect used by fields to resolve physical types.
+ * @returns Normalized desired database state sorted by physical names.
+ */
+export declare function collectModelSchema(models: readonly ActiveRecordClass[], dialect: DatabaseDialect): SchemaSnapshot;
+/**
+ * Canonicalizes dialect type strings so snapshots do not change because of
+ * harmless whitespace, case, or MariaDB integer display widths.
+ *
+ * @param input - Dialect-provided or database-inspected SQL type.
+ * @returns Stable lower-case SQL type.
+ */
+export declare function normalizeSchemaColumnType(input: string): string;
+/**
+ * Converts a static field default to the JSON-safe representation permitted in
+ * committed snapshots and generated migration source.
+ *
+ * @param input - Static database default produced by a field.
+ * @param path - Human-readable location used in validation errors.
+ * @returns Deterministically ordered JSON-safe value.
+ */
+export declare function normalizeSchemaValue(input: unknown, path: string): SchemaValue;

package/dist/db/migrations/ModelSchemaCollector.js

@@ -0,0 +1,183 @@
+import { normalizeDatabaseComment } from '@db3.ai/pure';
+import { Database } from '../Database.js';
+import { defaultSchemaForeignKeyName, defaultSchemaIndexName } from './SchemaNames.js';
+/**
+ * Collects a deterministic serializable schema snapshot from ActiveRecord
+ * model metadata.
+ *
+ * @param models - Complete model registry owned by the application.
+ * @param dialect - Database dialect used by fields to resolve physical types.
+ * @returns Normalized desired database state sorted by physical names.
+ */
+export function collectModelSchema(models, dialect) {
+    const tables = models.map(Model => collectModelTable(Model, dialect));
+    const tableNames = new Set();
+    for (const table of tables) {
+        if (tableNames.has(table.name)) {
+            throw new Error(`Duplicate model table "${table.name}" in migration registry.`);
+        }
+        tableNames.add(table.name);
+    }
+    return {
+        formatVersion: 1,
+        dialect: dialect.name,
+        tables: tables.sort(compareByName),
+    };
+}
+/**
+ * Collects one normalized table from an ActiveRecord class.
+ *
+ * @param Model - ActiveRecord model defining the table.
+ * @param dialect - Database dialect used by fields to resolve physical types.
+ * @returns Deterministic normalized table schema.
+ */
+function collectModelTable(Model, dialect) {
+    const schema = Database.getSchema(Model, dialect);
+    const columns = schema.columns.map(column => {
+        const normalized = {
+            name: column.name,
+            type: normalizeSchemaColumnType(column.type),
+            nullable: !(column.primary || column.nullable === false),
+            primary: Boolean(column.primary),
+            unique: Boolean(column.unique),
+            comment: normalizeDatabaseComment(column.comment),
+        };
+        if (column.default !== undefined) {
+            normalized.default = normalizeSchemaValue(column.default, `${Model.table}.${column.name} default`);
+        }
+        return normalized;
+    });
+    const indexes = schema.indexes.map(index => {
+        const indexColumns = index.columns.map(normalizeIndexColumn);
+        const unique = Boolean(index.unique);
+        const type = index.type ?? 'normal';
+        return {
+            name: index.name ?? defaultSchemaIndexName(Model.table, indexColumns, unique, type),
+            columns: indexColumns,
+            unique,
+            type,
+        };
+    });
+    const foreignKeys = schema.foreignKeys.map(foreignKey => {
+        const normalized = {
+            name: defaultSchemaForeignKeyName(Model.table, foreignKey.column),
+            column: foreignKey.column,
+            referencesTable: foreignKey.referencesTable,
+            referencesColumn: foreignKey.referencesColumn,
+        };
+        if (foreignKey.onDelete)
+            normalized.onDelete = foreignKey.onDelete;
+        if (foreignKey.onUpdate)
+            normalized.onUpdate = foreignKey.onUpdate;
+        return normalized;
+    });
+    assertUniqueNames(columns, `${Model.table} column`);
+    assertUniqueNames(indexes, `${Model.table} index`);
+    assertUniqueNames(foreignKeys, `${Model.table} foreign key`);
+    return {
+        name: Model.table,
+        comment: normalizeDatabaseComment(Model.comment),
+        columns: columns.sort(compareByName),
+        indexes: indexes.sort(compareByName),
+        foreignKeys: foreignKeys.sort(compareByName),
+    };
+}
+/**
+ * Converts one framework index column to its normalized serializable form.
+ *
+ * @param column - Field-owned index column metadata.
+ * @returns Normalized ordered index column.
+ */
+function normalizeIndexColumn(column) {
+    if (typeof column === 'string') {
+        return { name: column };
+    }
+    const normalized = { name: column.name };
+    if (column.order)
+        normalized.order = column.order;
+    return normalized;
+}
+/**
+ * Canonicalizes dialect type strings so snapshots do not change because of
+ * harmless whitespace, case, or MariaDB integer display widths.
+ *
+ * @param input - Dialect-provided or database-inspected SQL type.
+ * @returns Stable lower-case SQL type.
+ */
+export function normalizeSchemaColumnType(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/\bboolean\b/g, 'tinyint(1)')
+        .replace(/\b(bigint|int|mediumint|smallint)\(\d+\)/g, '$1')
+        .replace(/\s+/g, ' ');
+}
+/**
+ * Converts a static field default to the JSON-safe representation permitted in
+ * committed snapshots and generated migration source.
+ *
+ * @param input - Static database default produced by a field.
+ * @param path - Human-readable location used in validation errors.
+ * @returns Deterministically ordered JSON-safe value.
+ */
+export function normalizeSchemaValue(input, path) {
+    if (input === null || typeof input === 'string' || typeof input === 'boolean') {
+        return input;
+    }
+    if (typeof input === 'number') {
+        if (!Number.isFinite(input)) {
+            throw new Error(`${path} must be a finite serializable number.`);
+        }
+        return input;
+    }
+    if (Array.isArray(input)) {
+        return input.map((value, index) => {
+            return normalizeSchemaValue(value, `${path}[${index}]`);
+        });
+    }
+    if (isPlainObject(input)) {
+        return Object.fromEntries(Object.entries(input)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, value]) => {
+            return [key, normalizeSchemaValue(value, `${path}.${key}`)];
+        }));
+    }
+    throw new Error(`${path} must be a static JSON-serializable value.`);
+}
+/**
+ * Tests whether an input is a plain record that can be frozen as JSON.
+ *
+ * @param input - Value to inspect.
+ * @returns True only for ordinary or null-prototype records.
+ */
+function isPlainObject(input) {
+    if (!input || typeof input !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(input);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Rejects duplicate names before sorting hides their model declaration order.
+ *
+ * @param values - Named schema objects to validate.
+ * @param description - Object kind included in validation errors.
+ */
+function assertUniqueNames(values, description) {
+    const names = new Set();
+    for (const value of values) {
+        if (names.has(value.name)) {
+            throw new Error(`Duplicate ${description} "${value.name}".`);
+        }
+        names.add(value.name);
+    }
+}
+/**
+ * Sort comparator for normalized named schema objects.
+ *
+ * @param a - First named schema object.
+ * @param b - Second named schema object.
+ * @returns Locale-independent lexical ordering result.
+ */
+function compareByName(a, b) {
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}

package/dist/db/migrations/SchemaDiffer.d.ts

@@ -0,0 +1,13 @@
+import type { SchemaMigrationPlan, SchemaSnapshot } from './contracts/index.js';
+/**
+ * Computes a pure deterministic migration plan between two normalized schema
+ * snapshots.
+ *
+ * The automatic policy is intentionally conservative. Any blocked change
+ * prevents the manager from emitting a partially correct migration.
+ *
+ * @param from - Previously committed or currently installed model-owned state.
+ * @param to - New desired model-owned state.
+ * @returns Safe renderable changes and blocked reviewed changes.
+ */
+export declare function diffSchemaSnapshots(from: SchemaSnapshot, to: SchemaSnapshot): SchemaMigrationPlan;