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

package/src/commands.js

@@ -0,0 +1,170 @@
+import { fileToDirectory, directoryToFile } from './migrate.js';
+
+export default {
+  'db:migrate-to-directory': {
+    description: 'Migrate DB from single file to directory mode',
+    bootstrap: true,
+    run: async () => {
+      await fileToDirectory();
+      console.log('DB migration to directory mode complete.');
+    }
+  },
+  'db:migrate-to-file': {
+    description: 'Migrate DB from directory mode to single file',
+    bootstrap: true,
+    run: async () => {
+      await directoryToFile();
+      console.log('DB migration to file mode complete.');
+    }
+  },
+  'db:generate-migration': {
+    description: 'Generate a MySQL migration from current model schemas',
+    bootstrap: true,
+    run: async (args) => {
+      const description = args.join(' ') || 'migration';
+      const { generateMigration } = await import('./mysql/migration-generator.js');
+      const result = await generateMigration(description);
+
+      if (result) {
+        console.log(`Migration created: ${result.filename}`);
+      } else {
+        console.log('No schema changes detected. No migration generated.');
+      }
+    }
+  },
+  'db:migrate': {
+    description: 'Apply pending MySQL migrations',
+    bootstrap: true,
+    run: async () => {
+      const config = (await import('stonyx/config')).default;
+      const mysqlConfig = config.orm.mysql;
+
+      if (!mysqlConfig) {
+        console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');
+        process.exit(1);
+      }
+
+      const { getPool, closePool } = await import('./mysql/connection.js');
+      const { ensureMigrationsTable, getAppliedMigrations, getMigrationFiles, applyMigration, parseMigrationFile } = await import('./mysql/migration-runner.js');
+      const { readFile } = await import('@stonyx/utils/file');
+      const path = await import('path');
+
+      const pool = await getPool(mysqlConfig);
+      const migrationsPath = path.resolve(config.rootPath, mysqlConfig.migrationsDir);
+
+      try {
+        await ensureMigrationsTable(pool, mysqlConfig.migrationsTable);
+
+        const applied = await getAppliedMigrations(pool, mysqlConfig.migrationsTable);
+        const files = await getMigrationFiles(migrationsPath);
+        const pending = files.filter(f => !applied.includes(f));
+
+        if (pending.length === 0) {
+          console.log('No pending migrations.');
+          return;
+        }
+
+        console.log(`Applying ${pending.length} migration(s)...`);
+
+        for (const filename of pending) {
+          const content = await readFile(path.join(migrationsPath, filename));
+          const { up } = parseMigrationFile(content);
+
+          await applyMigration(pool, filename, up, mysqlConfig.migrationsTable);
+          console.log(`  Applied: ${filename}`);
+        }
+
+        console.log('All migrations applied.');
+      } finally {
+        await closePool();
+      }
+    }
+  },
+  'db:migrate:rollback': {
+    description: 'Rollback the most recent MySQL migration',
+    bootstrap: true,
+    run: async () => {
+      const config = (await import('stonyx/config')).default;
+      const mysqlConfig = config.orm.mysql;
+
+      if (!mysqlConfig) {
+        console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');
+        process.exit(1);
+      }
+
+      const { getPool, closePool } = await import('./mysql/connection.js');
+      const { ensureMigrationsTable, getAppliedMigrations, rollbackMigration, parseMigrationFile } = await import('./mysql/migration-runner.js');
+      const { readFile } = await import('@stonyx/utils/file');
+      const path = await import('path');
+
+      const pool = await getPool(mysqlConfig);
+      const migrationsPath = path.resolve(config.rootPath, mysqlConfig.migrationsDir);
+
+      try {
+        await ensureMigrationsTable(pool, mysqlConfig.migrationsTable);
+
+        const applied = await getAppliedMigrations(pool, mysqlConfig.migrationsTable);
+
+        if (applied.length === 0) {
+          console.log('No migrations to rollback.');
+          return;
+        }
+
+        const lastFilename = applied[applied.length - 1];
+        const content = await readFile(path.join(migrationsPath, lastFilename));
+        const { down } = parseMigrationFile(content);
+
+        if (!down) {
+          console.error(`No DOWN section found in ${lastFilename}. Cannot rollback.`);
+          process.exit(1);
+        }
+
+        await rollbackMigration(pool, lastFilename, down, mysqlConfig.migrationsTable);
+        console.log(`Rolled back: ${lastFilename}`);
+      } finally {
+        await closePool();
+      }
+    }
+  },
+  'db:migrate:status': {
+    description: 'Show status of MySQL migrations',
+    bootstrap: true,
+    run: async () => {
+      const config = (await import('stonyx/config')).default;
+      const mysqlConfig = config.orm.mysql;
+
+      if (!mysqlConfig) {
+        console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');
+        process.exit(1);
+      }
+
+      const { getPool, closePool } = await import('./mysql/connection.js');
+      const { ensureMigrationsTable, getAppliedMigrations, getMigrationFiles } = await import('./mysql/migration-runner.js');
+      const path = await import('path');
+
+      const pool = await getPool(mysqlConfig);
+      const migrationsPath = path.resolve(config.rootPath, mysqlConfig.migrationsDir);
+
+      try {
+        await ensureMigrationsTable(pool, mysqlConfig.migrationsTable);
+
+        const applied = new Set(await getAppliedMigrations(pool, mysqlConfig.migrationsTable));
+        const files = await getMigrationFiles(migrationsPath);
+
+        if (files.length === 0) {
+          console.log('No migration files found.');
+          return;
+        }
+
+        console.log('Migration status:');
+
+        for (const filename of files) {
+          const status = applied.has(filename) ? 'applied' : 'pending';
+          console.log(`  [${status}] ${filename}`);
+        }
+      } finally {
+        await closePool();
+      }
+    }
+  },
+};

package/src/db.js

@@ -18,14 +18,15 @@ import Cron from '@stonyx/cron';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import Orm, { createRecord, store } from '@stonyx/orm';
-import { createFile, updateFile, readFile } from '@stonyx/utils/file';
+import { createFile, createDirectory, updateFile, readFile, fileExists } from '@stonyx/utils/file';
+import path from 'path';
 
 export const dbKey = '__db';
 
 export default class DB {
   constructor() {
     if (DB.instance) return DB.instance;
-    
+
     DB.instance = this;
   }
 
@@ -38,12 +39,69 @@ export default class DB {
     return (await import(`${rootPath}/${schema}`)).default;
   }
 
+  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;
+  }
+
+  getDirPath() {
+    const { rootPath } = config;
+    const { file, directory } = config.orm.db;
+    const dbDir = path.dirname(path.resolve(`${rootPath}/${file}`));
+
+    return path.join(dbDir, directory);
+  }
+
+  async validateMode() {
+    const { rootPath } = config;
+    const { file, mode } = config.orm.db;
+    const collectionKeys = this.getCollectionKeys();
+    const dirPath = this.getDirPath();
+
+    if (mode === 'directory') {
+      const dbFilePath = path.resolve(`${rootPath}/${file}`);
+      const exists = await fileExists(dbFilePath);
+
+      if (exists) {
+        const data = await readFile(dbFilePath, { json: true });
+        const hasData = collectionKeys.some(key => Array.isArray(data[key]) && data[key].length > 0);
+
+        if (hasData) {
+          log.error(`DB mode mismatch: db.json contains data but mode is set to 'directory'. Run migration first:\n\n  stonyx db:migrate-to-directory\n`);
+          process.exit(1);
+        }
+      }
+    } else {
+      const dirExists = await fileExists(dirPath);
+
+      if (dirExists) {
+        const hasCollectionFiles = (await Promise.all(
+          collectionKeys.map(key => fileExists(path.join(dirPath, `${key}.json`)))
+        )).some(Boolean);
+
+        if (hasCollectionFiles) {
+          log.error(`DB mode mismatch: directory '${config.orm.db.directory}/' contains collection files but mode is set to 'file'. Run migration first:\n\n  stonyx db:migrate-to-file\n`);
+          process.exit(1);
+        }
+      }
+    }
+  }
+
   async init() {
     const { autosave, saveInterval } = config.orm.db;
-    
+
     store.set(dbKey, new Map());
     Orm.instance.models[`${dbKey}Model`] = await this.getSchema();
 
+    await this.validateMode();
     this.record = await this.getRecord();
 
     if (autosave !== 'true') return;
@@ -53,28 +111,96 @@ export default class DB {
 
   async create() {
     const { rootPath } = config;
-    const { file } = config.orm.db;
+    const { file, mode } = config.orm.db;
+
+    if (mode === 'directory') {
+      const dirPath = this.getDirPath();
+      const collectionKeys = this.getCollectionKeys();
+
+      await createDirectory(dirPath);
+
+      await Promise.all(collectionKeys.map(key =>
+        createFile(path.join(dirPath, `${key}.json`), [], { json: true })
+      ));
+
+      // Write empty-array skeleton to db.json
+      const skeleton = {};
+      for (const key of collectionKeys) skeleton[key] = [];
+
+      await createFile(`${rootPath}/${file}`, skeleton, { json: true });
+
+      return skeleton;
+    }
 
     createFile(`${rootPath}/${file}`, {}, { json: true });
 
     return {};
   }
-  
+
   async save() {
-    const { file } = config.orm.db;
+    const { file, mode } = config.orm.db;
     const jsonData = this.record.format();
     delete jsonData.id; // Don't save id
 
+    if (mode === 'directory') {
+      const dirPath = this.getDirPath();
+      const collectionKeys = this.getCollectionKeys();
+
+      // Write each collection to its own file in parallel
+      await Promise.all(collectionKeys.map(key =>
+        updateFile(path.join(dirPath, `${key}.json`), jsonData[key] || [], { json: true })
+      ));
+
+      // Write empty-array skeleton to db.json
+      const skeleton = {};
+      for (const key of collectionKeys) skeleton[key] = [];
+
+      await updateFile(`${config.rootPath}/${file}`, skeleton, { json: true });
+
+      log.db(`DB has been successfully saved to ${config.orm.db.directory}/ directory`);
+      return;
+    }
+
     await updateFile(`${config.rootPath}/${file}`, jsonData, { json: true });
 
     log.db(`DB has been successfully saved to ${file}`);
   }
 
   async getRecord() {
+    const { mode } = config.orm.db;
+
+    if (mode === 'directory') return this.getRecordFromDirectory();
+
+    return this.getRecordFromFile();
+  }
+
+  async getRecordFromFile() {
     const { file } = config.orm.db;
 
     const data = await readFile(file, { json: true, missingFileCallback: this.create.bind(this) });
 
     return createRecord(dbKey, data, { isDbRecord: true, serialize: false, transform: false });
   }
+
+  async getRecordFromDirectory() {
+    const dirPath = this.getDirPath();
+    const collectionKeys = this.getCollectionKeys();
+    const dirExists = await fileExists(dirPath);
+
+    if (!dirExists) {
+      const data = await this.create();
+      return createRecord(dbKey, data, { isDbRecord: true, serialize: false, transform: false });
+    }
+
+    const assembled = {};
+
+    await Promise.all(collectionKeys.map(async key => {
+      const filePath = path.join(dirPath, `${key}.json`);
+      const exists = await fileExists(filePath);
+
+      assembled[key] = exists ? await readFile(filePath, { json: true }) : [];
+    }));
+
+    return createRecord(dbKey, assembled, { isDbRecord: true, serialize: false, transform: false });
+  }
 }

package/src/hooks.js

@@ -0,0 +1,124 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the 'License');
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Middleware-based hooks registry for ORM operations.
+ * Unlike event-based hooks, middleware hooks run sequentially and can halt operations.
+ */
+
+// Map of "operation:model" -> handler[]
+const beforeHooks = new Map();
+const afterHooks = new Map();
+
+/**
+ * Register a before hook middleware that runs before the operation executes.
+ *
+ * @param {string} operation - Operation name: 'create', 'update', 'delete', 'get', or 'list'
+ * @param {string} model - Model name (e.g., 'user', 'animal')
+ * @param {Function} handler - Middleware function (context) => any
+ *   - Return undefined to continue to next hook/handler
+ *   - Return any value to halt operation (integer = HTTP status, object = response body)
+ * @returns {Function} Unsubscribe function
+ */
+export function beforeHook(operation, model, handler) {
+  const key = `${operation}:${model}`;
+  if (!beforeHooks.has(key)) {
+    beforeHooks.set(key, []);
+  }
+  beforeHooks.get(key).push(handler);
+
+  // Return unsubscribe function
+  return () => {
+    const hooks = beforeHooks.get(key);
+    if (hooks) {
+      const index = hooks.indexOf(handler);
+      if (index > -1) hooks.splice(index, 1);
+    }
+  };
+}
+
+/**
+ * Register an after hook middleware that runs after the operation completes.
+ * After hooks cannot halt operations (they run after completion).
+ *
+ * @param {string} operation - Operation name
+ * @param {string} model - Model name
+ * @param {Function} handler - Middleware function (context) => void
+ * @returns {Function} Unsubscribe function
+ */
+export function afterHook(operation, model, handler) {
+  const key = `${operation}:${model}`;
+  if (!afterHooks.has(key)) {
+    afterHooks.set(key, []);
+  }
+  afterHooks.get(key).push(handler);
+
+  // Return unsubscribe function
+  return () => {
+    const hooks = afterHooks.get(key);
+    if (hooks) {
+      const index = hooks.indexOf(handler);
+      if (index > -1) hooks.splice(index, 1);
+    }
+  };
+}
+
+/**
+ * Get all before hooks for an operation:model combination.
+ * @param {string} operation
+ * @param {string} model
+ * @returns {Function[]}
+ */
+export function getBeforeHooks(operation, model) {
+  const key = `${operation}:${model}`;
+  return beforeHooks.get(key) || [];
+}
+
+/**
+ * Get all after hooks for an operation:model combination.
+ * @param {string} operation
+ * @param {string} model
+ * @returns {Function[]}
+ */
+export function getAfterHooks(operation, model) {
+  const key = `${operation}:${model}`;
+  return afterHooks.get(key) || [];
+}
+
+/**
+ * Clear registered hooks for a specific operation:model.
+ *
+ * @param {string} operation - Operation name
+ * @param {string} model - Model name
+ * @param {string} [type] - 'before' or 'after' (if omitted, clears both)
+ */
+export function clearHook(operation, model, type) {
+  const key = `${operation}:${model}`;
+  if (!type || type === 'before') {
+    beforeHooks.set(key, []);
+  }
+  if (!type || type === 'after') {
+    afterHooks.set(key, []);
+  }
+}
+
+/**
+ * Clear all hooks (useful for testing).
+ */
+export function clearAllHooks() {
+  beforeHooks.clear();
+  afterHooks.clear();
+}

package/src/index.js

@@ -25,4 +25,11 @@ import { createRecord, updateRecord } from './manage-record.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
 export { Model, Serializer }; // base classes
-export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
+export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
+export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
+
+// Store API:
+// store.get(model, id)   — sync, memory-only
+// store.find(model, id)  — async, MySQL for memory:false models
+// store.findAll(model)   — async, all records
+// store.query(model, conditions) — async, always hits MySQL

package/src/main.js

@@ -19,10 +19,12 @@ import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
+import { registerPluralName } from './plural-registry.js';
 import setupRestServer from './setup-rest-server.js';
 import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
+import { setup } from '@stonyx/events';
 
 const defaultOptions = {
   dbType: 'json'
@@ -65,7 +67,10 @@ export default class Orm {
         // Transforms keep their original name, everything else gets converted to PascalCase with the type suffix
         const alias = type === 'Transform' ? name : `${kebabCaseToPascalCase(name)}${type}`;
 
-        if (type === 'Model') Orm.store.set(name, new Map());
+        if (type === 'Model') {
+          Orm.store.set(name, new Map());
+          registerPluralName(name, exported);
+        }
 
         return this[pluralize(lowerCaseType)][alias] = exported;
       }, { ignoreAccessFailure: true, rawName: true, recursive: true, recursiveNaming: true });
@@ -74,10 +79,30 @@ export default class Orm {
     // Wait for imports before db & rest server setup
     await Promise.all(promises);
 
-    if (this.options.dbType !== 'none') {
+    // Setup event names for hooks after models are loaded
+    const eventNames = [];
+    const operations = ['list', 'get', 'create', 'update', 'delete'];
+    const timings = ['before', 'after'];
+
+    for (const modelName of Orm.store.data.keys()) {
+      for (const timing of timings) {
+        for (const operation of operations) {
+          eventNames.push(`${timing}:${operation}:${modelName}`);
+        }
+      }
+    }
+
+    setup(eventNames);
+
+    if (config.orm.mysql) {
+      const { default: MysqlDB } = await import('./mysql/mysql-db.js');
+      this.mysqlDb = new MysqlDB();
+      this.db = this.mysqlDb;
+      promises.push(this.mysqlDb.init());
+    } else if (this.options.dbType !== 'none') {
       const db = new DB();
       this.db = db;
-      
+
       promises.push(db.init());
     }
 
@@ -85,10 +110,29 @@ export default class Orm {
       promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
     }
 
+    // Wire up memory resolver so store.find() can check model memory flags
+    Orm.store._memoryResolver = (modelName) => {
+      const { modelClass } = this.getRecordClasses(modelName);
+      return modelClass?.memory !== false;
+    };
+
+    // Wire up MySQL reference for on-demand queries from store.find()/findAll()
+    if (this.mysqlDb) {
+      Orm.store._mysqlDb = this.mysqlDb;
+    }
+
     Orm.ready = await Promise.all(promises);
     Orm.initialized = true;
   }
 
+  async startup() {
+    if (this.mysqlDb) await this.mysqlDb.startup();
+  }
+
+  async shutdown() {
+    if (this.mysqlDb) await this.mysqlDb.shutdown();
+  }
+
   static get db() {
     if (!Orm.initialized) throw new Error('ORM has not been initialized yet');
 

package/src/manage-record.js

@@ -90,14 +90,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);
+}