millas 0.2.11 → 0.2.12-beta

package/src/controller/Controller.js

@@ -1,363 +1,142 @@
 'use strict';
 
-const HttpError = require('../errors/HttpError');
+const HttpError  = require('../errors/HttpError');
+const { jsonify, redirect, view, text, empty } = require('../http/helpers');
 
 /**
  * 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()
+ * Controller methods receive a MillasRequest and return a MillasResponse
+ * (or a plain value that the kernel auto-wraps). Express is never exposed.
  *
  * Usage:
  *   class UserController extends Controller {
- *     async index(req, res) {
- *       return this.ok(res, { users: [] });
+ *     async index(req) {
+ *       const users = await User.all();
+ *       return this.ok(users);
+ *     }
+ *
+ *     async store(req) {
+ *       const data = await req.validate({
+ *         name:  'required|string',
+ *         email: 'required|email',
+ *       });
+ *       const user = await User.create(data);
+ *       return this.created(user);
  *     }
  *   }
  */
 class Controller {
 
-  // ─── Response Helpers ────────────────────────────────────────────────────────
+  // ─── Response helpers ────────────────────────────────────────────────────────
 
-  /**
-   * 200 OK
-   * @param {object} res
-   * @param {*} data
-   */
-  ok(res, data = null) {
-    return res.status(200).json(this._envelope(200, data));
+  /** 200 OK */
+  ok(data = null) {
+    return jsonify(this._envelope(200, data), { status: 200 });
   }
 
-  /**
-   * 201 Created
-   */
-  created(res, data = null) {
-    return res.status(201).json(this._envelope(201, data));
+  /** 201 Created */
+  created(data = null) {
+    return jsonify(this._envelope(201, data), { status: 201 });
   }
 
-  /**
-   * 204 No Content
-   */
-  noContent(res) {
-    return res.status(204).send();
+  /** 204 No Content */
+  noContent() {
+    return empty(204);
   }
 
-  /**
-   * 200 with a custom JSON payload (no envelope)
-   */
-  json(res, data, status = 200) {
-    return res.status(status).json(data);
+  /** 200 with a custom JSON payload (no envelope) */
+  json(data, status = 200) {
+    return jsonify(data, { status });
   }
 
-  /**
-   * 400 Bad Request
-   */
-  badRequest(res, message = 'Bad Request', errors = null) {
-    return res.status(400).json({
-      error:   'Bad Request',
-      message,
-      status:  400,
+  /** 400 Bad Request */
+  badRequest(message = 'Bad Request', errors = null) {
+    return jsonify({
+      error: 'Bad Request', message, status: 400,
       ...(errors && { errors }),
-    });
+    }, { status: 400 });
   }
 
-  /**
-   * 401 Unauthorized
-   */
-  unauthorized(res, message = 'Unauthorized') {
-    return res.status(401).json({ error: 'Unauthorized', message, status: 401 });
+  /** 401 Unauthorized */
+  unauthorized(message = 'Unauthorized') {
+    return jsonify({ error: 'Unauthorized', message, status: 401 }, { status: 401 });
   }
 
-  /**
-   * 403 Forbidden
-   */
-  forbidden(res, message = 'Forbidden') {
-    return res.status(403).json({ error: 'Forbidden', message, status: 403 });
+  /** 403 Forbidden */
+  forbidden(message = 'Forbidden') {
+    return jsonify({ error: 'Forbidden', message, status: 403 }, { status: 403 });
   }
 
-  /**
-   * 404 Not Found
-   */
-  notFound(res, message = 'Not Found') {
-    return res.status(404).json({ error: 'Not Found', message, status: 404 });
+  /** 404 Not Found */
+  notFound(message = 'Not Found') {
+    return jsonify({ error: 'Not Found', message, status: 404 }, { status: 404 });
   }
 
-  /**
-   * 422 Unprocessable Entity — validation failed
-   */
-  unprocessable(res, errors) {
-    return res.status(422).json({
-      error:   'Unprocessable Entity',
+  /** 422 Unprocessable Entity */
+  unprocessable(errors) {
+    return jsonify({
+      error: 'Unprocessable Entity',
       message: 'Validation failed',
-      status:  422,
+      status: 422,
       errors,
-    });
+    }, { status: 422 });
   }
 
-  /**
-   * 500 Internal Server Error
-   */
-  serverError(res, message = 'Internal Server Error') {
-    return res.status(500).json({ error: 'Internal Server Error', message, status: 500 });
+  /** 500 Internal Server Error */
+  serverError(message = 'Internal Server Error') {
+    return jsonify({ error: 'Internal Server Error', message, status: 500 }, { 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;
+  /** Render a view */
+  render(template, data = {}, status = 200) {
+    return view(template, data, { status });
   }
 
-  /**
-   * Merge body + query + params into one flat object.
-   */
-  all(req) {
-    return {
-      ...req.params,
-      ...req.query,
-      ...req.body,
-    };
+  /** Redirect */
+  redirectTo(url, status = 302) {
+    return redirect(url, { status });
   }
 
   /**
-   * Return only the specified keys from the request.
+   * Paginated list response.
    *
-   * this.only(req, ['name', 'email'])
+   *   return this.paginate({ data: users, total: 100, page: 2, perPage: 15 });
    */
-  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 }) {
+  paginate({ data, total, page = 1, perPage = 15 }) {
     const lastPage = Math.ceil(total / perPage);
-    return res.status(200).json({
+    return jsonify({
       data,
       meta: {
         total,
-        per_page:    perPage,
+        per_page:     perPage,
         current_page: Number(page),
-        last_page:   lastPage,
-        from:        (page - 1) * perPage + 1,
-        to:          Math.min(page * perPage, total),
+        last_page:    lastPage,
+        from:         (page - 1) * perPage + 1,
+        to:           Math.min(page * perPage, total),
       },
     });
   }
 
+  // ─── Abort ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Throw an HTTP error.
+   *   this.abort(404, 'User not found')
+   *   this.abort(403)
+   */
+  abort(status, message) {
+    throw new HttpError(status, message);
+  }
+
   // ─── 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)) {
+    if (typeof data === 'object' && !Array.isArray(data) &&
+        ('data' in data || 'message' in data)) {
       return { status, ...data };
     }
     return { status, data };