millas 0.2.11 → 0.2.12-beta-1

package/src/middleware/MiddlewarePipeline.js

@@ -1,93 +1,56 @@
 'use strict';
 
+const MillasRequest      = require('../http/MillasRequest');
+const RequestContext     = require('../http/RequestContext');
+const MillasResponse     = require('../http/MillasResponse');
+const ResponseDispatcher = require('../http/ResponseDispatcher');
+
 /**
  * MiddlewarePipeline
  *
- * Composes an ordered list of middleware handlers into a single
- * Express-compatible function. Used internally by the Router.
- *
- * Each handler can be:
- *   - A Middleware subclass (instantiated automatically)
- *   - An already-instantiated Middleware object
- *   - A raw Express function (req, res, next) => {}
+ * Runs an ordered list of middleware instances against a request.
+ * Used for programmatic pipelines outside of the router (e.g. queue webhooks).
  *
- * Usage (internal):
- *   const pipeline = new MiddlewarePipeline([AuthMiddleware, LogMiddleware]);
- *   app.use(pipeline.compose());
+ * Each middleware receives a RequestContext and a next() function.
  */
 class MiddlewarePipeline {
-  constructor(handlers = []) {
-    this._handlers = handlers;
-  }
-
-  /**
-   * Add a handler to the end of the pipeline.
-   */
-  pipe(handler) {
-    this._handlers.push(handler);
-    return this;
+  constructor(middlewares = []) {
+    this._middlewares = middlewares;
   }
 
-  /**
-   * Add a handler to the beginning of the pipeline.
-   */
-  prepend(handler) {
-    this._handlers.unshift(handler);
+  add(middleware) {
+    this._middlewares.push(middleware);
     return this;
   }
 
   /**
-   * Compose all handlers into a single (req, res, next) function.
+   * Run the pipeline against an Express req/res.
+   * @param {object} expressReq
+   * @param {object} expressRes
+   * @param {object|null} container
    */
-  compose() {
-    const fns = this._handlers.map(h => this._resolve(h));
+  async run(expressReq, expressRes, container = null) {
+    const millaReq = new MillasRequest(expressReq);
+    const ctx      = new RequestContext(millaReq, container);
 
-    return function pipeline(req, res, next) {
-      let index = 0;
+    const dispatch = async (index) => {
+      if (index >= this._middlewares.length) return null;
 
-      function dispatch(i) {
-        if (i >= fns.length) return next();
-        const fn = fns[i];
+      const mw   = this._middlewares[index];
+      const next = () => dispatch(index + 1);
 
-        try {
-          const result = fn(req, res, (err) => {
-            if (err) return next(err);
-            dispatch(i + 1);
-          });
-          // Handle async middleware that returns a Promise
-          if (result && typeof result.catch === 'function') {
-            result.catch(next);
-          }
-        } catch (err) {
-          next(err);
-        }
-      }
+      const instance = typeof mw === 'function' && mw.prototype?.handle
+        ? new mw()
+        : mw;
 
-      dispatch(0);
+      return instance.handle(ctx, next);
     };
-  }
-
-  /**
-   * Resolve a handler to a plain (req, res, next) => {} function.
-   */
-  _resolve(handler) {
-    // Raw Express function
-    if (typeof handler === 'function' && !(handler.prototype instanceof require('./Middleware'))) {
-      return handler;
-    }
 
-    // Middleware class (not yet instantiated)
-    if (typeof handler === 'function' && handler.prototype instanceof require('./Middleware')) {
-      const instance = new handler();
-      return (req, res, next) => instance.handle(req, res, next);
-    }
+    const response = await dispatch(0);
 
-    // Instantiated Middleware object
-    if (handler && typeof handler.handle === 'function') {
-      return (req, res, next) => handler.handle(req, res, next);
+    if (response && MillasResponse.isResponse(response) && !expressRes.headersSent) {
+      ResponseDispatcher.dispatch(response, expressRes);
     }
-
-    throw new Error(`Invalid middleware: ${handler}. Must be a Middleware class, instance, or function.`);
   }
 }
 

package/src/middleware/MiddlewareRegistry.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * MiddlewareRegistry
+ *
+ * Maps string aliases → Millas middleware classes or instances.
+ * Resolution produces adapter-native handler functions via the adapter,
+ * so this class has zero knowledge of Express (or any HTTP engine).
+ *
+ * The adapter is injected at resolution time (not construction time)
+ * so the registry can be built before the adapter exists.
+ */
+class MiddlewareRegistry {
+  constructor() {
+    this._map = {};
+  }
+
+  /**
+   * Register a middleware alias.
+   *
+   *   registry.register('auth',     AuthMiddleware)
+   *   registry.register('throttle', new ThrottleMiddleware({ max: 60 }))
+   */
+  register(alias, handler) {
+    this._map[alias] = handler;
+    return this;
+  }
+
+  /**
+   * Resolve a middleware alias or class/instance into an adapter-native handler.
+   *
+   * @param {string|Function|object} aliasOrFn
+   * @param {import('../http/adapters/HttpAdapter')} adapter
+   * @param {object|null} container
+   * @returns {Function}  adapter-native handler
+   */
+  resolve(aliasOrFn, adapter, container = null) {
+    const Handler = typeof aliasOrFn === 'string'
+      ? this._map[aliasOrFn]
+      : aliasOrFn;
+
+    if (!Handler) {
+      throw new Error(`Middleware "${aliasOrFn}" is not registered.`);
+    }
+
+    return this._wrap(Handler, adapter, container);
+  }
+
+  /**
+   * Resolve all aliases in a list.
+   */
+  resolveAll(list = [], adapter, container = null) {
+    return list.map(m => this.resolve(m, adapter, container));
+  }
+
+  /**
+   * Return a no-op passthrough handler for the given adapter.
+   * Used when a middleware alias is missing but should not crash the app.
+   */
+  resolvePassthrough(adapter) {
+    // Adapter-agnostic: return a function matching the native signature
+    // by asking the adapter to wrap a no-op middleware instance.
+    return adapter.wrapMiddleware({
+      handle: (_ctx, next) => next(),
+    }, null);
+  }
+
+  has(alias) {
+    return Object.prototype.hasOwnProperty.call(this._map, alias);
+  }
+
+  all() {
+    return { ...this._map };
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────────
+
+  _wrap(Handler, adapter, container) {
+    // Pre-instantiated Millas middleware object with handle()
+    if (
+      typeof Handler === 'object' &&
+      Handler !== null &&
+      typeof Handler.handle === 'function'
+    ) {
+      return adapter.wrapMiddleware(Handler, container);
+    }
+
+    // Millas middleware class (handle on prototype)
+    if (
+      typeof Handler === 'function' &&
+      Handler.prototype &&
+      typeof Handler.prototype.handle === 'function'
+    ) {
+      return adapter.wrapMiddleware(new Handler(), container);
+    }
+
+    // Raw adapter-native function — pass through as-is (escape hatch)
+    if (typeof Handler === 'function') {
+      return Handler;
+    }
+
+    throw new Error('Middleware must be a function or a class with handle().');
+  }
+}
+
+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,
     });