millas 0.2.11 → 0.2.12-beta

package/src/middleware/MiddlewareRegistry.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const MillasRequest      = require('../http/MillasRequest');
+const MillasResponse     = require('../http/MillasResponse');
+const ResponseDispatcher = require('../http/ResponseDispatcher');
+const RequestContext     = require('../http/RequestContext');
+
+/**
+ * MiddlewareRegistry
+ *
+ * Maps string aliases → middleware handler classes or functions.
+ * Resolves them into Express-compatible functions that wrap with MillasRequest.
+ */
+class MiddlewareRegistry {
+  constructor(container = null) {
+    this._map       = {};
+    this._container = container;
+  }
+
+  register(alias, handler) {
+    this._map[alias] = handler;
+    return this;
+  }
+
+  /**
+   * Resolve a middleware alias or function into an Express-compatible handler.
+   *
+   * Millas middleware (class with handle(req, next)):
+   *   - Receives MillasRequest
+   *   - Returns MillasResponse or calls next()
+   *   - Kernel dispatches the MillasResponse if returned
+   *
+   * Raw Express functions (legacy/escape hatch):
+   *   - Passed through as-is
+   */
+  resolve(aliasOrFn) {
+    // Raw function — check if it's a Millas middleware class or legacy Express fn
+    if (typeof aliasOrFn === 'function') {
+      return this._wrapHandler(aliasOrFn);
+    }
+
+    const Handler = this._map[aliasOrFn];
+    if (!Handler) {
+      throw new Error(`Middleware "${aliasOrFn}" is not registered.`);
+    }
+
+    return this._wrapHandler(Handler);
+  }
+
+  resolveAll(list = []) {
+    return list.map(m => this.resolve(m));
+  }
+
+  has(alias) {
+    return Object.prototype.hasOwnProperty.call(this._map, alias);
+  }
+
+  all() {
+    return { ...this._map }; }
+
+  // ─── Internal ──────────────────────────────────────────────────────────────
+
+  _wrapHandler(Handler) {
+    // Pre-instantiated Millas middleware object: { handle(req, next) }
+    if (typeof Handler === 'object' && Handler !== null &&
+        typeof Handler.handle === 'function') {
+      return this._buildMillasWrapper(Handler);
+    }
+
+    // Millas middleware class (has handle on prototype, not Express signature)
+    if (typeof Handler === 'function' &&
+        Handler.prototype &&
+        typeof Handler.prototype.handle === 'function') {
+      const instance = new Handler();
+      return this._buildMillasWrapper(instance);
+    }
+
+    // Legacy raw Express function: (req, res, next) => void
+    // Pass through unchanged — developers using old style still work
+    if (typeof Handler === 'function') {
+      return Handler;
+    }
+
+    throw new Error(`Middleware must be a function or a class with handle().`);
+  }
+
+  /**
+   * Build an Express-compatible function from a Millas middleware instance.
+   *
+   * The middleware's handle(req, next) is called with a MillasRequest.
+   * If it returns a MillasResponse, that response is dispatched immediately.
+   * If it calls next(), Express continues down the chain.
+   */
+  _buildMillasWrapper(instance) {
+    const container = this._container;
+
+    return (expressReq, expressRes, expressNext) => {
+      const millaReq = new MillasRequest(expressReq);
+      const ctx      = new RequestContext(millaReq, container);
+
+      const next = () => {
+        expressNext();
+        return undefined;
+      };
+
+      new Promise((resolve, reject) => {
+        try {
+          resolve(instance.handle(ctx, next));
+        } catch (err) {
+          reject(err);
+        }
+      })
+      .then(value => {
+        if (value !== undefined && value !== null && !expressRes.headersSent) {
+          const response = MillasResponse.isResponse(value)
+            ? value
+            : ResponseDispatcher.autoWrap(value);
+          ResponseDispatcher.dispatch(response, expressRes);
+        }
+      })
+      .catch(expressNext);
+    };
+  }
+}
+
+module.exports = MiddlewareRegistry;

package/src/middleware/ThrottleMiddleware.js

@@ -1,35 +1,28 @@
 'use strict';
 
-const Middleware = require('./Middleware');
+const Middleware     = require('./Middleware');
+const MillasResponse = require('../http/MillasResponse');
+const { jsonify }    = require('../http/helpers');
 
 /**
  * ThrottleMiddleware
  *
  * Simple in-memory rate limiter.
- * For production use, replace the store with a Redis-backed one (Phase 11).
- *
- * Register:
- *   middlewareRegistry.register('throttle', new ThrottleMiddleware({ max: 60, window: 60 }));
- *
- * Options:
- *   max     — max requests per window (default: 60)
- *   window  — window in seconds (default: 60)
- *   keyBy   — function(req) => string, defaults to IP
+ * Uses the Millas middleware signature: handle(req, next).
  */
 class ThrottleMiddleware extends Middleware {
   constructor(options = {}) {
     super();
     this.max    = options.max    || 60;
-    this.window = options.window || 60;       // seconds
+    this.window = options.window || 60;
     this.keyBy  = options.keyBy  || ((req) => req.ip || 'anonymous');
-    this._store = new Map();                   // { key: { count, resetAt } }
+    this._store = new Map();
   }
 
-  async handle(req, res, next) {
-    const key   = this.keyBy(req);
-    const now   = Date.now();
-
-    let record = this._store.get(key);
+  async handle(req, next) {
+    const key    = this.keyBy(req);
+    const now    = Date.now();
+    let   record = this._store.get(key);
 
     if (!record || now > record.resetAt) {
       record = { count: 0, resetAt: now + this.window * 1000 };
@@ -41,20 +34,23 @@ class ThrottleMiddleware extends Middleware {
     const remaining = Math.max(0, this.max - record.count);
     const resetIn   = Math.ceil((record.resetAt - now) / 1000);
 
-    res.setHeader('X-RateLimit-Limit',     String(this.max));
-    res.setHeader('X-RateLimit-Remaining', String(remaining));
-    res.setHeader('X-RateLimit-Reset',     String(Math.ceil(record.resetAt / 1000)));
+    // Rate limit headers — added to whatever response comes back
+    // We set them on the raw Express res since we don't have the final response yet.
+    // These headers will be present on all responses from throttled routes.
+    req.raw.res.setHeader('X-RateLimit-Limit',     String(this.max));
+    req.raw.res.setHeader('X-RateLimit-Remaining', String(remaining));
+    req.raw.res.setHeader('X-RateLimit-Reset',     String(Math.ceil(record.resetAt / 1000)));
 
     if (record.count > this.max) {
-      return res.status(429).json({
-        error:   'Too Many Requests',
-        message: `Rate limit exceeded. Try again in ${resetIn}s.`,
-        status:  429,
+      return jsonify({
+        error:      'Too Many Requests',
+        message:    `Rate limit exceeded. Try again in ${resetIn}s.`,
+        status:     429,
         retryAfter: resetIn,
-      });
+      }, { status: 429 });
     }
 
-    next();
+    return next();
   }
 }
 

package/src/orm/fields/index.js

@@ -1,128 +1,196 @@
 '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 }
+    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;
+    this._isForeignKey   = options._isForeignKey   ?? false;
+    this._isOneToOne     = options._isOneToOne     ?? false;
+    this._isManyToMany   = options._isManyToMany   ?? false;
+    this._fkModel        = options._fkModel        ?? null;
+    this._fkModelRef     = options._fkModelRef     ?? null;
+    this._fkToField      = options._fkToField      ?? 'id';
+    this._fkOnDelete     = options._fkOnDelete     ?? 'CASCADE';
+    this._fkRelatedName  = options._fkRelatedName  ?? null;
+    this._m2mThrough     = options._m2mThrough     ?? null;
   }
 
-  // ─── 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; }
+}
 
-  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; }
+function _makeModelRef(model) {
+  if (typeof model === 'function') return model;
+  if (model === 'self') return null;
+  return () => {
+    const path = require('path');
+    const modelsDir = path.join(process.cwd(), 'app', 'models');
+    try {
+      return require(path.join(modelsDir, model));
+    } catch {
+      try {
+        const fs = require('fs');
+        const files = fs.readdirSync(modelsDir);
+        const match = files.find(f =>
+          f.replace(/\.js$/, '').toLowerCase() === model.toLowerCase()
+        );
+        if (match) return require(path.join(modelsDir, match));
+      } catch {}
+      return null;
+    }
+  };
 }
 
 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
+   * ForeignKey — Django-style.
+   *
+   * Declares the integer column AND wires the BelongsTo relation automatically.
+   * No `static relations` block needed.
+   *
+   * Field name convention:
+   *   author    → accessor: book.author()   column: author_id
+   *   author_id → accessor: book.author()   column: author_id
+   *
+   * @param {string|Function} model        'Author' | () => Author | 'self'
+   * @param {object}  [opts]
+   * @param {boolean} [opts.nullable]      allow NULL (default: false)
+   * @param {string}  [opts.onDelete]      CASCADE|SET NULL|RESTRICT|PROTECT|DO_NOTHING (default: CASCADE)
+   * @param {string}  [opts.relatedName]   reverse accessor on target, e.g. 'books' → author.books()
+   *                                       pass '+' to suppress the reverse relation
+   * @param {string}  [opts.toField]       target column (default: 'id')
+   *
+   * @example
+   *   author:    fields.ForeignKey('Author', { onDelete: 'CASCADE', relatedName: 'books' })
+   *   editor:    fields.ForeignKey('User',   { nullable: true, onDelete: 'SET NULL' })
+   *   parent:    fields.ForeignKey('self',   { nullable: true, relatedName: 'children' })
+   */
+  ForeignKey(model, opts = {}) {
+    return new FieldDefinition('integer', {
+      unsigned:       true,
+      nullable:       opts.nullable     ?? false,
+      _isForeignKey:  true,
+      _fkModel:       model,
+      _fkModelRef:    _makeModelRef(model),
+      _fkToField:     opts.toField      ?? 'id',
+      _fkOnDelete:    opts.onDelete     ?? 'CASCADE',
+      _fkRelatedName: opts.relatedName  ?? null,
+    });
+  },
+
+  /**
+   * OneToOne — unique ForeignKey. Both directions wired automatically.
+   *
+   * @example
+   *   user: fields.OneToOne('User', { relatedName: 'profile' })
+   *   // profile.user() and user.profile() both work
    */
+  OneToOne(model, opts = {}) {
+    return new FieldDefinition('integer', {
+      unsigned:       true,
+      unique:         true,
+      nullable:       opts.nullable     ?? false,
+      _isForeignKey:  true,
+      _isOneToOne:    true,
+      _fkModel:       model,
+      _fkModelRef:    _makeModelRef(model),
+      _fkToField:     opts.toField      ?? 'id',
+      _fkOnDelete:    opts.onDelete     ?? 'CASCADE',
+      _fkRelatedName: opts.relatedName  ?? null,
+    });
+  },
+
+  /**
+   * ManyToMany — no DB column. Generates pivot table migration.
+   * Pivot table auto-named: sorted model names joined with underscore.
+   *
+   * @example
+   *   tags: fields.ManyToMany('Tag', { relatedName: 'courses' })
+   *   tags: fields.ManyToMany('Tag', { through: 'course_tags', relatedName: 'courses' })
+   */
+  ManyToMany(model, opts = {}) {
+    return new FieldDefinition('m2m', {
+      nullable:        true,
+      _isManyToMany:   true,
+      _fkModel:        model,
+      _fkModelRef:     _makeModelRef(model),
+      _fkRelatedName:  opts.relatedName ?? null,
+      _m2mThrough:     opts.through     ?? null,
+    });
+  },
+
+  /** Legacy — kept for backward compatibility. Prefer ForeignKey(). */
   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,
+      unsigned:   true,
+      nullable:   options.nullable ?? false,
       references: table ? { table, column: col } : null,
       ...options,
     });

package/src/orm/migration/ModelInspector.js

@@ -1,7 +1,8 @@
 'use strict';
 
-const fs   = require('fs-extra');
-const path = require('path');
+const fs        = require('fs-extra');
+const path      = require('path');
+const MillasLog = require('../../logger/internal');
 
 /**
  * ModelInspector
@@ -94,7 +95,10 @@ class ModelInspector {
         exported = require(fullPath);
       } catch (err) {
         // Skip files that fail to parse / have runtime errors
-        process.stderr.write(`  [makemigrations] Skipping ${file}: ${err.message}\n`);
+        // Log at WARN level — a skipped model is worth knowing about
+        // but shouldn't stop the command. Falls back silently if the
+        // logger hasn't been configured yet (e.g. bare CLI usage).
+        MillasLog.w('makemigrations', `Skipping ${file}: ${err.message}`);
         continue;
       }
 

package/src/orm/model/Model.js

@@ -412,7 +412,7 @@ class Model {
     return new QueryBuilder(this._db(), this).distinct(...cols);
   }
 
-  /** Start an eager-load chain. */
+  /** Start an eager-load chain. Relations inferred from fields are included automatically. */
   static with(...relations) {
     return new QueryBuilder(this._db(), this).with(...relations);
   }
@@ -461,15 +461,14 @@ class Model {
     Object.assign(this, attributes);
     this._original = { ...attributes };
 
-    // Attach lazy relation loaders as callable methods
-    const relations = this.constructor.relations || {};
+    // Use effective relations: explicit static relations PLUS those
+    // auto-inferred from ForeignKey / OneToOne / ManyToMany fields.
+    const relations = this.constructor._effectiveRelations();
+
     for (const [name, rel] of Object.entries(relations)) {
-      // Skip if already set by eager load
       if (!(name in this)) {
         this[name] = () => rel.load(this);
       }
-
-      // Attach pivot manager for BelongsToMany
       const BelongsToMany = require('../relations/BelongsToMany');
       if (rel instanceof BelongsToMany) {
         Object.assign(this[name], rel._pivotManager(this));
@@ -477,6 +476,97 @@ class Model {
     }
   }
 
+  /**
+   * Returns the merged relation map for this model class.
+   *
+   * Priority (highest → lowest):
+   *   1. Explicitly declared `static relations = {}`
+   *   2. Auto-inferred from ForeignKey / OneToOne / ManyToMany fields
+   *
+   * Result is cached per class after first call.
+   */
+  static _effectiveRelations() {
+    if (this._cachedRelations) return this._cachedRelations;
+
+    const BelongsTo     = require('../relations/BelongsTo');
+    const HasOne        = require('../relations/HasOne');
+    const BelongsToMany = require('../relations/BelongsToMany');
+
+    // Start with explicitly declared relations
+    const merged = { ...(this.relations || {}) };
+
+    for (const [fieldName, fieldDef] of Object.entries(this.fields || {})) {
+
+      // ── ForeignKey / OneToOne ────────────────────────────────────────────
+      if (fieldDef._isForeignKey) {
+        // Infer accessor name:
+        //   author_id  → author
+        //   author     → author  (column will be author_id in migration)
+        const accessorName = fieldName.endsWith('_id')
+          ? fieldName.slice(0, -3)
+          : fieldName;
+
+        // Don't overwrite an explicitly declared relation
+        if (!merged[accessorName]) {
+          const modelRef   = fieldDef._fkModelRef;
+          const toField    = fieldDef._fkToField || 'id';
+          const self       = this;
+
+          // self-referential: 'self' means this very model
+          const resolveModel = () => {
+            if (fieldDef._fkModel === 'self') return self;
+            const M = typeof modelRef === 'function' ? modelRef() : modelRef;
+            return M;
+          };
+
+          if (fieldDef._isOneToOne) {
+            // OneToOne: BelongsTo on the declaring side
+            merged[accessorName] = new BelongsTo(resolveModel, fieldName.endsWith('_id') ? fieldName : fieldName + '_id', toField);
+          } else {
+            merged[accessorName] = new BelongsTo(resolveModel, fieldName.endsWith('_id') ? fieldName : fieldName + '_id', toField);
+          }
+        }
+      }
+
+      // ── ManyToMany ────────────────────────────────────────────────────────
+      if (fieldDef._isManyToMany && !merged[fieldName]) {
+        const thisTableBase  = (this.table || this.name.toLowerCase()).replace(/s$/, '');
+        const modelRef       = fieldDef._fkModelRef;
+
+        const resolveRelated = () => {
+          const M = typeof modelRef === 'function' ? modelRef() : modelRef;
+          return M;
+        };
+
+        // Infer pivot table: sort both singular table names alphabetically
+        const relatedName   = typeof fieldDef._fkModel === 'string'
+          ? fieldDef._fkModel.toLowerCase().replace(/s$/, '')
+          : fieldName.replace(/s$/, '');
+
+        const pivotTable    = fieldDef._m2mThrough
+          || [thisTableBase, relatedName].sort().join('_') + 's';
+
+        const thisFk        = thisTableBase + '_id';
+        const relatedFk     = relatedName + '_id';
+
+        merged[fieldName] = new BelongsToMany(
+          resolveRelated,
+          pivotTable,
+          thisFk,
+          relatedFk,
+        );
+      }
+    }
+
+    this._cachedRelations = merged;
+    return merged;
+  }
+
+  /** Clear the cached relations (call if fields are modified at runtime). */
+  static _clearRelationCache() {
+    this._cachedRelations = null;
+  }
+
   /**
    * Persist changes to this instance.
    * @param {object} data