millas 0.2.11 → 0.2.12-beta

package/src/http/MillasResponse.js

@@ -0,0 +1,196 @@
+'use strict';
+
+/**
+ * MillasResponse
+ *
+ * An immutable value object representing an HTTP response.
+ * Nothing is written to the socket until ResponseDispatcher.dispatch() is called.
+ *
+ * Developers never instantiate this directly — use the helper functions:
+ *   jsonify(data, options)
+ *   view('template', data, options)
+ *   redirect('/path', options)
+ *   text('Hello', options)
+ *   file('/path/to/file')
+ *   empty(204)
+ *
+ * Route handlers return a MillasResponse (or a plain value that gets
+ * auto-wrapped). Middleware can inspect or modify the response before
+ * it reaches the dispatcher.
+ *
+ * Fluent mutation — each method returns a NEW MillasResponse:
+ *   return jsonify(user).status(201).header('X-Custom', 'value');
+ */
+class MillasResponse {
+  /**
+   * @param {object} options
+   * @param {string}  options.type     — 'json' | 'html' | 'text' | 'redirect' | 'file' | 'empty' | 'stream'
+   * @param {*}       options.body     — response body
+   * @param {number}  [options.status] — HTTP status code (default: 200)
+   * @param {object}  [options.headers]— additional headers
+   * @param {object}  [options.cookies]— cookies to set: { name: { value, options } }
+   */
+  constructor({ type, body, status = 200, headers = {}, cookies = {} } = {}) {
+    this._type    = type;
+    this._body    = body;
+    this._status  = status;
+    this._headers = { ...headers };
+    this._cookies = { ...cookies };
+
+    // Make immutable after construction
+    Object.freeze(this._headers);
+    Object.freeze(this._cookies);
+  }
+
+  // ─── Accessors ──────────────────────────────────────────────────────────────
+
+  get type()    { return this._type; }
+  get body()    { return this._body; }
+  get statusCode() { return this._status; }
+  get headers() { return this._headers; }
+  get cookies() { return this._cookies; }
+
+  // ─── Fluent builders (return new instance each time) ─────────────────────
+
+  /**
+   * Set the HTTP status code.
+   *   return jsonify(data).status(201)
+   */
+  status(code) {
+    return new MillasResponse({
+      type:    this._type,
+      body:    this._body,
+      status:  code,
+      headers: this._headers,
+      cookies: this._cookies,
+    });
+  }
+
+  /**
+   * Add or override a response header.
+   *   return jsonify(data).header('X-Custom-Id', '123')
+   */
+  header(name, value) {
+    return new MillasResponse({
+      type:    this._type,
+      body:    this._body,
+      status:  this._status,
+      headers: { ...this._headers, [name]: value },
+      cookies: this._cookies,
+    });
+  }
+
+  /**
+   * Add multiple headers at once.
+   *   return jsonify(data).withHeaders({ 'X-A': '1', 'X-B': '2' })
+   */
+  withHeaders(map = {}) {
+    return new MillasResponse({
+      type:    this._type,
+      body:    this._body,
+      status:  this._status,
+      headers: { ...this._headers, ...map },
+      cookies: this._cookies,
+    });
+  }
+
+  /**
+   * Set a cookie on the response.
+   *
+   *   return jsonify(data).cookie('token', value, { httpOnly: true, maxAge: 3600 })
+   */
+  cookie(name, value, options = {}) {
+    return new MillasResponse({
+      type:    this._type,
+      body:    this._body,
+      status:  this._status,
+      headers: this._headers,
+      cookies: { ...this._cookies, [name]: { value, options } },
+    });
+  }
+
+  /**
+   * Clear a cookie.
+   *   return jsonify(data).clearCookie('session')
+   */
+  clearCookie(name, options = {}) {
+    return this.cookie(name, '', { ...options, maxAge: 0, expires: new Date(0) });
+  }
+
+  // ─── Static factories ─────────────────────────────────────────────────────
+
+  /** JSON response */
+  static json(data, { status = 200, headers = {} } = {}) {
+    return new MillasResponse({
+      type: 'json',
+      body: data,
+      status,
+      headers: { 'Content-Type': 'application/json', ...headers },
+    });
+  }
+
+  /** HTML response */
+  static html(html, { status = 200, headers = {} } = {}) {
+    return new MillasResponse({
+      type: 'html',
+      body: html,
+      status,
+      headers: { 'Content-Type': 'text/html; charset=utf-8', ...headers },
+    });
+  }
+
+  /** Plain text response */
+  static text(text, { status = 200, headers = {} } = {}) {
+    return new MillasResponse({
+      type: 'text',
+      body: String(text),
+      status,
+      headers: { 'Content-Type': 'text/plain; charset=utf-8', ...headers },
+    });
+  }
+
+  /** Redirect response */
+  static redirect(url, { status = 302 } = {}) {
+    return new MillasResponse({
+      type:    'redirect',
+      body:    url,
+      status,
+      headers: { Location: url },
+    });
+  }
+
+  /** File download / serve response */
+  static file(filePath, { download = false, name = null, headers = {} } = {}) {
+    return new MillasResponse({
+      type: 'file',
+      body: { path: filePath, download, name },
+      status: 200,
+      headers,
+    });
+  }
+
+  /** Empty response (204 No Content by default) */
+  static empty(status = 204) {
+    return new MillasResponse({ type: 'empty', body: null, status });
+  }
+
+  /** Rendered view/template response */
+  static view(template, data = {}, { status = 200, headers = {} } = {}) {
+    return new MillasResponse({
+      type:   'view',
+      body:   { template, data },
+      status,
+      headers: { 'Content-Type': 'text/html; charset=utf-8', ...headers },
+    });
+  }
+
+  /**
+   * Check if something is a MillasResponse instance.
+   * Used by the router to distinguish from plain return values.
+   */
+  static isResponse(value) {
+    return value instanceof MillasResponse;
+  }
+}
+
+module.exports = MillasResponse;

package/src/http/RequestContext.js

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * RequestContext
+ *
+ * The single argument passed to every Millas route handler and middleware.
+ * Developers destructure exactly what they need — nothing else is in scope.
+ *
+ * Inspired by FastAPI's parameter injection. Each key maps to a specific
+ * part of the request — no more digging through a monolithic req object.
+ *
+ * ── Usage ───────────────────────────────────────────────────────────────────
+ *
+ *   // Route params  → params
+ *   Route.get('/users/:id', ({ params }) => User.findOrFail(params.id))
+ *
+ *   // Query string  → query
+ *   Route.get('/users', ({ query }) => User.paginate(query.page, query.per_page))
+ *
+ *   // Request body  → body  (alias: json)
+ *   Route.post('/users', async ({ body }) => {
+ *     const user = await User.create(body);
+ *     return jsonify(user, { status: 201 });
+ *   })
+ *
+ *   // Uploaded files → files
+ *   Route.post('/upload', ({ files }) => {
+ *     const avatar = files.avatar;
+ *     return jsonify({ size: avatar.size });
+ *   })
+ *
+ *   // Authenticated user → user
+ *   Route.get('/me', ({ user }) => jsonify(user))
+ *
+ *   // Multiple at once — destructure only what you need
+ *   Route.put('/users/:id', async ({ params, body, user }) => {
+ *     if (user.id !== params.id) abort(403);
+ *     return jsonify(await User.update(params.id, body));
+ *   })
+ *
+ *   // Inline validation on body
+ *   Route.post('/posts', async ({ body }) => {
+ *     const data = await body.validate({
+ *       title:   'required|string|max:255',
+ *       content: 'required|string',
+ *     });
+ *     return jsonify(await Post.create(data));
+ *   })
+ *
+ *   // DI container — for resolving services at request time
+ *   Route.get('/stats', ({ container }) => {
+ *     const cache = container.make('Cache');
+ *     return cache.remember('stats', 60, () => Stats.compute());
+ *   })
+ *
+ *   // Full MillasRequest escape hatch — when you need something not covered
+ *   Route.get('/raw', ({ req }) => {
+ *     const ip = req.ip;
+ *     return jsonify({ ip });
+ *   })
+ *
+ * ── Context shape ────────────────────────────────────────────────────────────
+ *
+ *   {
+ *     params,     // route parameters    { id: '5' }
+ *     query,      // query string        { page: '2', search: 'alice' }
+ *     body,       // request body        { name: 'Alice', email: '...' }  + .validate()
+ *     json,       // alias for body      (same object)
+ *     files,      // uploaded files      { avatar: File, resume: File }
+ *     headers,    // request headers     { authorization: 'Bearer ...' }
+ *     cookies,    // cookies             { session: 'abc123' }
+ *     user,       // authenticated user  (set by AuthMiddleware)
+ *     req,        // full MillasRequest  (escape hatch)
+ *     container,  // DI container        container.make('Cache')
+ *   }
+ */
+class RequestContext {
+  /**
+   * @param {import('./MillasRequest')} millaReq
+   * @param {import('../container/Container')|null} container
+   */
+  constructor(millaReq, container = null) {
+    this._req       = millaReq;
+    this._container = container;
+
+    // ── params ────────────────────────────────────────────────────────────────
+    // Route parameters — /users/:id → params.id
+    this.params = millaReq.raw.params || {};
+
+    // ── query ─────────────────────────────────────────────────────────────────
+    // Query string — ?page=2&search=alice → query.page, query.search
+    this.query = millaReq.raw.query || {};
+
+    // ── body / json ───────────────────────────────────────────────────────────
+    // Parsed request body (JSON, form data, etc.)
+    // body and json are the same object — use whichever reads better.
+    const rawBody = millaReq.raw.body || {};
+    this.body = this._buildBody(rawBody, millaReq);
+    this.json = this.body;   // alias
+
+    // ── files ─────────────────────────────────────────────────────────────────
+    // Uploaded files (populated by multer or similar middleware)
+    this.files = millaReq.raw.files || {};
+
+    // ── headers ───────────────────────────────────────────────────────────────
+    this.headers = millaReq.raw.headers || {};
+
+    // ── cookies ───────────────────────────────────────────────────────────────
+    this.cookies = millaReq.raw.cookies || {};
+
+    // ── user ──────────────────────────────────────────────────────────────────
+    // Authenticated user — set by AuthMiddleware via req.user
+    Object.defineProperty(this, 'user', {
+      get: () => millaReq.raw.user ?? null,
+      set: (v) => { millaReq.raw.user = v; },
+      enumerable: true,
+    });
+
+    // ── req ───────────────────────────────────────────────────────────────────
+    // Full MillasRequest — escape hatch for anything not covered above
+    this.req = millaReq;
+
+    // ── container ─────────────────────────────────────────────────────────────
+    // DI container — resolve services at request time
+    this.container = container;
+  }
+
+  // ─── Body with validation ──────────────────────────────────────────────────
+
+  /**
+   * Build the body object with an attached .validate() method.
+   * This keeps validation ergonomic and co-located with the body itself:
+   *
+   *   const data = await body.validate({
+   *     name:  'required|string|max:100',
+   *     email: 'required|email',
+   *   });
+   */
+  _buildBody(rawBody, millaReq) {
+    // Start with the raw body data
+    const body = Object.assign(Object.create(null), rawBody);
+
+    // Attach validate() directly on the body object
+    Object.defineProperty(body, 'validate', {
+      enumerable: false,   // doesn't show up in Object.keys / JSON.stringify
+      value: async function validate(rules) {
+        const { Validator } = require('../validation/Validator');
+        return Validator.validate(rawBody, rules);
+      },
+    });
+
+    // Attach only() and except() helpers too
+    Object.defineProperty(body, 'only', {
+      enumerable: false,
+      value: function only(keys) {
+        return keys.reduce((acc, k) => {
+          if (k in rawBody) acc[k] = rawBody[k];
+          return acc;
+        }, {});
+      },
+    });
+
+    Object.defineProperty(body, 'except', {
+      enumerable: false,
+      value: function except(keys) {
+        return Object.fromEntries(
+          Object.entries(rawBody).filter(([k]) => !keys.includes(k))
+        );
+      },
+    });
+
+    return body;
+  }
+}
+
+module.exports = RequestContext;

package/src/http/ResponseDispatcher.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const MillasResponse = require('./MillasResponse');
+
+/**
+ * ResponseDispatcher
+ *
+ * The only place in the entire framework where Express res methods are called.
+ * Takes a MillasResponse value object and drives the Express response.
+ *
+ * This is an internal kernel component — developers never call this directly.
+ * The Router calls it after the handler (and middleware pipeline) resolves.
+ */
+class ResponseDispatcher {
+
+  /**
+   * Dispatch a MillasResponse to the Express res.
+   *
+   * @param {MillasResponse} response
+   * @param {import('express').Response} expressRes
+   */
+  static dispatch(response, expressRes) {
+    if (!response || !MillasResponse.isResponse(response)) {
+      throw new Error(
+        '[ResponseDispatcher] Expected a MillasResponse instance. ' +
+        'Got: ' + typeof response
+      );
+    }
+
+    // ── Status ──────────────────────────────────────────────────────────────
+    expressRes.status(response.statusCode);
+
+    // ── CORS passthrough headers ─────────────────────────────────────────────
+    // CorsMiddleware stores headers on req._corsHeaders when it calls next()
+    // (i.e. non-preflight requests). Apply them here so every response carries
+    // the CORS headers regardless of what the route handler returned.
+    const corsHeaders = expressRes.req?._corsHeaders;
+    if (corsHeaders) {
+      for (const [name, value] of Object.entries(corsHeaders)) {
+        expressRes.setHeader(name, value);
+      }
+    }
+
+    // ── Response headers ─────────────────────────────────────────────────────
+    for (const [name, value] of Object.entries(response.headers)) {
+      expressRes.setHeader(name, value);
+    }
+
+    // ── Cookies ─────────────────────────────────────────────────────────────
+    for (const [name, { value, options }] of Object.entries(response.cookies)) {
+      if (options.maxAge === 0 || options.expires?.getTime() === 0) {
+        expressRes.clearCookie(name, options);
+      } else {
+        expressRes.cookie(name, value, options);
+      }
+    }
+
+    // ── Body ─────────────────────────────────────────────────────────────────
+    const { type, body } = response;
+
+    switch (type) {
+
+      case 'json':
+        // Let Express handle JSON serialisation and Content-Type
+        return expressRes.json(body);
+
+      case 'html':
+        return expressRes.send(body);
+
+      case 'text':
+        return expressRes.send(body);
+
+      case 'redirect':
+        return expressRes.redirect(response.statusCode, body);
+
+      case 'empty':
+        return expressRes.end();
+
+      case 'file': {
+        const { path: filePath, download, name: fileName } = body;
+        if (download) {
+          return expressRes.download(filePath, fileName || require('path').basename(filePath));
+        }
+        return expressRes.sendFile(require('path').resolve(filePath));
+      }
+
+      case 'view': {
+        // Nunjucks (or whatever template engine is wired) renders the template.
+        // expressRes.render() is configured by the framework's view engine setup.
+        const { template, data } = body;
+        return expressRes.render(template, data);
+      }
+
+      case 'stream': {
+        // body is a readable stream
+        if (body && typeof body.pipe === 'function') {
+          body.pipe(expressRes);
+        } else {
+          expressRes.end();
+        }
+        return;
+      }
+
+      default:
+        // Unknown type — try to send as-is
+        return expressRes.send(body);
+    }
+  }
+
+  /**
+   * Auto-wrap a plain return value into a MillasResponse.
+   *
+   * Called when a handler returns something that is NOT a MillasResponse —
+   * e.g. a plain object, string, number, or array.
+   *
+   * @param {*} value
+   * @returns {MillasResponse}
+   */
+  static autoWrap(value) {
+    if (MillasResponse.isResponse(value)) return value;
+
+    if (value instanceof Error) {
+      // Let the caller handle errors — don't wrap them into responses
+      throw value;
+    }
+
+    if (typeof value === 'string') {
+      // Detect HTML (starts with < tag) vs plain text
+      const isHtml = value.trimStart().startsWith('<');
+      return isHtml
+        ? MillasResponse.html(value)
+        : MillasResponse.text(value);
+    }
+
+    if (typeof value === 'object' || typeof value === 'number' || typeof value === 'boolean') {
+      return MillasResponse.json(value);
+    }
+
+    // Fallback
+    return MillasResponse.text(String(value));
+  }
+}
+
+module.exports = ResponseDispatcher;

package/src/http/helpers.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const MillasResponse = require('./MillasResponse');
+const HttpError      = require('../errors/HttpError');
+
+/**
+ * Millas HTTP Helper Functions
+ *
+ * These are the only response-building tools developers need.
+ * Import them at the top of any route/controller file.
+ *
+ *   const { jsonify, view, redirect, text, abort } = require('millas');
+ *
+ * Every helper returns a MillasResponse instance. Nothing is written
+ * to the socket until the kernel's ResponseDispatcher processes it.
+ */
+
+/**
+ * Return a JSON response.
+ *
+ *   return jsonify(users)
+ *   return jsonify(user, { status: 201 })
+ *   return jsonify({ error: 'Not found' }, { status: 404 })
+ *   return jsonify(data).header('X-Total', String(total))
+ *   return jsonify(data).cookie('token', jwt, { httpOnly: true })
+ *
+ * @param {*}      data
+ * @param {object} [options]
+ * @param {number} [options.status=200]
+ * @param {object} [options.headers={}]
+ * @returns {MillasResponse}
+ */
+function jsonify(data, options = {}) {
+  return MillasResponse.json(data, options);
+}
+
+/**
+ * Return an HTML view (template) response.
+ *
+ *   return view('users/index', { users })
+ *   return view('emails/welcome', { user }, { status: 200 })
+ *
+ * @param {string} template  — template path relative to views directory
+ * @param {object} [data={}] — data passed to the template
+ * @param {object} [options]
+ * @param {number} [options.status=200]
+ * @returns {MillasResponse}
+ */
+function view(template, data = {}, options = {}) {
+  return MillasResponse.view(template, data, options);
+}
+
+/**
+ * Return a redirect response.
+ *
+ *   return redirect('/login')
+ *   return redirect('/dashboard', { status: 301 })
+ *   return redirect('back')   // redirects to Referer header or '/'
+ *
+ * @param {string} url
+ * @param {object} [options]
+ * @param {number} [options.status=302]
+ * @returns {MillasResponse}
+ */
+function redirect(url, options = {}) {
+  return MillasResponse.redirect(url, options);
+}
+
+/**
+ * Return a plain text response.
+ *
+ *   return text('Hello, world')
+ *   return text('Created', { status: 201 })
+ *
+ * @param {string} content
+ * @param {object} [options]
+ * @param {number} [options.status=200]
+ * @returns {MillasResponse}
+ */
+function text(content, options = {}) {
+  return MillasResponse.text(content, options);
+}
+
+/**
+ * Return a file response (send / download).
+ *
+ *   return file('/storage/uploads/report.pdf')
+ *   return file('/storage/uploads/report.pdf', { download: true })
+ *   return file('/storage/uploads/report.pdf', { download: true, name: 'report.pdf' })
+ *
+ * @param {string} filePath  — absolute or relative path
+ * @param {object} [options]
+ * @param {boolean} [options.download=false] — force download (Content-Disposition: attachment)
+ * @param {string}  [options.name]           — filename shown to the user on download
+ * @returns {MillasResponse}
+ */
+function file(filePath, options = {}) {
+  return MillasResponse.file(filePath, options);
+}
+
+/**
+ * Return an empty response.
+ *
+ *   return empty()        // 204 No Content
+ *   return empty(200)     // 200 with no body
+ *
+ * @param {number} [status=204]
+ * @returns {MillasResponse}
+ */
+function empty(status = 204) {
+  return MillasResponse.empty(status);
+}
+
+/**
+ * Throw an HTTP error — caught by the kernel and rendered by ErrorRenderer.
+ *
+ *   abort(404)
+ *   abort(403, 'You are not allowed to do that')
+ *   abort(422, 'Validation failed', { email: ['Email is required'] })
+ *
+ * @param {number} status
+ * @param {string} [message]
+ * @param {object} [errors]
+ * @throws {HttpError}
+ */
+function abort(status, message, errors = null) {
+  throw new HttpError(status, message, errors);
+}
+
+/**
+ * Throw a 404 Not Found error.
+ *   notFound()
+ *   notFound('User not found')
+ */
+function notFound(message = 'Not Found') {
+  abort(404, message);
+}
+
+/**
+ * Throw a 401 Unauthorized error.
+ */
+function unauthorized(message = 'Unauthorized') {
+  abort(401, message);
+}
+
+/**
+ * Throw a 403 Forbidden error.
+ */
+function forbidden(message = 'Forbidden') {
+  abort(403, message);
+}
+
+module.exports = {
+  jsonify,
+  view,
+  redirect,
+  text,
+  file,
+  empty,
+  abort,
+  notFound,
+  unauthorized,
+  forbidden,
+};

package/src/http/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const MillasRequest      = require('./MillasRequest');
+const MillasResponse     = require('./MillasResponse');
+const ResponseDispatcher = require('./ResponseDispatcher');
+const helpers            = require('./helpers');
+
+module.exports = {
+  MillasRequest,
+  MillasResponse,
+  ResponseDispatcher,
+  ...helpers,
+};