millas 0.1.0

package/src/controller/Controller.js

@@ -0,0 +1,367 @@
+'use strict';
+
+const HttpError = require('../errors/HttpError');
+
+/**
+ * Controller
+ *
+ * Base class for all Millas controllers.
+ *
+ * Provides:
+ *   - Response helpers  : this.ok(), this.created(), this.noContent(),
+ *                         this.badRequest(), this.unauthorized(),
+ *                         this.forbidden(), this.notFound(), this.json()
+ *   - Request helpers   : this.input(), this.param(), this.query(), this.all()
+ *   - Validation        : this.validate()
+ *   - Pagination helper : this.paginate()
+ *   - Error throwing    : this.abort()
+ *
+ * Usage:
+ *   class UserController extends Controller {
+ *     async index(req, res) {
+ *       return this.ok(res, { users: [] });
+ *     }
+ *   }
+ */
+class Controller {
+
+  // ─── Response Helpers ────────────────────────────────────────────────────────
+
+  /**
+   * 200 OK
+   * @param {object} res
+   * @param {*} data
+   */
+  ok(res, data = null) {
+    return res.status(200).json(this._envelope(200, data));
+  }
+
+  /**
+   * 201 Created
+   */
+  created(res, data = null) {
+    return res.status(201).json(this._envelope(201, data));
+  }
+
+  /**
+   * 204 No Content
+   */
+  noContent(res) {
+    return res.status(204).send();
+  }
+
+  /**
+   * 200 with a custom JSON payload (no envelope)
+   */
+  json(res, data, status = 200) {
+    return res.status(status).json(data);
+  }
+
+  /**
+   * 400 Bad Request
+   */
+  badRequest(res, message = 'Bad Request', errors = null) {
+    return res.status(400).json({
+      error:   'Bad Request',
+      message,
+      status:  400,
+      ...(errors && { errors }),
+    });
+  }
+
+  /**
+   * 401 Unauthorized
+   */
+  unauthorized(res, message = 'Unauthorized') {
+    return res.status(401).json({ error: 'Unauthorized', message, status: 401 });
+  }
+
+  /**
+   * 403 Forbidden
+   */
+  forbidden(res, message = 'Forbidden') {
+    return res.status(403).json({ error: 'Forbidden', message, status: 403 });
+  }
+
+  /**
+   * 404 Not Found
+   */
+  notFound(res, message = 'Not Found') {
+    return res.status(404).json({ error: 'Not Found', message, status: 404 });
+  }
+
+  /**
+   * 422 Unprocessable Entity — validation failed
+   */
+  unprocessable(res, errors) {
+    return res.status(422).json({
+      error:   'Unprocessable Entity',
+      message: 'Validation failed',
+      status:  422,
+      errors,
+    });
+  }
+
+  /**
+   * 500 Internal Server Error
+   */
+  serverError(res, message = 'Internal Server Error') {
+    return res.status(500).json({ error: 'Internal Server Error', message, status: 500 });
+  }
+
+  // ─── Abort (throw HttpError) ─────────────────────────────────────────────────
+
+  /**
+   * Throw an HTTP error — caught by the Router error handler.
+   *
+   * this.abort(404, 'User not found')
+   * this.abort(403)
+   */
+  abort(status, message) {
+    throw new HttpError(status, message);
+  }
+
+  // ─── Request Helpers ─────────────────────────────────────────────────────────
+
+  /**
+   * Get a value from req.body, req.query, or req.params — in that order.
+   * Falls back to defaultValue if not found.
+   *
+   * this.input(req, 'email')
+   * this.input(req, 'page', 1)
+   */
+  input(req, key, defaultValue = null) {
+    if (key === undefined) return this.all(req);
+    const value =
+      (req.body   && req.body[key]   !== undefined ? req.body[key]   : undefined) ??
+      (req.query  && req.query[key]  !== undefined ? req.query[key]  : undefined) ??
+      (req.params && req.params[key] !== undefined ? req.params[key] : undefined);
+    return value !== undefined ? value : defaultValue;
+  }
+
+  /**
+   * Get a URL parameter.  this.param(req, 'id')
+   */
+  param(req, key, defaultValue = null) {
+    return req.params?.[key] ?? defaultValue;
+  }
+
+  /**
+   * Get a query string value.  this.query(req, 'page', 1)
+   */
+  query(req, key, defaultValue = null) {
+    if (key === undefined) return req.query || {};
+    return req.query?.[key] ?? defaultValue;
+  }
+
+  /**
+   * Merge body + query + params into one flat object.
+   */
+  all(req) {
+    return {
+      ...req.params,
+      ...req.query,
+      ...req.body,
+    };
+  }
+
+  /**
+   * Return only the specified keys from the request.
+   *
+   * this.only(req, ['name', 'email'])
+   */
+  only(req, keys = []) {
+    const all = this.all(req);
+    return keys.reduce((acc, k) => {
+      if (k in all) acc[k] = all[k];
+      return acc;
+    }, {});
+  }
+
+  /**
+   * Return all request data except the specified keys.
+   *
+   * this.except(req, ['password', 'token'])
+   */
+  except(req, keys = []) {
+    const all = this.all(req);
+    return Object.fromEntries(
+      Object.entries(all).filter(([k]) => !keys.includes(k))
+    );
+  }
+
+  // ─── Validation ──────────────────────────────────────────────────────────────
+
+  /**
+   * Validate request data against a set of rules.
+   * Throws a 422 HttpError on failure (caught by the router).
+   *
+   * const data = await this.validate(req, {
+   *   name:  'required|string|min:2|max:100',
+   *   email: 'required|email',
+   *   age:   'optional|number|min:0',
+   * });
+   *
+   * On success returns the validated + sanitised data object.
+   */
+  async validate(req, rules) {
+    const data   = this.all(req);
+    const errors = {};
+
+    for (const [field, ruleString] of Object.entries(rules)) {
+      const fieldRules = ruleString.split('|').map(r => r.trim());
+      const value      = data[field];
+      const fieldErrors = [];
+
+      for (const rule of fieldRules) {
+        const [ruleName, ruleArg] = rule.split(':');
+        const err = this._applyRule(field, value, ruleName, ruleArg);
+        if (err) fieldErrors.push(err);
+      }
+
+      if (fieldErrors.length) errors[field] = fieldErrors;
+    }
+
+    if (Object.keys(errors).length > 0) {
+      throw new HttpError(422, 'Validation failed', errors);
+    }
+
+    // Return only the validated fields
+    const validated = {};
+    for (const field of Object.keys(rules)) {
+      if (data[field] !== undefined) validated[field] = data[field];
+    }
+    return validated;
+  }
+
+  _applyRule(field, value, rule, arg) {
+    const isEmpty = value === undefined || value === null || value === '';
+
+    switch (rule) {
+      case 'required':
+        if (isEmpty) return `${field} is required`;
+        break;
+
+      case 'optional':
+        if (isEmpty) return null; // skip further checks if optional and empty
+        break;
+
+      case 'string':
+        if (!isEmpty && typeof value !== 'string')
+          return `${field} must be a string`;
+        break;
+
+      case 'number':
+        if (!isEmpty && (isNaN(Number(value))))
+          return `${field} must be a number`;
+        break;
+
+      case 'boolean':
+        if (!isEmpty && !['true', 'false', true, false, '1', '0', 1, 0].includes(value))
+          return `${field} must be a boolean`;
+        break;
+
+      case 'email': {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        if (!isEmpty && !emailRegex.test(value))
+          return `${field} must be a valid email address`;
+        break;
+      }
+
+      case 'min':
+        if (!isEmpty) {
+          if (typeof value === 'string' && value.length < Number(arg))
+            return `${field} must be at least ${arg} characters`;
+          if (typeof value === 'number' && value < Number(arg))
+            return `${field} must be at least ${arg}`;
+        }
+        break;
+
+      case 'max':
+        if (!isEmpty) {
+          if (typeof value === 'string' && value.length > Number(arg))
+            return `${field} must not exceed ${arg} characters`;
+          if (typeof value === 'number' && value > Number(arg))
+            return `${field} must not exceed ${arg}`;
+        }
+        break;
+
+      case 'in': {
+        const allowed = arg.split(',');
+        if (!isEmpty && !allowed.includes(String(value)))
+          return `${field} must be one of: ${allowed.join(', ')}`;
+        break;
+      }
+
+      case 'alpha':
+        if (!isEmpty && !/^[a-zA-Z]+$/.test(value))
+          return `${field} must contain only letters`;
+        break;
+
+      case 'alphanumeric':
+        if (!isEmpty && !/^[a-zA-Z0-9]+$/.test(value))
+          return `${field} must contain only letters and numbers`;
+        break;
+
+      case 'url':
+        try {
+          if (!isEmpty) new URL(value);
+        } catch {
+          return `${field} must be a valid URL`;
+        }
+        break;
+
+      case 'confirmed': {
+        // Expects a matching field named `${field}_confirmation` in the request
+        // We store the raw req data on the instance during validate()
+        break;
+      }
+
+      default:
+        // Unknown rule — silently ignore (extensible in future)
+        break;
+    }
+
+    return null;
+  }
+
+  // ─── Pagination Helper ───────────────────────────────────────────────────────
+
+  /**
+   * Build a pagination envelope for list responses.
+   *
+   * return this.paginate(res, {
+   *   data:    users,
+   *   total:   100,
+   *   page:    2,
+   *   perPage: 15,
+   * });
+   */
+  paginate(res, { data, total, page = 1, perPage = 15 }) {
+    const lastPage = Math.ceil(total / perPage);
+    return res.status(200).json({
+      data,
+      meta: {
+        total,
+        per_page:    perPage,
+        current_page: Number(page),
+        last_page:   lastPage,
+        from:        (page - 1) * perPage + 1,
+        to:          Math.min(page * perPage, total),
+      },
+    });
+  }
+
+  // ─── Internal ────────────────────────────────────────────────────────────────
+
+  _envelope(status, data) {
+    if (data === null) return { status };
+    // If data already has a recognised top-level shape, return as-is
+    if (typeof data === 'object' && !Array.isArray(data) && ('data' in data || 'message' in data)) {
+      return { status, ...data };
+    }
+    return { status, data };
+  }
+}
+
+module.exports = Controller;

package/src/errors/HttpError.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * HttpError
+ *
+ * A structured error that carries an HTTP status code.
+ * Thrown by Controller.abort() and the validation system.
+ * Caught automatically by the Router's global error handler.
+ *
+ * Usage:
+ *   throw new HttpError(404, 'User not found')
+ *   throw new HttpError(422, 'Validation failed', { email: ['email is required'] })
+ */
+class HttpError extends Error {
+  /**
+   * @param {number} status   HTTP status code
+   * @param {string} message  Human-readable message
+   * @param {object} errors   Optional field-level errors (for validation)
+   */
+  constructor(status = 500, message = 'Internal Server Error', errors = null) {
+    super(message);
+    this.name       = 'HttpError';
+    this.status     = status;
+    this.statusCode = status;
+    this.errors     = errors;
+  }
+}
+
+module.exports = HttpError;

package/src/events/Event.js

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * Event
+ *
+ * Base class for all Millas events.
+ *
+ * Usage:
+ *   class UserRegistered extends Event {
+ *     constructor(user) {
+ *       super();
+ *       this.user      = user;
+ *       this.timestamp = new Date();
+ *     }
+ *   }
+ *
+ *   // Fire the event
+ *   await emit(new UserRegistered(user));
+ */
+class Event {
+  constructor() {
+    this._name      = this.constructor.name;
+    this._timestamp = new Date().toISOString();
+    this._stopped   = false;
+  }
+
+  /**
+   * Stop event propagation — subsequent listeners won't be called.
+   */
+  stopPropagation() {
+    this._stopped = true;
+  }
+
+  get name()      { return this._name; }
+  get timestamp() { return this._timestamp; }
+  get stopped()   { return this._stopped; }
+}
+
+module.exports = Event;

package/src/events/EventEmitter.js

@@ -0,0 +1,151 @@
+'use strict';
+
+/**
+ * EventEmitter — Millas event bus.
+ */
+class EventEmitter {
+  constructor() {
+    this._listeners = new Map();
+    this._wildcards = [];
+    this._queue     = null;
+  }
+
+  listen(event, listeners) {
+    const name = this._name(event);
+    if (!this._listeners.has(name)) this._listeners.set(name, []);
+    const list = Array.isArray(listeners) ? listeners : [listeners];
+    for (const l of list) this._listeners.get(name).push({ handler: l, once: false });
+    return this;
+  }
+
+  on(event, fn)    { return this.listen(event, fn); }
+
+  once(event, fn) {
+    const name = this._name(event);
+    if (!this._listeners.has(name)) this._listeners.set(name, []);
+    this._listeners.get(name).push({ handler: fn, once: true });
+    return this;
+  }
+
+  off(event, fn) {
+    const name = this._name(event);
+    if (!this._listeners.has(name)) return this;
+    this._listeners.set(name, this._listeners.get(name).filter(l => l.handler !== fn));
+    return this;
+  }
+
+  onWildcard(pattern, fn) {
+    const rx = new RegExp('^' + pattern.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$');
+    this._wildcards.push({ rx, handler: fn });
+    return this;
+  }
+
+  async emit(event, data = {}) {
+    let ev = event;
+    if (typeof event === 'string') {
+      const Ev = require('./Event');
+      ev = Object.assign(new Ev(), { _name: event, ...data });
+    }
+    const name    = ev._name || ev.constructor?.name || String(event);
+    const entries = [...(this._listeners.get(name) || [])];
+    const remove  = [];
+
+    for (const entry of entries) {
+      if (ev.stopped) break;
+      await this._invoke(entry.handler, ev);
+      if (entry.once) remove.push(entry);
+    }
+    if (remove.length) {
+      this._listeners.set(name, (this._listeners.get(name) || []).filter(l => !remove.includes(l)));
+    }
+
+    for (const { rx, handler } of this._wildcards) {
+      if (ev.stopped) break;
+      if (rx.test(name)) await this._invoke(handler, ev);
+    }
+    return ev;
+  }
+
+  emitAsync(event, data = {}) {
+    Promise.resolve(this.emit(event, data)).catch(err =>
+      console.error('[EventEmitter] Unhandled error:', err.message)
+    );
+  }
+
+  hasListeners(event) { return (this._listeners.get(this._name(event)) || []).length > 0; }
+  getListeners(event) { return (this._listeners.get(this._name(event)) || []).map(l => l.handler); }
+  removeAll(event)    { this._listeners.delete(this._name(event)); return this; }
+  flush()             { this._listeners.clear(); this._wildcards = []; return this; }
+  setQueue(queue)     { this._queue = queue; }
+
+  async _invoke(handler, event) {
+    // Listener class (has handle() on prototype)
+    if (typeof handler === 'function' && typeof handler.prototype?.handle === 'function') {
+      const inst = new handler();
+      if (handler.queue && this._queue) {
+        const Job = require('../queue/Job');
+        const q   = this._queue;
+        class LJob extends Job {
+          async handle()      { await inst.handle(event); }
+          async failed(e)     { if (typeof inst.failed === 'function') await inst.failed(event, e); }
+        }
+        LJob.queue = handler.queueName || 'default';
+        await q.push(new LJob());
+        return;
+      }
+      try   { await inst.handle(event); }
+      catch (e) {
+        if (typeof inst.failed === 'function') await inst.failed(event, e);
+        else throw e;
+      }
+      return;
+    }
+    // Instantiated listener object
+    if (handler && typeof handler === 'object' && typeof handler.handle === 'function') {
+      await handler.handle(event); return;
+    }
+    // Raw function
+    if (typeof handler === 'function') { await handler(event); return; }
+    throw new Error('Invalid listener: ' + handler);
+  }
+
+  _name(e) {
+    if (typeof e === 'string')   return e;
+    if (typeof e === 'function') return e.name;
+    return e?._name || e?.constructor?.name || String(e);
+  }
+}
+
+// ── Singleton ─────────────────────────────────────────────────────────────────
+const _inst = new EventEmitter();
+
+// Standalone emit function — IMPORTANT: does NOT use module.exports.emit
+// to avoid the circular reference where module.exports === _inst so
+// _inst.emit gets overwritten by the wrapper.
+async function emit(event, data) {
+  // Call the class method bound to _inst, bypassing any property overwrites
+  return EventEmitter.prototype.emit.call(_inst, event, data);
+}
+
+// Export a plain wrapper object (NOT the singleton itself) to prevent
+// module.exports.emit from writing back onto _inst.
+module.exports = {
+  // Proxy all EventEmitter instance methods to _inst
+  listen:      (...a) => _inst.listen(...a),
+  on:          (...a) => _inst.on(...a),
+  once:        (...a) => _inst.once(...a),
+  off:         (...a) => _inst.off(...a),
+  onWildcard:  (...a) => _inst.onWildcard(...a),
+  emit:        (...a) => EventEmitter.prototype.emit.call(_inst, ...a),
+  emitAsync:   (...a) => _inst.emitAsync(...a),
+  hasListeners:(...a) => _inst.hasListeners(...a),
+  getListeners:(...a) => _inst.getListeners(...a),
+  removeAll:   (...a) => _inst.removeAll(...a),
+  flush:       ()     => _inst.flush(),
+  setQueue:    (q)    => _inst.setQueue(q),
+  // Named exports
+  EventEmitter,
+  emit,
+  // Expose singleton for advanced use
+  _instance: _inst,
+};

package/src/events/Listener.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * Listener
+ *
+ * Base class for all event listeners.
+ *
+ * Usage:
+ *   class SendWelcomeEmail extends Listener {
+ *     static queue = true;  // run this listener via the queue (Phase 9)
+ *
+ *     async handle(event) {
+ *       await Mail.send({
+ *         to:       event.user.email,
+ *         subject:  'Welcome!',
+ *         template: 'welcome',
+ *         data:     { name: event.user.name },
+ *       });
+ *     }
+ *   }
+ *
+ * Register:
+ *   EventEmitter.listen(UserRegistered, [SendWelcomeEmail, NotifyAdmin]);
+ */
+class Listener {
+  /**
+   * Whether to run this listener via the queue.
+   * Set to true for slow operations (email, notifications, etc.)
+   */
+  static queue = false;
+
+  /**
+   * Handle the event.
+   * @param {Event} event
+   */
+  async handle(event) {
+    throw new Error(`${this.constructor.name} must implement handle(event)`);
+  }
+
+  /**
+   * Called when the listener fails.
+   */
+  async failed(event, error) {}
+}
+
+module.exports = Listener;

package/src/events/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const emitterModule = require('./EventEmitter');
+const EventEmitter  = emitterModule.EventEmitter
+  ? emitterModule                      // if default export is singleton
+  : emitterModule;
+const Event    = require('./Event');
+const Listener = require('./Listener');
+
+module.exports = {
+  EventEmitter: emitterModule,
+  Event,
+  Listener,
+  emit: emitterModule.emit,
+};