millas 0.1.0

package/src/orm/drivers/DatabaseManager.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * DatabaseManager
+ *
+ * Creates and caches knex connection instances per named connection.
+ * Reads from config/database.js (or the config object passed in).
+ *
+ * Usage:
+ *   const db = DatabaseManager.connection();           // default
+ *   const db = DatabaseManager.connection('mysql');    // named
+ *   await db.schema.createTable(...)
+ *   await db('users').select('*')
+ */
+class DatabaseManager {
+  constructor() {
+    this._connections = new Map();
+    this._config      = null;
+    this._default     = null;
+  }
+
+  /**
+   * Configure the manager with a database config object.
+   * Called automatically by DatabaseServiceProvider.
+   */
+  configure(config) {
+    this._config  = config;
+    this._default = config.default || 'sqlite';
+  }
+
+  /**
+   * Get (or create) a knex connection by name.
+   * @param {string} name — connection name from config/database.js
+   */
+  connection(name) {
+    const connName = name || this._default;
+
+    if (this._connections.has(connName)) {
+      return this._connections.get(connName);
+    }
+
+    const conn = this._makeConnection(connName);
+    this._connections.set(connName, conn);
+    return conn;
+  }
+
+  /**
+   * Shorthand for the default connection.
+   */
+  get db() {
+    return this.connection();
+  }
+
+  /**
+   * Close all connections.
+   */
+  async closeAll() {
+    for (const [, conn] of this._connections) {
+      await conn.destroy();
+    }
+    this._connections.clear();
+  }
+
+  /**
+   * Close a specific connection.
+   */
+  async close(name) {
+    const conn = this._connections.get(name || this._default);
+    if (conn) {
+      await conn.destroy();
+      this._connections.delete(name || this._default);
+    }
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  _makeConnection(name) {
+    if (!this._config) {
+      throw new Error(
+        'DatabaseManager not configured. ' +
+        'Did you boot DatabaseServiceProvider?'
+      );
+    }
+
+    const conf = this._config.connections?.[name];
+    if (!conf) {
+      throw new Error(`Database connection "${name}" is not defined in config/database.js`);
+    }
+
+    const knex = require('knex');
+
+    switch (conf.driver) {
+      case 'sqlite':
+        return knex({
+          client:            'sqlite3',
+          connection:        { filename: conf.database },
+          useNullAsDefault:  true,
+          asyncStackTraces:  process.env.NODE_ENV !== 'production',
+        });
+
+      case 'mysql':
+        return knex({
+          client:     'mysql2',
+          connection: {
+            host:     conf.host,
+            port:     conf.port,
+            database: conf.database,
+            user:     conf.username,
+            password: conf.password,
+          },
+          pool: { min: 2, max: 10 },
+        });
+
+      case 'postgres':
+        return knex({
+          client:     'pg',
+          connection: {
+            host:     conf.host,
+            port:     conf.port,
+            database: conf.database,
+            user:     conf.username,
+            password: conf.password,
+          },
+          pool: { min: 2, max: 10 },
+        });
+
+      default:
+        throw new Error(`Unsupported database driver: "${conf.driver}"`);
+    }
+  }
+}
+
+// Singleton — shared across the whole application
+const manager = new DatabaseManager();
+module.exports = manager;

package/src/orm/fields/index.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * fields
+ *
+ * Schema field definitions used inside Model.fields = { ... }
+ *
+ * Usage:
+ *   class User extends Model {
+ *     static fields = {
+ *       id:         fields.id(),
+ *       name:       fields.string({ max: 100 }),
+ *       email:      fields.string({ unique: true }),
+ *       age:        fields.integer({ nullable: true }),
+ *       score:      fields.float({ default: 0.0 }),
+ *       active:     fields.boolean({ default: true }),
+ *       bio:        fields.text({ nullable: true }),
+ *       data:       fields.json({ nullable: true }),
+ *       role:       fields.enum(['admin', 'user', 'guest'], { default: 'user' }),
+ *       created_at: fields.timestamp(),
+ *       updated_at: fields.timestamp(),
+ *     };
+ *   }
+ */
+
+class FieldDefinition {
+  constructor(type, options = {}) {
+    this.type      = type;
+    this.options   = options;
+    this.nullable  = options.nullable  ?? false;
+    this.unique    = options.unique    ?? false;
+    this.default   = options.default   !== undefined ? options.default : undefined;
+    this.primary   = options.primary   ?? false;
+    this.unsigned  = options.unsigned  ?? false;
+    this.max       = options.max       ?? null;
+    this.enumValues = options.enumValues ?? null;
+    this.references = options.references ?? null; // { table, column }
+  }
+
+  // ─── Fluent modifiers ──────────────────────────────────────────
+
+  nullable_(val = true)    { this.nullable  = val;  return this; }
+  unique_(val = true)      { this.unique    = val;  return this; }
+  default_(val)            { this.default   = val;  return this; }
+  unsigned_(val = true)    { this.unsigned  = val;  return this; }
+  references_(table, col)  { this.references = { table, column: col }; return this; }
+}
+
+const fields = {
+  /** Auto-incrementing primary key */
+  id(options = {}) {
+    return new FieldDefinition('id', { primary: true, unsigned: true, ...options });
+  },
+
+  /** VARCHAR / TEXT string */
+  string(options = {}) {
+    return new FieldDefinition('string', { max: 255, ...options });
+  },
+
+  /** LONGTEXT */
+  text(options = {}) {
+    return new FieldDefinition('text', options);
+  },
+
+  /** INT */
+  integer(options = {}) {
+    return new FieldDefinition('integer', options);
+  },
+
+  /** BIGINT */
+  bigInteger(options = {}) {
+    return new FieldDefinition('bigInteger', options);
+  },
+
+  /** FLOAT / DOUBLE */
+  float(options = {}) {
+    return new FieldDefinition('float', options);
+  },
+
+  /** DECIMAL(precision, scale) */
+  decimal(precision = 8, scale = 2, options = {}) {
+    return new FieldDefinition('decimal', { precision, scale, ...options });
+  },
+
+  /** TINYINT(1) boolean */
+  boolean(options = {}) {
+    return new FieldDefinition('boolean', options);
+  },
+
+  /** JSON blob */
+  json(options = {}) {
+    return new FieldDefinition('json', options);
+  },
+
+  /** DATE */
+  date(options = {}) {
+    return new FieldDefinition('date', options);
+  },
+
+  /** DATETIME / TIMESTAMP */
+  timestamp(options = {}) {
+    return new FieldDefinition('timestamp', { nullable: true, ...options });
+  },
+
+  /** ENUM */
+  enum(values, options = {}) {
+    return new FieldDefinition('enum', { enumValues: values, ...options });
+  },
+
+  /** UUID */
+  uuid(options = {}) {
+    return new FieldDefinition('uuid', options);
+  },
+
+  /**
+   * Foreign key integer shorthand.
+   * fields.foreignId('user_id') → unsigned integer, references users.id
+   */
+  foreignId(column, options = {}) {
+    const [table, col] = column.endsWith('_id')
+      ? [column.slice(0, -3) + 's', 'id']
+      : [null, null];
+    return new FieldDefinition('integer', {
+      unsigned: true,
+      nullable: options.nullable ?? false,
+      references: table ? { table, column: col } : null,
+      ...options,
+    });
+  },
+};
+
+module.exports = { fields, FieldDefinition };

package/src/orm/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const Model           = require('./model/Model');
+const { fields }      = require('./fields');
+const QueryBuilder    = require('./query/QueryBuilder');
+const DatabaseManager = require('./drivers/DatabaseManager');
+const SchemaBuilder   = require('./migration/SchemaBuilder');
+const MigrationRunner = require('./migration/MigrationRunner');
+const ModelInspector  = require('./migration/ModelInspector');
+
+module.exports = {
+  Model,
+  fields,
+  QueryBuilder,
+  DatabaseManager,
+  SchemaBuilder,
+  MigrationRunner,
+  ModelInspector,
+};

package/src/orm/migration/MigrationRunner.js

@@ -0,0 +1,216 @@
+'use strict';
+
+const fs   = require('fs-extra');
+const path = require('path');
+
+/**
+ * MigrationRunner
+ *
+ * Handles the full migration lifecycle:
+ *   - run pending migrations (migrate)
+ *   - rollback last batch (migrate:rollback)
+ *   - show status table (migrate:status)
+ *   - drop all + re-run (migrate:fresh)
+ *   - rollback all (migrate:reset)
+ *   - rollback all + re-run (migrate:refresh)
+ *
+ * Migration history is tracked in the `millas_migrations` table.
+ * Each migration file must export { up(db), down(db) }.
+ */
+class MigrationRunner {
+  /**
+   * @param {object} knexConn   — live knex connection
+   * @param {string} migrationsPath — absolute path to migrations dir
+   */
+  constructor(knexConn, migrationsPath) {
+    this._db   = knexConn;
+    this._path = migrationsPath;
+  }
+
+  // ─── Public commands ──────────────────────────────────────────────────────
+
+  /**
+   * Run all pending migrations.
+   */
+  async migrate() {
+    await this._ensureTable();
+    const pending = await this._pending();
+
+    if (pending.length === 0) {
+      return { ran: [], message: 'Nothing to migrate.' };
+    }
+
+    const batch = await this._nextBatch();
+    const ran   = [];
+
+    for (const file of pending) {
+      const migration = this._load(file);
+      await migration.up(this._db);
+      await this._record(file, batch);
+      ran.push(file);
+    }
+
+    return { ran, batch, message: `Ran ${ran.length} migration(s).` };
+  }
+
+  /**
+   * Rollback the last batch of migrations.
+   */
+  async rollback(steps = 1) {
+    await this._ensureTable();
+    const batches = await this._lastBatches(steps);
+
+    if (batches.length === 0) {
+      return { rolledBack: [], message: 'Nothing to rollback.' };
+    }
+
+    const rolledBack = [];
+
+    // Run in reverse order
+    for (const row of [...batches].reverse()) {
+      const migration = this._load(row.name);
+      await migration.down(this._db);
+      await this._db('millas_migrations').where('name', row.name).delete();
+      rolledBack.push(row.name);
+    }
+
+    return { rolledBack, message: `Rolled back ${rolledBack.length} migration(s).` };
+  }
+
+  /**
+   * Drop all tables and re-run every migration.
+   */
+  async fresh() {
+    await this._dropAllTables();
+    await this._ensureTable();
+    return this.migrate();
+  }
+
+  /**
+   * Rollback ALL migrations.
+   */
+  async reset() {
+    await this._ensureTable();
+    const all = await this._db('millas_migrations').orderBy('id', 'desc');
+
+    if (all.length === 0) {
+      return { rolledBack: [], message: 'Nothing to reset.' };
+    }
+
+    const rolledBack = [];
+    for (const row of all) {
+      const migration = this._load(row.name);
+      await migration.down(this._db);
+      await this._db('millas_migrations').where('name', row.name).delete();
+      rolledBack.push(row.name);
+    }
+
+    return { rolledBack, message: `Reset ${rolledBack.length} migration(s).` };
+  }
+
+  /**
+   * Rollback all then re-run all.
+   */
+  async refresh() {
+    await this.reset();
+    return this.migrate();
+  }
+
+  /**
+   * Return status of all migration files.
+   */
+  async status() {
+    await this._ensureTable();
+    const files = this._files();
+    const ran   = await this._ranNames();
+
+    return files.map(file => ({
+      name:   file,
+      status: ran.has(file) ? 'Ran' : 'Pending',
+      batch:  ran.get ? ran.get(file) : null,
+    }));
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  async _ensureTable() {
+    const exists = await this._db.schema.hasTable('millas_migrations');
+    if (exists) return;
+
+    await this._db.schema.createTable('millas_migrations', (t) => {
+      t.increments('id');
+      t.string('name').notNullable().unique();
+      t.integer('batch').notNullable();
+      t.timestamp('ran_at').defaultTo(this._db.fn.now());
+    });
+  }
+
+  async _pending() {
+    const ran   = await this._ranNames();
+    const files = this._files();
+    return files.filter(f => !ran.has(f));
+  }
+
+  async _ranNames() {
+    const rows = await this._db('millas_migrations').select('name', 'batch');
+    const map  = new Map(rows.map(r => [r.name, r.batch]));
+    // Map with has() and get()
+    return map;
+  }
+
+  async _nextBatch() {
+    const result = await this._db('millas_migrations').max('batch as max').first();
+    return (result?.max || 0) + 1;
+  }
+
+  async _lastBatches(steps = 1) {
+    const maxBatch = await this._db('millas_migrations').max('batch as max').first();
+    if (!maxBatch?.max) return [];
+
+    const fromBatch = maxBatch.max - steps + 1;
+    // Fetch all then filter in JS to avoid needing >= support in all drivers
+    const all = await this._db('millas_migrations').orderBy('id', 'desc');
+    return all.filter(r => r.batch >= fromBatch);
+  }
+
+  async _dropAllTables() {
+    // Get all table names (SQLite compatible)
+    const tables = await this._db
+      .select('name')
+      .from('sqlite_master')
+      .where('type', 'table')
+      .whereNot('name', 'like', 'sqlite_%');
+
+    for (const { name } of tables) {
+      await this._db.schema.dropTableIfExists(name);
+    }
+  }
+
+  _files() {
+    if (!fs.existsSync(this._path)) return [];
+    return fs.readdirSync(this._path)
+      .filter(f => f.endsWith('.js') && !f.startsWith('.'))
+      .sort(); // Sorted by timestamp prefix
+  }
+
+  _load(name) {
+    const filePath = path.join(this._path, name);
+    // Clear require cache so fresh loads work in tests
+    delete require.cache[require.resolve(filePath)];
+    const migration = require(filePath);
+    if (typeof migration.up !== 'function' || typeof migration.down !== 'function') {
+      throw new Error(`Migration "${name}" must export { up(db), down(db) }`);
+    }
+    return migration;
+  }
+
+  async _record(name, batch) {
+    await this._db('millas_migrations').insert({
+      name,
+      batch,
+      ran_at: new Date().toISOString(),
+    });
+  }
+}
+
+module.exports = MigrationRunner;