@stonyx/orm 0.2.5-alpha.0 → 0.3.1

package/src/belongs-to.ts

@@ -0,0 +1,90 @@
+import { createRecord, store } from '@stonyx/orm';
+import { getRelationships, getHasManyRegistry, getPendingRegistry, getPendingBelongsToRegistry } from './relationships.js';
+import type { SourceRecord } from './types/orm-types.js';
+
+function getOrSet<K, V>(map: Map<K, V>, key: K, defaultValue: V): V {
+  if (!map.has(key)) map.set(key, defaultValue);
+  return map.get(key) as V;
+}
+
+interface BelongsToOptions {
+  _relationshipKey?: string;
+  [key: string]: unknown;
+}
+
+interface PendingBelongsToEntry {
+  sourceRecord: SourceRecord;
+  sourceModelName: string;
+  relationshipKey: string | undefined;
+  relationshipId: unknown;
+}
+
+type RelationshipHandler = ((sourceRecord: SourceRecord, rawData: unknown, options: BelongsToOptions) => unknown) & {
+  __relatedModelName: string;
+  __relationshipType: 'belongsTo';
+};
+
+export default function belongsTo(modelName: string): RelationshipHandler {
+  const hasManyRelationships = getHasManyRegistry();
+  const pendingHasManyQueue = getPendingRegistry();
+  const pendingBelongsToQueue = getPendingBelongsToRegistry();
+
+  const fn = (sourceRecord: SourceRecord, rawData: unknown, options: BelongsToOptions): unknown => {
+    if (!rawData) return null;
+
+    const { __name: sourceModelName } = sourceRecord.__model;
+    const relationshipId = sourceRecord.id;
+    const relationshipKey = options._relationshipKey;
+    const relationship = getRelationships('belongsTo', sourceModelName, modelName, relationshipId as string) as Map<unknown, unknown>;
+    const modelStore = store.get(modelName);
+
+    // Try to get existing record
+    let output: unknown;
+
+    if (typeof rawData === 'object') {
+      output = createRecord(modelName, rawData as Record<string, unknown>, options);
+    } else if (modelStore) {
+      output = modelStore.get(rawData as number | string);
+    }
+
+    // If not found and is a string ID, register as pending
+    if (!output && typeof rawData !== 'object') {
+      const targetId = rawData;
+
+      // Register pending belongsTo
+      const modelPendingMap = getOrSet(pendingBelongsToQueue, modelName, new Map());
+      const targetPendingArray = getOrSet(modelPendingMap, targetId, []);
+
+      targetPendingArray.push({
+        sourceRecord,
+        sourceModelName,
+        relationshipKey,
+        relationshipId
+      });
+
+      relationship.set(relationshipId, null);
+      return null;
+    }
+
+    relationship.set(relationshipId, output || {});
+
+    // Populate hasMany side if the relationship is defined
+    const outputRecord = typeof output === 'object' && output !== null && 'id' in output ? output as SourceRecord : undefined;
+    const otherSide = outputRecord ? hasManyRelationships.get(modelName)?.get(sourceModelName)?.get(outputRecord.id) as unknown[] | undefined : undefined;
+
+    if (otherSide) {
+      otherSide.push(sourceRecord);
+
+      // Remove pending queue if it was just fulfilled
+      const pendingModelRelationships = pendingHasManyQueue.get(sourceModelName);
+
+      if (pendingModelRelationships) pendingModelRelationships.delete(relationshipId);
+    }
+
+    return output;
+  };
+
+  Object.defineProperty(fn, '__relatedModelName', { value: modelName });
+  Object.defineProperty(fn, '__relationshipType', { value: 'belongsTo' as const });
+  return fn as RelationshipHandler;
+}

package/src/cli.ts

@@ -0,0 +1,183 @@
+#!/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';
+
+interface CLIConfig {
+  mode: 'file' | 'directory';
+  dbPath: string;
+  directory: string;
+}
+
+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: string[]): Promise<CLIConfig> {
+  const config: Record<string, string> = {};
+
+  // 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 instanceof Error ? err.message : String(err)}`);
+      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') as 'file' | 'directory',
+    dbPath: process.env.DB_PATH || config.dbPath || 'db.json',
+    directory: process.env.DB_DIRECTORY || config.directory || 'db',
+  };
+}
+
+function parseArgs(argv: string[]): string[] {
+  // 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(): Promise<void> {
+  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 instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+run();

package/src/commands.ts

@@ -0,0 +1,179 @@
+import { fileToDirectory, directoryToFile } from './migrate.js';
+import type { MysqlConfig } from './mysql/connection.js';
+
+interface Command {
+  description: string;
+  bootstrap: boolean;
+  run: (args?: string[]) => Promise<void>;
+}
+
+const commands: Record<string, Command> = {
+  '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 as MysqlConfig);
+      const migrationsPath = path.resolve(config.rootPath, mysqlConfig.migrationsDir as string);
+
+      try {
+        await ensureMigrationsTable(pool, mysqlConfig.migrationsTable as string);
+
+        const applied = await getAppliedMigrations(pool, mysqlConfig.migrationsTable as string);
+        const files = await getMigrationFiles(migrationsPath);
+        const pending = files.filter((f: string) => !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) as string) as string;
+          const { up } = parseMigrationFile(content);
+
+          await applyMigration(pool, filename, up, mysqlConfig.migrationsTable as string);
+          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 as MysqlConfig);
+      const migrationsPath = path.resolve(config.rootPath, mysqlConfig.migrationsDir as string);
+
+      try {
+        await ensureMigrationsTable(pool, mysqlConfig.migrationsTable as string);
+
+        const applied = await getAppliedMigrations(pool, mysqlConfig.migrationsTable as string);
+
+        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) as string) as string;
+        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 as string);
+        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 as MysqlConfig);
+      const migrationsPath = path.resolve(config.rootPath, mysqlConfig.migrationsDir as string);
+
+      try {
+        await ensureMigrationsTable(pool, mysqlConfig.migrationsTable as string);
+
+        const applied = new Set(await getAppliedMigrations(pool, mysqlConfig.migrationsTable as string));
+        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();
+      }
+    }
+  },
+};
+
+export default commands;

package/src/db.ts

@@ -0,0 +1,232 @@
+/*
+ * 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.
+ */
+
+import Cron from '@stonyx/cron';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import Orm, { store } from '@stonyx/orm';
+import { createRecord } from './manage-record.js';
+import { createFile, createDirectory, updateFile, readFile, fileExists } from '@stonyx/utils/file';
+import path from 'path';
+
+export const dbKey = '__db';
+
+interface DBRecord {
+  format(): Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+function asDBRecord(value: unknown): DBRecord {
+  if (typeof value !== 'object' || value === null || typeof (value as DBRecord).format !== 'function') {
+    throw new Error('createRecord did not return a valid DBRecord');
+  }
+  return value as DBRecord;
+}
+
+export default class DB {
+  static instance: DB;
+  record!: DBRecord;
+
+  constructor() {
+    if (DB.instance) return DB.instance;
+
+    DB.instance = this;
+  }
+
+  async getSchema(): Promise<unknown> {
+    const { rootPath } = config;
+    const { file, schema } = config.orm.db;
+
+    if (!file) throw new Error('Configuration Error: ORM DB file path must be defined.');
+
+    return (await import(`${rootPath}/${schema}`)).default;
+  }
+
+  getCollectionKeys(): string[] {
+    const SchemaClass = Orm.instance.models[`${dbKey}Model`] as new () => Record<string, unknown>;
+    const instance = new SchemaClass();
+    const keys: string[] = [];
+
+    for (const key of Object.keys(instance)) {
+      if (key === '__name' || key === 'id') continue;
+      if (typeof instance[key] === 'function') keys.push(key);
+    }
+
+    return keys;
+  }
+
+  getDirPath(): string {
+    const { rootPath } = config;
+    const { file, directory } = config.orm.db;
+    const dbDir = path.dirname(path.resolve(`${rootPath}/${file}`));
+
+    return path.join(dbDir, directory);
+  }
+
+  async validateMode(): Promise<void> {
+    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 }) as Record<string, unknown[]>;
+        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(): Promise<void> {
+    const { autosave, saveInterval } = config.orm.db;
+
+    store.set(dbKey, new Map());
+    (Orm.instance as Orm).models[`${dbKey}Model`] = await this.getSchema();
+
+    await this.validateMode();
+    this.record = await this.getRecord();
+
+    if (autosave !== 'true') return;
+
+    new Cron().register('save', this.save.bind(this), saveInterval);
+  }
+
+  async create(): Promise<Record<string, unknown>> {
+    const { rootPath } = config;
+    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: Record<string, unknown[]> = {};
+      for (const key of collectionKeys) skeleton[key] = [];
+
+      await createFile(`${rootPath}/${file}`, skeleton, { json: true });
+
+      return skeleton;
+    }
+
+    createFile(`${rootPath}/${file}`, {}, { json: true });
+
+    return {};
+  }
+
+  async save(): Promise<void> {
+    const { file, mode } = config.orm.db;
+    const jsonData = this.record.format() as Record<string, unknown>;
+    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] || []) as Record<string, unknown> | unknown[];
+
+        if (exists) await updateFile(filePath, data, { json: true });
+        else await createFile(filePath, data, { json: true });
+      }));
+
+      // Write empty-array skeleton to db.json
+      const skeleton: Record<string, unknown[]> = {};
+      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(): Promise<DBRecord> {
+    const { mode } = config.orm.db;
+
+    if (mode === 'directory') return this.getRecordFromDirectory();
+
+    return this.getRecordFromFile();
+  }
+
+  async getRecordFromFile(): Promise<DBRecord> {
+    const { file } = config.orm.db;
+
+    const data = await readFile(file, { json: true, missingFileCallback: this.create.bind(this) });
+
+    return asDBRecord(createRecord(dbKey, data as Record<string, unknown>, { isDbRecord: true, serialize: false, transform: false }));
+  }
+
+  async getRecordFromDirectory(): Promise<DBRecord> {
+    const dirPath = this.getDirPath();
+    const collectionKeys = this.getCollectionKeys();
+    const dirExists = await fileExists(dirPath);
+
+    if (!dirExists) {
+      const data = await this.create();
+      return asDBRecord(createRecord(dbKey, data, { isDbRecord: true, serialize: false, transform: false }));
+    }
+
+    const assembled: Record<string, unknown> = {};
+
+    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 asDBRecord(createRecord(dbKey, assembled, { isDbRecord: true, serialize: false, transform: false }));
+  }
+}

package/src/exports/db.ts

@@ -0,0 +1,7 @@
+import Orm from '@stonyx/orm';
+
+const db = Orm.db as { record: unknown; save(): Promise<void> };
+
+export default db;
+export const data = db.record;
+export const saveDB = db.save.bind(db);