millas 0.1.0

package/src/orm/model/Model.js

@@ -0,0 +1,371 @@
+'use strict';
+
+const QueryBuilder   = require('../query/QueryBuilder');
+const DatabaseManager = require('../drivers/DatabaseManager');
+
+/**
+ * Model
+ *
+ * Base class for all Millas ORM models.
+ *
+ * Define your schema with static fields and interact via static
+ * query methods — no instantiation needed for reads.
+ *
+ * Usage:
+ *
+ *   const { Model, fields } = require('millas/src/orm');
+ *
+ *   class User extends Model {
+ *     static table  = 'users';
+ *     static fields = {
+ *       id:         fields.id(),
+ *       name:       fields.string(),
+ *       email:      fields.string({ unique: true }),
+ *       active:     fields.boolean({ default: true }),
+ *       created_at: fields.timestamp(),
+ *       updated_at: fields.timestamp(),
+ *     };
+ *   }
+ *
+ *   // CRUD
+ *   const user  = await User.create({ name: 'Alice', email: 'a@b.com' });
+ *   const users = await User.all();
+ *   const found = await User.find(1);
+ *   const alice = await User.findBy('email', 'a@b.com');
+ *   await user.update({ name: 'Alice Smith' });
+ *   await user.delete();
+ *
+ *   // Query builder
+ *   const active = await User.where('active', true).orderBy('name').get();
+ *   const admins = await User.where('role', 'admin').limit(10).get();
+ *   const page   = await User.where('active', true).paginate(1, 15);
+ */
+class Model {
+  // ─── Static schema config ─────────────────────────────────────────────────
+
+  /** @type {string} Table name — defaults to pluralised lowercase class name */
+  static get table() {
+    return this._table || (this._table = this._defaultTable());
+  }
+  static set table(v) { this._table = v; }
+
+  /** @type {string} Primary key column name */
+  static primaryKey = 'id';
+
+  /** @type {boolean} Whether to auto-manage created_at / updated_at */
+  static timestamps = true;
+
+  /** @type {object} Field definitions */
+  static fields = {};
+
+  /** @type {string|null} Named DB connection to use */
+  static connection = null;
+
+  // ─── Static CRUD methods ──────────────────────────────────────────────────
+
+  /**
+   * Return all rows.
+   */
+  static async all() {
+    const rows = await this._db();
+    return rows.map(r => this._hydrate(r));
+  }
+
+  /**
+   * Find by primary key. Returns null if not found.
+   */
+  static async find(id) {
+    const row = await this._db().where(this.primaryKey, id).first();
+    return row ? this._hydrate(row) : null;
+  }
+
+  /**
+   * Find by primary key. Throws 404 HttpError if not found.
+   */
+  static async findOrFail(id) {
+    const result = await this.find(id);
+    if (!result) {
+      const HttpError = require('../../errors/HttpError');
+      throw new HttpError(404, `${this.name} #${id} not found`);
+    }
+    return result;
+  }
+
+  /**
+   * Find the first row matching column = value.
+   */
+  static async findBy(column, value) {
+    const row = await this._db().where(column, value).first();
+    return row ? this._hydrate(row) : null;
+  }
+
+  /**
+   * Find the first row matching column = value or throw 404.
+   */
+  static async findByOrFail(column, value) {
+    const result = await this.findBy(column, value);
+    if (!result) {
+      const HttpError = require('../../errors/HttpError');
+      throw new HttpError(404, `${this.name} not found`);
+    }
+    return result;
+  }
+
+  /**
+   * Create a new row and return the model instance.
+   */
+  static async create(data) {
+    const now = new Date().toISOString();
+    const payload = {
+      ...this._applyDefaults(data),
+      ...(this.timestamps ? { created_at: now, updated_at: now } : {}),
+    };
+
+    const [id] = await this._db().insert(payload);
+    return this.find(id);
+  }
+
+  /**
+   * Find by column or create if not found.
+   */
+  static async firstOrCreate(search, extra = {}) {
+    const existing = await this.findBy(Object.keys(search)[0], Object.values(search)[0]);
+    if (existing) return existing;
+    return this.create({ ...search, ...extra });
+  }
+
+  /**
+   * Update or create based on search criteria.
+   */
+  static async updateOrCreate(search, data) {
+    const existing = await this.where(search).first();
+    if (existing) {
+      await existing.update(data);
+      return existing;
+    }
+    return this.create({ ...search, ...data });
+  }
+
+  /**
+   * Count rows.
+   */
+  static async count(column = '*') {
+    const result = await this._db().count(`${column} as count`);
+    const row = Array.isArray(result) ? result[0] : result;
+    return Number(row?.count ?? 0);
+  }
+
+  /**
+   * Check whether any row matches the optional conditions.
+   */
+  static async exists(conditions = {}) {
+    let q = this._db();
+    if (Object.keys(conditions).length) q = q.where(conditions);
+    const result = await q.count('* as count');
+    const row = Array.isArray(result) ? result[0] : result;
+    return Number(row?.count ?? 0) > 0;
+  }
+
+  /**
+   * Bulk insert — returns number of rows inserted.
+   */
+  static async insert(rows) {
+    const now = new Date().toISOString();
+    const payload = rows.map(r => ({
+      ...this._applyDefaults(r),
+      ...(this.timestamps ? { created_at: now, updated_at: now } : {}),
+    }));
+    return this._db().insert(payload);
+  }
+
+  /**
+   * Delete rows by primary key.
+   */
+  static async destroy(...ids) {
+    return this._db().whereIn(this.primaryKey, ids.flat()).delete();
+  }
+
+  /**
+   * Truncate the table.
+   */
+  static async truncate() {
+    return this._db().truncate();
+  }
+
+  // ─── Query Builder entry points ───────────────────────────────────────────
+
+  static where(column, operatorOrValue, value) {
+    const qb = new QueryBuilder(this._db(), this);
+    return qb.where(column, operatorOrValue, value);
+  }
+
+  static whereIn(column, values) {
+    return new QueryBuilder(this._db(), this).whereIn(column, values);
+  }
+
+  static whereNull(column) {
+    return new QueryBuilder(this._db(), this).whereNull(column);
+  }
+
+  static whereNotNull(column) {
+    return new QueryBuilder(this._db(), this).whereNotNull(column);
+  }
+
+  static orderBy(column, dir = 'asc') {
+    return new QueryBuilder(this._db(), this).orderBy(column, dir);
+  }
+
+  static latest(column = 'created_at') {
+    return new QueryBuilder(this._db(), this).latest(column);
+  }
+
+  static oldest(column = 'created_at') {
+    return new QueryBuilder(this._db(), this).oldest(column);
+  }
+
+  static limit(n) {
+    return new QueryBuilder(this._db(), this).limit(n);
+  }
+
+  static select(...cols) {
+    return new QueryBuilder(this._db(), this).select(...cols);
+  }
+
+  /**
+   * Raw query builder — escape hatch.
+   */
+  static query() {
+    return new QueryBuilder(this._db(), this);
+  }
+
+  /**
+   * Paginate static shorthand.
+   */
+  static async paginate(page = 1, perPage = 15) {
+    const offset = (page - 1) * perPage;
+    const total  = await this.count();
+    const rows   = await this._db().limit(perPage).offset(offset);
+    return {
+      data:     rows.map(r => this._hydrate(r)),
+      total,
+      page:     Number(page),
+      perPage,
+      lastPage: Math.ceil(total / perPage),
+    };
+  }
+
+  // ─── Instance methods ─────────────────────────────────────────────────────
+
+  constructor(attributes = {}) {
+    Object.assign(this, attributes);
+    this._original  = { ...attributes };
+    this._isDirty   = false;
+  }
+
+  /**
+   * Persist changes to this instance back to the database.
+   */
+  async update(data = {}) {
+    const now = new Date().toISOString();
+    const payload = {
+      ...data,
+      ...(this.constructor.timestamps ? { updated_at: now } : {}),
+    };
+
+    await this.constructor._db()
+      .where(this.constructor.primaryKey, this[this.constructor.primaryKey])
+      .update(payload);
+
+    Object.assign(this, payload);
+    return this;
+  }
+
+  /**
+   * Save any changes made directly to this instance's properties.
+   */
+  async save() {
+    const dirty = this._getDirty();
+    if (!Object.keys(dirty).length) return this;
+    return this.update(dirty);
+  }
+
+  /**
+   * Delete this row from the database.
+   */
+  async delete() {
+    await this.constructor._db()
+      .where(this.constructor.primaryKey, this[this.constructor.primaryKey])
+      .delete();
+    return this;
+  }
+
+  /**
+   * Reload this instance's attributes from the database.
+   */
+  async refresh() {
+    const fresh = await this.constructor.find(this[this.constructor.primaryKey]);
+    if (fresh) Object.assign(this, fresh);
+    return this;
+  }
+
+  /**
+   * Return a plain object representation.
+   */
+  toJSON() {
+    const obj = {};
+    for (const key of Object.keys(this)) {
+      if (!key.startsWith('_')) obj[key] = this[key];
+    }
+    return obj;
+  }
+
+  /**
+   * Check whether this instance has been persisted.
+   */
+  get isNew() {
+    return !this[this.constructor.primaryKey];
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  static _db() {
+    const db = DatabaseManager.connection(this.connection || null);
+    return db(this.table);
+  }
+
+  static _hydrate(row) {
+    return new this(row);
+  }
+
+  static _applyDefaults(data) {
+    const result = { ...data };
+    for (const [key, field] of Object.entries(this.fields)) {
+      if (!(key in result) && field.default !== undefined) {
+        result[key] = typeof field.default === 'function'
+          ? field.default()
+          : field.default;
+      }
+    }
+    return result;
+  }
+
+  static _defaultTable() {
+    const name = this.name.toLowerCase();
+    if (name.endsWith('y') && !['ay','ey','iy','oy','uy'].some(s => name.endsWith(s)))
+      return name.slice(0, -1) + 'ies';
+    if (/(?:s|sh|ch|x|z)$/.test(name)) return name + 'es';
+    return name + 's';
+  }
+
+  _getDirty() {
+    const dirty = {};
+    for (const key of Object.keys(this)) {
+      if (!key.startsWith('_') && this[key] !== this._original[key]) {
+        dirty[key] = this[key];
+      }
+    }
+    return dirty;
+  }
+}
+
+module.exports = Model;

package/src/orm/query/QueryBuilder.js

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * QueryBuilder
+ *
+ * Fluent query builder for Millas ORM.
+ * Wraps a knex query builder instance and adds result casting.
+ *
+ * Never instantiated directly — accessed via Model methods:
+ *   User.where('active', true).orderBy('name').limit(10).get()
+ */
+class QueryBuilder {
+  constructor(knexQuery, ModelClass) {
+    this._query = knexQuery;
+    this._model = ModelClass;
+  }
+
+  // ─── WHERE ────────────────────────────────────────────────────────────────
+
+  where(column, operatorOrValue, value) {
+    if (typeof column === 'object') {
+      this._query = this._query.where(column);
+    } else if (value !== undefined) {
+      this._query = this._query.where(column, operatorOrValue, value);
+    } else {
+      this._query = this._query.where(column, operatorOrValue);
+    }
+    return this;
+  }
+
+  orWhere(column, operatorOrValue, value) {
+    if (value !== undefined) {
+      this._query = this._query.orWhere(column, operatorOrValue, value);
+    } else {
+      this._query = this._query.orWhere(column, operatorOrValue);
+    }
+    return this;
+  }
+
+  whereNull(column)    { this._query = this._query.whereNull(column);    return this; }
+  whereNotNull(column) { this._query = this._query.whereNotNull(column); return this; }
+
+  whereIn(column, values) {
+    this._query = this._query.whereIn(column, values);
+    return this;
+  }
+
+  whereNotIn(column, values) {
+    this._query = this._query.whereNotIn(column, values);
+    return this;
+  }
+
+  whereBetween(column, [min, max]) {
+    this._query = this._query.whereBetween(column, [min, max]);
+    return this;
+  }
+
+  whereLike(column, pattern) {
+    this._query = this._query.whereLike(column, pattern);
+    return this;
+  }
+
+  // ─── ORDER / LIMIT / OFFSET ───────────────────────────────────────────────
+
+  orderBy(column, direction = 'asc') {
+    this._query = this._query.orderBy(column, direction);
+    return this;
+  }
+
+  latest(column = 'created_at') {
+    return this.orderBy(column, 'desc');
+  }
+
+  oldest(column = 'created_at') {
+    return this.orderBy(column, 'asc');
+  }
+
+  limit(n)  { this._query = this._query.limit(n);  return this; }
+  offset(n) { this._query = this._query.offset(n); return this; }
+  skip(n)   { return this.offset(n); }
+  take(n)   { return this.limit(n); }
+
+  // ─── SELECT ───────────────────────────────────────────────────────────────
+
+  select(...columns) {
+    this._query = this._query.select(...columns);
+    return this;
+  }
+
+  // ─── EXECUTION ────────────────────────────────────────────────────────────
+
+  /**
+   * Fetch all matching rows — returns array of model instances.
+   */
+  async get() {
+    const rows = await this._query;
+    return rows.map(r => this._model._hydrate(r));
+  }
+
+  /**
+   * Fetch the first matching row — returns a model instance or null.
+   */
+  async first() {
+    const row = await this._query.first();
+    return row ? this._model._hydrate(row) : null;
+  }
+
+  /**
+   * Fetch by primary key — throws if not found.
+   */
+  async firstOrFail(message) {
+    const result = await this.first();
+    if (!result) {
+      const HttpError = require('../../errors/HttpError');
+      throw new HttpError(404, message || `${this._model.name} not found`);
+    }
+    return result;
+  }
+
+  /**
+   * Count matching rows.
+   */
+  async count(column = '*') {
+    const result = await this._query.count(`${column} as count`);
+    const row = Array.isArray(result) ? result[0] : result;
+    return Number(row?.count ?? 0);
+  }
+
+  /**
+   * Check whether any rows match.
+   */
+  async exists() {
+    return (await this.count()) > 0;
+  }
+
+  /**
+   * Pluck a single column as a flat array.
+   */
+  async pluck(column) {
+    const rows = await this._query;
+    return rows.map(r => r[column]);
+  }
+
+  /**
+   * Paginate results.
+   * Returns { data, total, page, perPage, lastPage }
+   */
+  async paginate(page = 1, perPage = 15) {
+    const offset = (page - 1) * perPage;
+
+    // Clone for count without limit/offset
+    const total = await this._model
+      .query()
+      .where(this._getWhereBindings())
+      .count();
+
+    const rows = await this._query.clone().limit(perPage).offset(offset).select('*');
+
+    return {
+      data:     rows.map(r => this._model._hydrate(r)),
+      total,
+      page:     Number(page),
+      perPage,
+      lastPage: Math.ceil(total / perPage),
+    };
+  }
+
+  /**
+   * Update matching rows.
+   */
+  async update(data) {
+    return this._query.update({ ...data, updated_at: new Date().toISOString() });
+  }
+
+  /**
+   * Delete matching rows.
+   */
+  async delete() {
+    return this._query.delete();
+  }
+
+  /**
+   * Raw underlying knex query (escape hatch).
+   */
+  toSQL() {
+    return this._query.toSQL();
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  _getWhereBindings() {
+    // Lightweight — used for paginate count clone
+    return {};
+  }
+}
+
+module.exports = QueryBuilder;

package/src/providers/AdminServiceProvider.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const ServiceProvider = require('./ServiceProvider');
+const Admin           = require('../admin/Admin');
+
+/**
+ * AdminServiceProvider
+ *
+ * Registers the Admin singleton and exposes it in the container.
+ *
+ * Add to bootstrap/app.js:
+ *   app.providers([..., AdminServiceProvider])
+ *
+ * Then register resources and mount:
+ *   Admin.register(UserResource);
+ *   Admin.mount(route, expressApp);
+ */
+class AdminServiceProvider extends ServiceProvider {
+  register(container) {
+    container.instance('Admin',         Admin);
+    container.instance('AdminResource', require('../admin/resources/AdminResource').AdminResource);
+    container.instance('AdminField',    require('../admin/resources/AdminResource').AdminField);
+    container.instance('AdminFilter',   require('../admin/resources/AdminResource').AdminFilter);
+  }
+
+  async boot(container) {
+    let adminConfig = {};
+    try {
+      adminConfig = require(process.cwd() + '/config/admin');
+    } catch { /* config is optional */ }
+
+    Admin.configure({
+      prefix: adminConfig.prefix || '/admin',
+      title:  adminConfig.title  || process.env.APP_NAME || 'Millas Admin',
+      ...adminConfig,
+    });
+  }
+}
+
+module.exports = AdminServiceProvider;

package/src/providers/AuthServiceProvider.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const ServiceProvider = require('./ServiceProvider');
+const Auth            = require('../auth/Auth');
+const AuthMiddleware  = require('../auth/AuthMiddleware');
+const RoleMiddleware  = require('../auth/RoleMiddleware');
+
+/**
+ * AuthServiceProvider
+ *
+ * Configures the Auth facade and registers auth-related
+ * bindings and middleware aliases.
+ *
+ * Add to bootstrap/app.js:
+ *   app.providers([DatabaseServiceProvider, AuthServiceProvider, AppServiceProvider])
+ */
+class AuthServiceProvider extends ServiceProvider {
+  register(container) {
+    container.instance('Auth',            Auth);
+    container.instance('AuthMiddleware',  AuthMiddleware);
+  }
+
+  async boot(container, app) {
+    // Load auth config
+    let authConfig;
+    try {
+      authConfig = require(process.cwd() + '/config/auth');
+    } catch {
+      authConfig = {
+        default: 'jwt',
+        guards:  { jwt: { driver: 'jwt', secret: process.env.APP_KEY || 'dev-secret', expiresIn: '7d' } },
+      };
+    }
+
+    // Load the User model if available
+    let UserModel = null;
+    try {
+      UserModel = require(process.cwd() + '/app/models/User');
+    } catch { /* User model optional at boot */ }
+
+    // Configure the Auth singleton
+    Auth.configure(authConfig, UserModel);
+
+    // Register 'auth' middleware alias with the real JWT implementation
+    if (app && app.mwRegistry) {
+      app.mwRegistry.register('auth',  AuthMiddleware);
+      app.mwRegistry.register('role',  new RoleMiddleware([]));
+      app.mwRegistry.register('admin', new RoleMiddleware(['admin']));
+    }
+  }
+}
+
+module.exports = AuthServiceProvider;