millas 0.2.11 → 0.2.12-beta-1

package/src/http/MillasRequest.js

@@ -0,0 +1,253 @@
+'use strict';
+
+/**
+ * MillasRequest
+ *
+ * Wraps an Express request and exposes a clean, framework-level API.
+ * Developers never touch the raw Express req — they use this instead.
+ *
+ * The raw Express req is accessible via req.raw for escape hatches,
+ * but should never be needed in normal application code.
+ *
+ * Usage in route handlers:
+ *   Route.get('/users/:id', async (req) => {
+ *     const id   = req.param('id');
+ *     const page = req.input('page', 1);
+ *     const user = await User.findOrFail(id);
+ *     return jsonify(user);
+ *   });
+ */
+class MillasRequest {
+  /**
+   * @param {import('express').Request} expressReq
+   */
+  constructor(expressReq) {
+    /** @private — access via req.raw if absolutely necessary */
+    this._req = expressReq;
+
+    // Proxy commonly-used scalar properties for convenience
+    this.method  = expressReq.method;
+    this.path    = expressReq.path;
+    this.url     = expressReq.url;
+    this.baseUrl = expressReq.baseUrl;
+    this.originalUrl = expressReq.originalUrl;
+  }
+
+  // ─── Input ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Read a value from body, query, or route params — in that priority order.
+   * Returns defaultValue if not present.
+   *
+   *   req.input('email')
+   *   req.input('page', 1)
+   */
+  input(key, defaultValue = null) {
+    if (key === undefined) return this.all();
+    const r = this._req;
+    const v =
+      (r.body   && r.body[key]   !== undefined ? r.body[key]   : undefined) ??
+      (r.query  && r.query[key]  !== undefined ? r.query[key]  : undefined) ??
+      (r.params && r.params[key] !== undefined ? r.params[key] : undefined);
+    return v !== undefined ? v : defaultValue;
+  }
+
+  /**
+   * Read a route parameter.
+   *   req.param('id')
+   */
+  param(key, defaultValue = null) {
+    return this._req.params?.[key] ?? defaultValue;
+  }
+
+  /**
+   * Read a query string value.
+   *   req.query('page', 1)
+   */
+  query(key, defaultValue = null) {
+    if (key === undefined) return this._req.query || {};
+    return this._req.query?.[key] ?? defaultValue;
+  }
+
+  /**
+   * Read from the request body only.
+   *   req.body('email')
+   */
+  body(key, defaultValue = null) {
+    if (key === undefined) return this._req.body || {};
+    return this._req.body?.[key] ?? defaultValue;
+  }
+
+  /**
+   * Merge body + query + params into one flat object.
+   */
+  all() {
+    return {
+      ...this._req.params,
+      ...this._req.query,
+      ...this._req.body,
+    };
+  }
+
+  /**
+   * Return only the specified keys from the merged input.
+   *   req.only(['name', 'email'])
+   */
+  only(keys = []) {
+    const all = this.all();
+    return keys.reduce((acc, k) => {
+      if (k in all) acc[k] = all[k];
+      return acc;
+    }, {});
+  }
+
+  /**
+   * Return all input except the specified keys.
+   *   req.except(['password', 'token'])
+   */
+  except(keys = []) {
+    const all = this.all();
+    return Object.fromEntries(
+      Object.entries(all).filter(([k]) => !keys.includes(k))
+    );
+  }
+
+  // ─── Headers ────────────────────────────────────────────────────────────────
+
+  /**
+   * Read a request header (case-insensitive).
+   *   req.header('Authorization')
+   *   req.header('content-type')
+   */
+  header(name, defaultValue = null) {
+    if (name === undefined) return this._req.headers || {};
+    return this._req.headers?.[name.toLowerCase()] ?? defaultValue;
+  }
+
+  /**
+   * All request headers as a plain object.
+   */
+  get headers() {
+    return this._req.headers || {};
+  }
+
+  // ─── Cookies ────────────────────────────────────────────────────────────────
+
+  /**
+   * Read a cookie value.
+   *   req.cookie('session_id')
+   */
+  cookie(name, defaultValue = null) {
+    return this._req.cookies?.[name] ?? defaultValue;
+  }
+
+  // ─── Files ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Get an uploaded file (requires multer or similar middleware upstream).
+   *   req.file('avatar')
+   */
+  file(name) {
+    if (this._req.files && this._req.files[name]) return this._req.files[name];
+    if (this._req.file  && this._req.file.fieldname === name) return this._req.file;
+    return null;
+  }
+
+  /**
+   * All uploaded files.
+   */
+  get files() {
+    return this._req.files || {};
+  }
+
+  // ─── User ───────────────────────────────────────────────────────────────────
+
+  /**
+   * The authenticated user (set by AuthMiddleware).
+   */
+  get user() {
+    return this._req.user ?? null;
+  }
+
+  /** Set the authenticated user (used by AuthMiddleware). */
+  set user(value) {
+    this._req.user = value;
+  }
+
+  // ─── Content negotiation ────────────────────────────────────────────────────
+
+  /**
+   * Returns true if the request expects a JSON response.
+   */
+  wantsJson() {
+    const accept = this.header('accept', '');
+    return accept.includes('application/json') || accept.includes('*/*');
+  }
+
+  /**
+   * Returns true if the request body is JSON.
+   */
+  isJson() {
+    const ct = this.header('content-type', '');
+    return ct.includes('application/json');
+  }
+
+  /**
+   * Returns true if this was an XMLHttpRequest / fetch call.
+   */
+  isAjax() {
+    return this.header('x-requested-with', '').toLowerCase() === 'xmlhttprequest';
+  }
+
+  // ─── Network ────────────────────────────────────────────────────────────────
+
+  /**
+   * Client IP address.
+   */
+  get ip() {
+    return this._req.ip || this._req.connection?.remoteAddress || null;
+  }
+
+  /**
+   * Request hostname (from Host header).
+   */
+  get hostname() {
+    return this._req.hostname || '';
+  }
+
+  /**
+   * Whether the request is HTTPS.
+   */
+  get secure() {
+    return this._req.secure || false;
+  }
+
+  // ─── Validation ─────────────────────────────────────────────────────────────
+
+  /**
+   * Validate request input against rules. Throws 422 HttpError on failure.
+   * Returns the validated data on success.
+   *
+   *   const data = await req.validate({
+   *     name:  'required|string|min:2|max:100',
+   *     email: 'required|email',
+   *     age:   'optional|number|min:0',
+   *   });
+   */
+  async validate(rules) {
+    const { Validator } = require('../validation/Validator');
+    return Validator.validate(this.all(), rules);
+  }
+
+  // ─── Escape hatch ────────────────────────────────────────────────────────────
+
+  /**
+   * The raw underlying Express request.
+   * Only use this when you genuinely need something MillasRequest doesn't expose.
+   */
+  get raw() {
+    return this._req;
+  }
+}
+
+module.exports = MillasRequest;

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,51 @@
+'use strict';
+
+const MillasResponse = require('./MillasResponse');
+
+/**
+ * ResponseDispatcher
+ *
+ * Kernel-side utility — handles auto-wrapping plain return values into
+ * MillasResponse objects.
+ *
+ * Actual dispatch to the HTTP engine (setting headers, writing the body)
+ * lives in HttpAdapter.dispatch() — that is the only place HTTP-engine
+ * APIs are called.
+ *
+ * This file has zero imports of Express or any HTTP engine.
+ */
+class ResponseDispatcher {
+
+  /**
+   * Auto-wrap a plain JS return value into a MillasResponse.
+   *
+   * Called when a route handler returns something that is NOT already
+   * 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) throw value;
+
+    if (typeof value === 'string') {
+      return value.trimStart().startsWith('<')
+        ? MillasResponse.html(value)
+        : MillasResponse.text(value);
+    }
+
+    if (
+      typeof value === 'object'  ||
+      typeof value === 'number'  ||
+      typeof value === 'boolean'
+    ) {
+      return MillasResponse.json(value);
+    }
+
+    return MillasResponse.text(String(value));
+  }
+}
+
+module.exports = ResponseDispatcher;