@stonyx/orm 0.2.5-alpha.0 → 0.3.1

package/dist/mysql/migration-generator.js

@@ -0,0 +1,254 @@
+import { introspectModels, introspectViews, buildTableDDL, buildViewDDL, schemasToSnapshot, viewSchemasToSnapshot, getTopologicalOrder } from './schema-introspector.js';
+import { readFile, createFile, createDirectory, fileExists } from '@stonyx/utils/file';
+import path from 'path';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+export async function generateMigration(description = 'migration') {
+    const mysqlConfig = config.orm.mysql;
+    if (!mysqlConfig)
+        throw new Error('MySQL configuration (config.orm.mysql) is required for migration generation');
+    const { migrationsDir } = mysqlConfig;
+    if (!migrationsDir)
+        throw new Error('MySQL migrationsDir is required in config');
+    const rootPath = config.rootPath;
+    const migrationsPath = path.resolve(rootPath, migrationsDir);
+    await createDirectory(migrationsPath);
+    const schemas = introspectModels();
+    const currentSnapshot = schemasToSnapshot(schemas);
+    const previousSnapshot = await loadLatestSnapshot(migrationsPath);
+    const diff = diffSnapshots(previousSnapshot, currentSnapshot);
+    // Don't return early — check view changes too before deciding
+    if (!diff.hasChanges) {
+        // Check if there are view changes before returning null
+        const viewSchemasPrelim = introspectViews();
+        const currentViewSnapshotPrelim = viewSchemasToSnapshot(viewSchemasPrelim);
+        const previousViewSnapshotPrelim = extractViewsFromSnapshot(previousSnapshot);
+        const viewDiffPrelim = diffViewSnapshots(previousViewSnapshotPrelim, currentViewSnapshotPrelim);
+        if (!viewDiffPrelim.hasChanges) {
+            log.db?.('No schema changes detected.');
+            return null;
+        }
+    }
+    const upStatements = [];
+    const downStatements = [];
+    // New tables — in topological order (parents before children)
+    const allOrder = getTopologicalOrder(schemas);
+    const addedOrdered = allOrder.filter(name => diff.addedModels.includes(name));
+    for (const name of addedOrdered) {
+        upStatements.push(buildTableDDL(name, schemas[name], schemas) + ';');
+        downStatements.unshift(`DROP TABLE IF EXISTS \`${schemas[name].table}\`;`);
+    }
+    // Removed tables (warn only, commented out)
+    for (const name of diff.removedModels) {
+        upStatements.push(`-- WARNING: Model '${name}' was removed. Uncomment to drop table:`);
+        upStatements.push(`-- DROP TABLE IF EXISTS \`${previousSnapshot[name].table}\`;`);
+        downStatements.push(`-- Recreate table for removed model '${name}' manually if needed`);
+    }
+    // Added columns
+    for (const { model, column, type } of diff.addedColumns) {
+        const table = currentSnapshot[model].table;
+        upStatements.push(`ALTER TABLE \`${table}\` ADD COLUMN \`${column}\` ${type};`);
+        downStatements.push(`ALTER TABLE \`${table}\` DROP COLUMN \`${column}\`;`);
+    }
+    // Removed columns
+    for (const { model, column, type } of diff.removedColumns) {
+        const table = previousSnapshot[model]?.table;
+        if (!table)
+            throw new Error(`Missing table name in snapshot for model "${model}"`);
+        upStatements.push(`ALTER TABLE \`${table}\` DROP COLUMN \`${column}\`;`);
+        downStatements.push(`ALTER TABLE \`${table}\` ADD COLUMN \`${column}\` ${type};`);
+    }
+    // Changed column types
+    for (const { model, column, from, to } of diff.changedColumns) {
+        const table = currentSnapshot[model].table;
+        upStatements.push(`ALTER TABLE \`${table}\` MODIFY COLUMN \`${column}\` ${to};`);
+        downStatements.push(`ALTER TABLE \`${table}\` MODIFY COLUMN \`${column}\` ${from};`);
+    }
+    // Added foreign keys
+    for (const { model, column, references } of diff.addedForeignKeys) {
+        const table = currentSnapshot[model].table;
+        // Resolve FK column type from the referenced table's PK type
+        const refModel = Object.entries(currentSnapshot).find(([, s]) => s.table === references.references);
+        const fkType = refModel && refModel[1].idType === 'string' ? 'VARCHAR(255)' : 'INT';
+        upStatements.push(`ALTER TABLE \`${table}\` ADD COLUMN \`${column}\` ${fkType};`);
+        upStatements.push(`ALTER TABLE \`${table}\` ADD FOREIGN KEY (\`${column}\`) REFERENCES \`${references.references}\`(\`${references.column}\`) ON DELETE SET NULL;`);
+        downStatements.push(`ALTER TABLE \`${table}\` DROP FOREIGN KEY \`${column}\`;`);
+        downStatements.push(`ALTER TABLE \`${table}\` DROP COLUMN \`${column}\`;`);
+    }
+    // Removed foreign keys
+    for (const { model, column, references } of diff.removedForeignKeys) {
+        const table = previousSnapshot[model]?.table;
+        if (!table)
+            throw new Error(`Missing table name in snapshot for model "${model}"`);
+        // Resolve FK column type from the referenced table's PK type in previous snapshot
+        const refModel = Object.entries(previousSnapshot).find(([, s]) => s.table === references.references);
+        const fkType = refModel && refModel[1].idType === 'string' ? 'VARCHAR(255)' : 'INT';
+        upStatements.push(`ALTER TABLE \`${table}\` DROP FOREIGN KEY \`${column}\`;`);
+        upStatements.push(`ALTER TABLE \`${table}\` DROP COLUMN \`${column}\`;`);
+        downStatements.push(`ALTER TABLE \`${table}\` ADD COLUMN \`${column}\` ${fkType};`);
+        downStatements.push(`ALTER TABLE \`${table}\` ADD FOREIGN KEY (\`${column}\`) REFERENCES \`${references.references}\`(\`${references.column}\`) ON DELETE SET NULL;`);
+    }
+    // View migrations — views are created AFTER tables (dependency order)
+    const viewSchemas = introspectViews();
+    const currentViewSnapshot = viewSchemasToSnapshot(viewSchemas);
+    const previousViewSnapshot = extractViewsFromSnapshot(previousSnapshot);
+    const viewDiff = diffViewSnapshots(previousViewSnapshot, currentViewSnapshot);
+    if (viewDiff.hasChanges) {
+        upStatements.push('');
+        upStatements.push('-- Views');
+        downStatements.push('');
+        downStatements.push('-- Views');
+        // Added views
+        for (const name of viewDiff.addedViews) {
+            try {
+                const ddl = buildViewDDL(name, viewSchemas[name], schemas);
+                upStatements.push(ddl + ';');
+                downStatements.unshift(`DROP VIEW IF EXISTS \`${viewSchemas[name].viewName}\`;`);
+            }
+            catch (error) {
+                upStatements.push(`-- WARNING: Could not generate DDL for view '${name}': ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // Removed views
+        for (const name of viewDiff.removedViews) {
+            upStatements.push(`-- WARNING: View '${name}' was removed. Uncomment to drop view:`);
+            upStatements.push(`-- DROP VIEW IF EXISTS \`${previousViewSnapshot[name].viewName}\`;`);
+            downStatements.push(`-- Recreate view for removed view '${name}' manually if needed`);
+        }
+        // Changed views (source or aggregates changed)
+        for (const name of viewDiff.changedViews) {
+            try {
+                const ddl = buildViewDDL(name, viewSchemas[name], schemas);
+                upStatements.push(ddl + ';');
+            }
+            catch (error) {
+                upStatements.push(`-- WARNING: Could not generate DDL for changed view '${name}': ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    const combinedHasChanges = diff.hasChanges || viewDiff.hasChanges;
+    if (!combinedHasChanges) {
+        log.db?.('No schema changes detected.');
+        return null;
+    }
+    // Merge view snapshot into the main snapshot
+    const combinedSnapshot = { ...currentSnapshot };
+    for (const [name, viewSnap] of Object.entries(currentViewSnapshot)) {
+        combinedSnapshot[name] = viewSnap;
+    }
+    const sanitizedDescription = description.replace(/\s+/g, '_').replace(/[^a-zA-Z0-9_]/g, '');
+    const timestamp = Math.floor(Date.now() / 1000);
+    const filename = `${timestamp}_${sanitizedDescription}.sql`;
+    const content = `-- UP\n${upStatements.join('\n')}\n\n-- DOWN\n${downStatements.join('\n')}\n`;
+    await createFile(path.join(migrationsPath, filename), content);
+    await createFile(path.join(migrationsPath, '.snapshot.json'), JSON.stringify(combinedSnapshot, null, 2));
+    log.db?.(`Migration generated: ${filename}`);
+    return { filename, content, snapshot: combinedSnapshot };
+}
+export async function loadLatestSnapshot(migrationsPath) {
+    const snapshotPath = path.join(migrationsPath, '.snapshot.json');
+    const exists = await fileExists(snapshotPath);
+    if (!exists)
+        return {};
+    return readFile(snapshotPath, { json: true });
+}
+export function diffSnapshots(previous, current) {
+    const addedModels = [];
+    const removedModels = [];
+    const addedColumns = [];
+    const removedColumns = [];
+    const changedColumns = [];
+    const addedForeignKeys = [];
+    const removedForeignKeys = [];
+    // Find added models
+    for (const name of Object.keys(current)) {
+        if (!previous[name])
+            addedModels.push(name);
+    }
+    // Find removed models
+    for (const name of Object.keys(previous)) {
+        if (!current[name])
+            removedModels.push(name);
+    }
+    // Find column changes in existing models
+    for (const name of Object.keys(current)) {
+        if (!previous[name])
+            continue;
+        const { columns: prevCols = {} } = previous[name];
+        const { columns: currCols = {} } = current[name];
+        // Added columns
+        for (const [col, type] of Object.entries(currCols)) {
+            if (!prevCols[col]) {
+                addedColumns.push({ model: name, column: col, type });
+            }
+            else if (prevCols[col] !== type) {
+                changedColumns.push({ model: name, column: col, from: prevCols[col], to: type });
+            }
+        }
+        // Removed columns
+        for (const [col, type] of Object.entries(prevCols)) {
+            if (!currCols[col]) {
+                removedColumns.push({ model: name, column: col, type });
+            }
+        }
+        // Foreign key changes
+        const prevFKs = previous[name].foreignKeys || {};
+        const currFKs = current[name].foreignKeys || {};
+        for (const [col, refs] of Object.entries(currFKs)) {
+            if (!prevFKs[col]) {
+                addedForeignKeys.push({ model: name, column: col, references: refs });
+            }
+        }
+        for (const [col, refs] of Object.entries(prevFKs)) {
+            if (!currFKs[col]) {
+                removedForeignKeys.push({ model: name, column: col, references: refs });
+            }
+        }
+    }
+    const hasChanges = addedModels.length > 0 || removedModels.length > 0 ||
+        addedColumns.length > 0 || removedColumns.length > 0 ||
+        changedColumns.length > 0 || addedForeignKeys.length > 0 || removedForeignKeys.length > 0;
+    return {
+        hasChanges,
+        addedModels,
+        removedModels,
+        addedColumns,
+        removedColumns,
+        changedColumns,
+        addedForeignKeys,
+        removedForeignKeys,
+    };
+}
+export function detectSchemaDrift(schemas, snapshot) {
+    const current = schemasToSnapshot(schemas);
+    return diffSnapshots(snapshot, current);
+}
+export function extractViewsFromSnapshot(snapshot) {
+    const views = {};
+    for (const [name, entry] of Object.entries(snapshot)) {
+        if (entry.isView)
+            views[name] = entry;
+    }
+    return views;
+}
+export function diffViewSnapshots(previous, current) {
+    const addedViews = [];
+    const removedViews = [];
+    const changedViews = [];
+    for (const name of Object.keys(current)) {
+        if (!previous[name]) {
+            addedViews.push(name);
+        }
+        else if (current[name].viewQuery !== previous[name].viewQuery ||
+            current[name].source !== previous[name].source) {
+            changedViews.push(name);
+        }
+    }
+    for (const name of Object.keys(previous)) {
+        if (!current[name]) {
+            removedViews.push(name);
+        }
+    }
+    const hasChanges = addedViews.length > 0 || removedViews.length > 0 || changedViews.length > 0;
+    return { hasChanges, addedViews, removedViews, changedViews };
+}

package/dist/mysql/migration-runner.d.ts

@@ -0,0 +1,12 @@
+import type { Pool } from 'mysql2/promise';
+interface ParsedMigration {
+    up: string;
+    down: string;
+}
+export declare function ensureMigrationsTable(pool: Pool, tableName?: string): Promise<void>;
+export declare function getAppliedMigrations(pool: Pool, tableName?: string): Promise<string[]>;
+export declare function getMigrationFiles(migrationsDir: string): Promise<string[]>;
+export declare function parseMigrationFile(content: string): ParsedMigration;
+export declare function applyMigration(pool: Pool, filename: string, upSql: string, tableName?: string): Promise<void>;
+export declare function rollbackMigration(pool: Pool, filename: string, downSql: string, tableName?: string): Promise<void>;
+export {};

package/dist/mysql/migration-runner.js

@@ -0,0 +1,88 @@
+import { fileExists } from '@stonyx/utils/file';
+import fs from 'fs/promises';
+import { validateIdentifier } from './query-builder.js';
+export async function ensureMigrationsTable(pool, tableName = '__migrations') {
+    validateIdentifier(tableName, 'migration table name');
+    await pool.execute(`
+    CREATE TABLE IF NOT EXISTS \`${tableName}\` (
+      id INT AUTO_INCREMENT PRIMARY KEY,
+      filename VARCHAR(255) NOT NULL UNIQUE,
+      applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    )
+  `);
+}
+export async function getAppliedMigrations(pool, tableName = '__migrations') {
+    validateIdentifier(tableName, 'migration table name');
+    const [rows] = await pool.execute(`SELECT filename FROM \`${tableName}\` ORDER BY id ASC`);
+    return rows.map(row => row.filename);
+}
+export async function getMigrationFiles(migrationsDir) {
+    const exists = await fileExists(migrationsDir);
+    if (!exists)
+        return [];
+    const entries = await fs.readdir(migrationsDir);
+    return entries
+        .filter(f => f.endsWith('.sql'))
+        .sort();
+}
+export function parseMigrationFile(content) {
+    const upMarker = '-- UP';
+    const downMarker = '-- DOWN';
+    const upIndex = content.indexOf(upMarker);
+    const downIndex = content.indexOf(downMarker);
+    if (upIndex === -1) {
+        return { up: content.trim(), down: '' };
+    }
+    const upStart = upIndex + upMarker.length;
+    const upEnd = downIndex !== -1 ? downIndex : content.length;
+    const up = content.slice(upStart, upEnd).trim();
+    const down = downIndex !== -1 ? content.slice(downIndex + downMarker.length).trim() : '';
+    return { up, down };
+}
+export async function applyMigration(pool, filename, upSql, tableName = '__migrations') {
+    validateIdentifier(tableName, 'migration table name');
+    const connection = await pool.getConnection();
+    try {
+        await connection.beginTransaction();
+        // Execute each statement separately (split on semicolons)
+        const statements = splitStatements(upSql);
+        for (const stmt of statements) {
+            await connection.execute(stmt);
+        }
+        await connection.execute(`INSERT INTO \`${tableName}\` (filename) VALUES (?)`, [filename]);
+        await connection.commit();
+    }
+    catch (error) {
+        await connection.rollback();
+        throw error;
+    }
+    finally {
+        connection.release();
+    }
+}
+export async function rollbackMigration(pool, filename, downSql, tableName = '__migrations') {
+    validateIdentifier(tableName, 'migration table name');
+    const connection = await pool.getConnection();
+    try {
+        await connection.beginTransaction();
+        const statements = splitStatements(downSql);
+        for (const stmt of statements) {
+            await connection.execute(stmt);
+        }
+        await connection.execute(`DELETE FROM \`${tableName}\` WHERE filename = ?`, [filename]);
+        await connection.commit();
+    }
+    catch (error) {
+        await connection.rollback();
+        throw error;
+    }
+    finally {
+        connection.release();
+    }
+}
+function splitStatements(sql) {
+    return sql
+        .split(';')
+        .map(s => s.trim())
+        .filter(s => s.length > 0 && !s.startsWith('--'));
+}

package/dist/mysql/mysql-db.d.ts

@@ -0,0 +1,100 @@
+import { getPool, closePool } from './connection.js';
+import type { MysqlConfig } from './connection.js';
+import { ensureMigrationsTable, getAppliedMigrations, getMigrationFiles, applyMigration, parseMigrationFile } from './migration-runner.js';
+import { introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot } from './schema-introspector.js';
+import { loadLatestSnapshot, detectSchemaDrift } from './migration-generator.js';
+import { buildInsert, buildUpdate, buildDelete, buildSelect } from './query-builder.js';
+import { createRecord } from '../manage-record.js';
+import { confirm } from '@stonyx/utils/prompt';
+import { readFile } from '@stonyx/utils/file';
+import { getPluralName } from '../plural-registry.js';
+import config from 'stonyx/config';
+import path from 'path';
+import type { Pool } from 'mysql2/promise';
+import type { OrmRecord } from '../types/orm-types.js';
+interface PersistContext {
+    record?: OrmRecord;
+    recordId?: unknown;
+    oldState?: Record<string, unknown>;
+}
+interface PersistResponse {
+    data?: {
+        id?: unknown;
+    };
+}
+interface OrmStore {
+    get(key: string): Map<number | string, unknown> | undefined;
+    get(key: string, id: number | string): unknown;
+    _memoryResolver?: (modelName: string) => boolean;
+    data?: Map<string, Map<number | string, unknown>>;
+}
+interface MysqlDBDeps {
+    getPool: typeof getPool;
+    closePool: typeof closePool;
+    ensureMigrationsTable: typeof ensureMigrationsTable;
+    getAppliedMigrations: typeof getAppliedMigrations;
+    getMigrationFiles: typeof getMigrationFiles;
+    applyMigration: typeof applyMigration;
+    parseMigrationFile: typeof parseMigrationFile;
+    introspectModels: typeof introspectModels;
+    introspectViews: typeof introspectViews;
+    getTopologicalOrder: typeof getTopologicalOrder;
+    schemasToSnapshot: typeof schemasToSnapshot;
+    loadLatestSnapshot: typeof loadLatestSnapshot;
+    detectSchemaDrift: typeof detectSchemaDrift;
+    buildInsert: typeof buildInsert;
+    buildUpdate: typeof buildUpdate;
+    buildDelete: typeof buildDelete;
+    buildSelect: typeof buildSelect;
+    createRecord: typeof createRecord;
+    store: OrmStore;
+    confirm: typeof confirm;
+    readFile: typeof readFile;
+    getPluralName: typeof getPluralName;
+    config: typeof config;
+    log: Record<string, ((...args: unknown[]) => void) | undefined>;
+    path: typeof path;
+}
+export default class MysqlDB {
+    static instance: MysqlDB | undefined;
+    deps: MysqlDBDeps;
+    pool: Pool | null;
+    mysqlConfig: MysqlConfig;
+    constructor(deps?: Partial<MysqlDBDeps>);
+    private requirePool;
+    init(): Promise<void>;
+    startup(): Promise<void>;
+    shutdown(): Promise<void>;
+    save(): Promise<void>;
+    /**
+     * Loads only models with memory: true into the in-memory store on startup.
+     * Models with memory: false are skipped — accessed on-demand via find()/findAll().
+     */
+    loadMemoryRecords(): Promise<void>;
+    /**
+     * @deprecated Use loadMemoryRecords() instead. Kept for backward compatibility.
+     */
+    loadAllRecords(): Promise<void>;
+    /**
+     * Find a single record by ID from MySQL.
+     * Does NOT cache the result in the store for memory: false models.
+     */
+    findRecord(modelName: string, id: string | number): Promise<OrmRecord | undefined>;
+    /**
+     * Find all records of a model from MySQL, with optional conditions.
+     */
+    findAll(modelName: string, conditions?: Record<string, unknown>): Promise<OrmRecord[]>;
+    /**
+     * Remove a record from the in-memory store if its model has memory: false.
+     * The record object itself survives — the caller retains the reference.
+     * This prevents on-demand queries from leaking records into the store.
+     */
+    private _evictIfNotMemory;
+    private _rowToRawData;
+    persist(operation: string, modelName: string, context: PersistContext, response: PersistResponse): Promise<void>;
+    private _persistCreate;
+    private _persistUpdate;
+    private _persistDelete;
+    private _recordToRow;
+}
+export {};