@stonyx/orm 0.2.1-alpha.3 → 0.2.1-alpha.31

package/src/aggregates.js

@@ -0,0 +1,93 @@
+export class AggregateProperty {
+  constructor(aggregateType, relationship, field) {
+    this.aggregateType = aggregateType;
+    this.relationship = relationship;
+    this.field = field;
+    this.mysqlFunction = aggregateType.toUpperCase();
+    this.resultType = aggregateType === 'avg' ? 'float' : 'number';
+  }
+
+  compute(relatedRecords) {
+    if (!relatedRecords || !Array.isArray(relatedRecords) || relatedRecords.length === 0) {
+      if (this.aggregateType === 'min' || this.aggregateType === 'max') return null;
+      return 0;
+    }
+
+    switch (this.aggregateType) {
+      case 'count':
+        return relatedRecords.length;
+
+      case 'sum':
+        return relatedRecords.reduce((acc, record) => {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          return acc + (isNaN(val) ? 0 : val);
+        }, 0);
+
+      case 'avg': {
+        let sum = 0;
+        let count = 0;
+        for (const record of relatedRecords) {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          if (!isNaN(val)) {
+            sum += val;
+            count++;
+          }
+        }
+        return count === 0 ? 0 : sum / count;
+      }
+
+      case 'min': {
+        let min = null;
+        for (const record of relatedRecords) {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          if (!isNaN(val) && (min === null || val < min)) min = val;
+        }
+        return min;
+      }
+
+      case 'max': {
+        let max = null;
+        for (const record of relatedRecords) {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          if (!isNaN(val) && (max === null || val > max)) max = val;
+        }
+        return max;
+      }
+
+      default:
+        return null;
+    }
+  }
+}
+
+export function count(relationship) {
+  return new AggregateProperty('count', relationship);
+}
+
+export function avg(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('avg', relationshipOrField, field);
+  }
+  return new AggregateProperty('avg', undefined, relationshipOrField);
+}
+
+export function sum(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('sum', relationshipOrField, field);
+  }
+  return new AggregateProperty('sum', undefined, relationshipOrField);
+}
+
+export function min(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('min', relationshipOrField, field);
+  }
+  return new AggregateProperty('min', undefined, relationshipOrField);
+}
+
+export function max(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('max', relationshipOrField, field);
+  }
+  return new AggregateProperty('max', undefined, relationshipOrField);
+}

package/src/belongs-to.js

@@ -11,7 +11,7 @@ export default function belongsTo(modelName) {
   const pendingHasManyQueue = relationships.get('pending');
   const pendingBelongsToQueue = relationships.get('pendingBelongsTo');
 
-  return (sourceRecord, rawData, options) => {
+  const fn = (sourceRecord, rawData, options) => {
     if (!rawData) return null;
 
     const { __name: sourceModelName } = sourceRecord.__model;
@@ -60,4 +60,7 @@ export default function belongsTo(modelName) {
 
     return output;
   }
+
+  Object.defineProperty(fn, '__relatedModelName', { value: modelName });
+  return fn;
 }

package/src/cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone CLI for ORM database operations.
+ *
+ * Performs CRUD operations on the JSON database without requiring
+ * the full Stonyx bootstrap. Supports both file and directory modes.
+ *
+ * Usage:
+ *   stonyx-orm create <collection> <json-data>
+ *   stonyx-orm list <collection>
+ *   stonyx-orm get <collection> <id>
+ *   stonyx-orm delete <collection> <id>
+ *
+ * Configuration (environment variables):
+ *   DB_MODE      — 'file' or 'directory' (default: 'directory')
+ *   DB_PATH      — Path to db.json (default: 'db.json')
+ *   DB_DIRECTORY  — Directory name for collection files (default: 'db')
+ *
+ * Configuration (CLI flag):
+ *   --config <path>  — Path to a JSON config file with { mode, dbPath, directory }
+ */
+
+import StandaloneDB from './standalone-db.js';
+import fs from 'fs/promises';
+
+const USAGE = `Usage: stonyx-orm <command> [options]
+
+Commands:
+  create <collection> <json-data>   Create a record
+  list   <collection>               List all records
+  get    <collection> <id>          Get a record by ID
+  delete <collection> <id>          Delete a record by ID
+
+Options:
+  --config <path>   Path to JSON config file
+  --help            Show this help message
+
+Environment variables:
+  DB_MODE       'file' or 'directory' (default: 'directory')
+  DB_PATH       Path to db.json (default: 'db.json')
+  DB_DIRECTORY  Directory name for collection files (default: 'db')`;
+
+async function loadConfig(args) {
+  const config = {};
+
+  // Check for --config flag
+  const configIndex = args.indexOf('--config');
+
+  if (configIndex !== -1 && args[configIndex + 1]) {
+    const configPath = args[configIndex + 1];
+
+    try {
+      const content = await fs.readFile(configPath, 'utf-8');
+      Object.assign(config, JSON.parse(content));
+    } catch (err) {
+      console.error(`Error reading config file '${configPath}': ${err.message}`);
+      process.exit(1);
+    }
+
+    // Remove --config and its value from args
+    args.splice(configIndex, 2);
+  }
+
+  // Environment variables override config file, config file overrides defaults
+  return {
+    mode: process.env.DB_MODE || config.mode || 'directory',
+    dbPath: process.env.DB_PATH || config.dbPath || 'db.json',
+    directory: process.env.DB_DIRECTORY || config.directory || 'db',
+  };
+}
+
+function parseArgs(argv) {
+  // Strip node binary and script path
+  const args = argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  return args;
+}
+
+async function run() {
+  const args = parseArgs(process.argv);
+  const config = await loadConfig(args);
+  const db = new StandaloneDB(config);
+
+  const [command, collection, ...rest] = args;
+
+  if (!command) {
+    console.error('Error: No command specified.\n');
+    console.log(USAGE);
+    process.exit(1);
+  }
+
+  if (!collection && command !== '--help') {
+    console.error(`Error: No collection specified for '${command}' command.\n`);
+    console.log(USAGE);
+    process.exit(1);
+  }
+
+  try {
+    switch (command) {
+      case 'list': {
+        const records = await db.list(collection);
+        console.log(JSON.stringify(records, null, 2));
+        break;
+      }
+
+      case 'get': {
+        const id = rest[0];
+
+        if (!id) {
+          console.error("Error: 'get' command requires an <id> argument.");
+          process.exit(1);
+        }
+
+        const record = await db.get(collection, id);
+
+        if (!record) {
+          console.error(`Record with id '${id}' not found in '${collection}'.`);
+          process.exit(1);
+        }
+
+        console.log(JSON.stringify(record, null, 2));
+        break;
+      }
+
+      case 'create': {
+        const jsonStr = rest.join(' ');
+
+        if (!jsonStr) {
+          console.error("Error: 'create' command requires <json-data> argument.");
+          process.exit(1);
+        }
+
+        let data;
+
+        try {
+          data = JSON.parse(jsonStr);
+        } catch {
+          console.error(`Error: Invalid JSON data: ${jsonStr}`);
+          process.exit(1);
+        }
+
+        const created = await db.create(collection, data);
+        console.log(JSON.stringify(created, null, 2));
+        break;
+      }
+
+      case 'delete': {
+        const deleteId = rest[0];
+
+        if (!deleteId) {
+          console.error("Error: 'delete' command requires an <id> argument.");
+          process.exit(1);
+        }
+
+        const removed = await db.delete(collection, deleteId);
+        console.log(JSON.stringify(removed, null, 2));
+        break;
+      }
+
+      default:
+        console.error(`Error: Unknown command '${command}'.\n`);
+        console.log(USAGE);
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+run();

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,106 @@ 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
+      // Use createFile for new files, updateFile for existing ones
+      await Promise.all(collectionKeys.map(async key => {
+        const filePath = path.join(dirPath, `${key}.json`);
+        const exists = await fileExists(filePath);
+        const data = jsonData[key] || [];
+
+        if (exists) await updateFile(filePath, data, { json: true });
+        else await createFile(filePath, data, { json: true });
+      }));
+
+      // Write empty-array skeleton to db.json
+      const skeleton = {};
+      for (const key of collectionKeys) skeleton[key] = [];
+
+      const dbFilePath = `${config.rootPath}/${file}`;
+      const dbFileExists = await fileExists(dbFilePath);
+
+      if (dbFileExists) await updateFile(dbFilePath, skeleton, { json: true });
+      else await createFile(dbFilePath, 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/has-many.js

@@ -16,7 +16,7 @@ export default function hasMany(modelName) {
   const globalRelationships = relationships.get('global');
   const pendingRelationships = relationships.get('pending');
 
-  return (sourceRecord, rawData, options) => {
+  const fn = (sourceRecord, rawData, options) => {
     const { __name: sourceModelName } = sourceRecord.__model;
     const relationshipId = sourceRecord.id;
     const relationship = getRelationships('hasMany', sourceModelName, modelName, relationshipId);
@@ -58,4 +58,7 @@ export default function hasMany(modelName) {
 
     return output;
   }
+
+  Object.defineProperty(fn, '__relatedModelName', { value: modelName });
+  return fn;
 }