@stonyx/orm 0.2.1-alpha.2 → 0.2.1-alpha.21

package/src/manage-record.js

@@ -14,6 +14,11 @@ export function createRecord(modelName, rawData={}, userOptions={}) {
 
   if (!initialized && !options.isDbRecord) throw new Error('ORM is not ready');
 
+  // Guard: read-only views cannot have records created directly
+  if (orm?.isView?.(modelName) && !options.isDbRecord) {
+    throw new Error(`Cannot create records for read-only view '${modelName}'`);
+  }
+
   const modelStore = store.get(modelName);
   const globalRelationships = relationships.get('global');
   const pendingRelationships = relationships.get('pending');
@@ -83,6 +88,12 @@ export function createRecord(modelName, rawData={}, userOptions={}) {
 export function updateRecord(record, rawData, userOptions={}) {
   if (!rawData) throw new Error('rawData must be passed in to updateRecord call');
 
+  // Guard: read-only views cannot be updated
+  const modelName = record?.__model?.__name;
+  if (modelName && Orm.instance?.isView?.(modelName)) {
+    throw new Error(`Cannot update records for read-only view '${modelName}'`);
+  }
+
   const options = { ...defaultOptions, ...userOptions, update:true };
 
   record.serialize(rawData, options);
@@ -90,14 +101,29 @@ export function updateRecord(record, rawData, userOptions={}) {
 
 /**
  * gets the next available id based on last record entry.
- * 
- * Note/TODO: Records going into a db should get their id from the db instead
- * Atm, i think the best way to do that would be as an id override that happens after the
- * record is created
+ *
+ * In MySQL mode with numeric IDs, assigns a temporary pending ID.
+ * MySQL's AUTO_INCREMENT provides the real ID after INSERT.
  */
 function assignRecordId(modelName, rawData) {
   if (rawData.id) return;
 
+  // In MySQL mode with numeric IDs, defer to MySQL auto-increment
+  if (Orm.instance?.mysqlDb && !isStringIdModel(modelName)) {
+    rawData.id = `__pending_${Date.now()}_${Math.random()}`;
+    rawData.__pendingMysqlId = true;
+    return;
+  }
+
   const modelStore = Array.from(store.get(modelName).values());
   rawData.id = modelStore.length ? modelStore.at(-1).id + 1 : 1;
 }
+
+function isStringIdModel(modelName) {
+  const { modelClass } = Orm.instance.getRecordClasses(modelName);
+  if (!modelClass) return false;
+
+  const model = new modelClass(modelName);
+
+  return model.id?.type === 'string';
+}

package/src/migrate.js

@@ -0,0 +1,72 @@
+import config from 'stonyx/config';
+import Orm from '@stonyx/orm';
+import { createFile, createDirectory, readFile, updateFile, deleteDirectory } from '@stonyx/utils/file';
+import { dbKey } from './db.js';
+import path from 'path';
+
+function getCollectionKeys() {
+  const SchemaClass = Orm.instance.models[`${dbKey}Model`];
+  const instance = new SchemaClass();
+  const keys = [];
+
+  for (const key of Object.keys(instance)) {
+    if (key === '__name' || key === 'id') continue;
+    if (typeof instance[key] === 'function') keys.push(key);
+  }
+
+  return keys;
+}
+
+function getDirPath() {
+  const { rootPath } = config;
+  const { file, directory } = config.orm.db;
+  const dbDir = path.dirname(path.resolve(`${rootPath}/${file}`));
+
+  return path.join(dbDir, directory);
+}
+
+export async function fileToDirectory() {
+  const { rootPath } = config;
+  const { file } = config.orm.db;
+  const dbFilePath = path.resolve(`${rootPath}/${file}`);
+  const collectionKeys = getCollectionKeys();
+  const dirPath = getDirPath();
+
+  // Read full data from db.json
+  const data = await readFile(dbFilePath, { json: true });
+
+  // Create directory and write each collection
+  await createDirectory(dirPath);
+
+  await Promise.all(collectionKeys.map(key =>
+    createFile(path.join(dirPath, `${key}.json`), data[key] || [], { json: true })
+  ));
+
+  // Overwrite db.json with empty-array skeleton
+  const skeleton = {};
+  for (const key of collectionKeys) skeleton[key] = [];
+
+  await updateFile(dbFilePath, skeleton, { json: true });
+}
+
+export async function directoryToFile() {
+  const { rootPath } = config;
+  const { file } = config.orm.db;
+  const dbFilePath = path.resolve(`${rootPath}/${file}`);
+  const collectionKeys = getCollectionKeys();
+  const dirPath = getDirPath();
+
+  // Read each collection from the directory
+  const assembled = {};
+
+  await Promise.all(collectionKeys.map(async key => {
+    const filePath = path.join(dirPath, `${key}.json`);
+    assembled[key] = await readFile(filePath, { json: true });
+  }));
+
+  // Overwrite db.json with full assembled data
+  await updateFile(dbFilePath, assembled, { json: true });
+
+  // Remove the directory
+  await deleteDirectory(dirPath);
+}

package/src/model-property.js

@@ -22,8 +22,8 @@ export default class ModelProperty {
       return this._value = newValue;
     }
 
-    if (newValue === undefined || newValue === null) return;
+    if (newValue === undefined) return;
 
-    this._value = Orm.instance.transforms[this.type](newValue);
+    this._value = newValue === null ? null : Orm.instance.transforms[this.type](newValue);
   }
 }

package/src/model.js

@@ -1,6 +1,17 @@
 import { attr } from '@stonyx/orm';
 
 export default class Model {
+  /**
+   * Controls whether records of this model are loaded into memory on startup.
+   *
+   * - true  → loaded on boot, kept in store (default for backward compatibility)
+   * - false → never cached; find() always queries MySQL
+   *
+   * Override in subclass: static memory = false;
+   */
+  static memory = true;
+  static pluralName = undefined;
+
   id = attr('number');
 
   constructor(name) {

package/src/mysql/connection.js

@@ -0,0 +1,28 @@
+let pool = null;
+
+export async function getPool(mysqlConfig) {
+  if (pool) return pool;
+
+  const mysql = await import('mysql2/promise');
+
+  pool = mysql.createPool({
+    host: mysqlConfig.host,
+    port: mysqlConfig.port,
+    user: mysqlConfig.user,
+    password: mysqlConfig.password,
+    database: mysqlConfig.database,
+    connectionLimit: mysqlConfig.connectionLimit,
+    waitForConnections: true,
+    enableKeepAlive: true,
+    keepAliveInitialDelay: 10000,
+  });
+
+  return pool;
+}
+
+export async function closePool() {
+  if (!pool) return;
+
+  await pool.end();
+  pool = null;
+}

package/src/mysql/migration-generator.js

@@ -0,0 +1,286 @@
+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 { migrationsDir } = config.orm.mysql;
+  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;
+    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;
+    // 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.message}`);
+      }
+    }
+
+    // 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.message}`);
+      }
+    }
+  }
+
+  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/src/mysql/migration-runner.js

@@ -0,0 +1,110 @@
+import { readFile, fileExists } from '@stonyx/utils/file';
+import path from 'path';
+import fs from 'fs/promises';
+
+export async function ensureMigrationsTable(pool, tableName = '__migrations') {
+  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') {
+  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') {
+  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') {
+  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('--'));
+}