millas 0.2.13 → 0.2.15

package/src/container/MillasConfig.js

@@ -52,6 +52,13 @@ class MillasConfig {
             // Admin panel — null means disabled, {} or options object means enabled
             admin: null,
 
+            // Docs panel — null means disabled, {} or options object means enabled
+            docs: null,
+
+            // CORS — null means disabled, true means enabled.
+            // All configuration comes from config/app.js cors: { ... }.
+            cors: null,
+
             // Raw adapter-level middleware (e.g. helmet, compression)
             adapterMiddleware: [],
 
@@ -130,6 +137,47 @@ class MillasConfig {
         return this;
     }
 
+    /**
+     * Enable the API documentation panel.
+     *
+     * DocsServiceProvider is registered automatically — no need to add it
+     * to .providers([]). The panel mounts at /docs by default.
+     *
+     *   .withDocs()
+     *   .withDocs({ prefix: '/api-docs', title: 'My API', auth: true })
+     *
+     * To register ApiResources, call Docs.register() / Docs.registerMany()
+     * inside AppServiceProvider.boot() or a dedicated bootstrap/docs.js.
+     */
+    withDocs(options = {}) {
+        this._config.docs = options;
+        return this;
+    }
+
+    /**
+     * Enable global CORS headers.
+     *
+     * Takes no arguments — all CORS settings are configured in config/app.js:
+     *
+     *   // config/app.js
+     *   cors: {
+     *     origins:     ['https://app.example.com'],
+     *     credentials: true,
+     *     methods:     ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+     *     headers:     ['Content-Type', 'Authorization', 'X-Requested-With'],
+     *     maxAge:      86400,
+     *   }
+     *
+     * Omitting the cors key in config/app.js falls back to CorsMiddleware defaults
+     * (allow all origins, standard methods, no credentials).
+     *
+     *   .withCors()
+     */
+    withCors() {
+        this._config.cors = true;
+        return this;
+    }
+
     /**
      * Disable individual core services.
      *

package/src/controller/Controller.js

@@ -8,24 +8,26 @@ const { jsonify, redirect, view, text, empty } = require('../http/helpers');
  *
  * Base class for all Millas controllers.
  *
- * Controller methods receive a MillasRequest and return a MillasResponse
- * (or a plain value that the kernel auto-wraps). Express is never exposed.
+ * Controller methods receive a RequestContext destructured as named keys.
+ * Express req/res are never exposed. Return a response helper or plain value.
  *
  * Usage:
  *   class UserController extends Controller {
- *     async index(req) {
- *       const users = await User.all();
+ *     async index({ query }) {
+ *       const users = await User.paginate(query.page, query.per_page);
  *       return this.ok(users);
  *     }
  *
- *     async store(req) {
- *       const data = await req.validate({
- *         name:  'required|string',
- *         email: 'required|email',
- *       });
- *       const user = await User.create(data);
+ *     async store({ body }) {
+ *       // body is already validated when .shape() is used on the route
+ *       const user = await User.create(body);
  *       return this.created(user);
  *     }
+ *
+ *     async show({ params }) {
+ *       const user = await User.findOrFail(params.id);
+ *       return this.ok(user);
+ *     }
  *   }
  */
 class Controller {
@@ -143,4 +145,4 @@ class Controller {
   }
 }
 
-module.exports = Controller;
+module.exports = Controller;

package/src/core/docs.js

@@ -0,0 +1,6 @@
+// ── Docs ──────────────────────────────────────────────────────────────────────
+const { Docs, ApiResource, ApiEndpoint, ApiField } = require('../docs');
+module.exports.Docs        = Docs;
+module.exports.ApiResource = ApiResource;
+module.exports.ApiEndpoint = ApiEndpoint;
+module.exports.ApiField    = ApiField;

package/src/core/foundation.js

@@ -41,6 +41,10 @@ const { CacheServiceProvider, StorageServiceProvider } = require('../providers/C
 // ── Storage ───────────────────────────────────────────────────────
 const Storage     = require('../storage/Storage');
 const LocalDriver = require('../storage/drivers/LocalDriver');
+// ── Serializer ────────────────────────────────────────────────────
+const { Serializer } = require('../serializer/Serializer');
+const {Str, FluentString} = require("../support/Str");
+
 module.exports = {
   // ── Millas HTTP layer ──────────────────────────────────────────
   MillasRequest, MillasResponse, ResponseDispatcher, RequestContext,
@@ -55,5 +59,9 @@ module.exports = {
   Cache, MemoryDriver, FileDriver, NullDriver, CacheServiceProvider,
   // Storage
   Storage, LocalDriver, StorageServiceProvider,
+  // Serializer
+  Serializer,
+  // Support
+  Str, FluentString,
   Log: require('../logger').Log,
 };

package/src/core/http.js

@@ -1,11 +1,21 @@
-const Controller = require("../controller/Controller");
-const Middleware = require("../middleware/Middleware");
-const MiddlewarePipeline = require("../middleware/MiddlewarePipeline");
-const CorsMiddleware = require("../middleware/CorsMiddleware");
-const ThrottleMiddleware = require("../middleware/ThrottleMiddleware");
-const LogMiddleware = require("../middleware/LogMiddleware");
-const HttpError = require("../errors/HttpError");
+const Controller      = require('../controller/Controller');
+const Middleware      = require('../middleware/Middleware');
+const MiddlewarePipeline = require('../middleware/MiddlewarePipeline');
+const CorsMiddleware  = require('../middleware/CorsMiddleware');
+const ThrottleMiddleware = require('../middleware/ThrottleMiddleware');
+const LogMiddleware   = require('../middleware/LogMiddleware');
+const HttpError       = require('../errors/HttpError');
+const { shape, isShape } = require('../http/Shape');
+
 module.exports = {
-    Controller, Middleware, MiddlewarePipeline,
-  CorsMiddleware, ThrottleMiddleware, LogMiddleware, HttpError,
-}
+  Controller,
+  Middleware,
+  MiddlewarePipeline,
+  CorsMiddleware,
+  ThrottleMiddleware,
+  LogMiddleware,
+  HttpError,
+  // Shape factory — define route input/output contracts
+  shape,
+  isShape,
+};

package/src/core/validation.js

@@ -1,29 +1,60 @@
+'use strict';
+
+/**
+ * millas/core/validation
+ *
+ * Re-exports everything from the validation layer.
+ * Import from here in your app code — never from the internal paths.
+ *
+ *   const { string, email, number, boolean, array, object, date, file } =
+ *     require('millas/core/validation');
+ */
+
+const { Validator, ValidationError } = require('../validation/Validator');
+const { BaseValidator }              = require('../validation/BaseValidator');
 const {
-    Validator,
-    BaseValidator,
-    StringValidator,
-    EmailValidator,
-    NumberValidator,
-    BooleanValidator,
-    DateValidator,
-    ArrayValidator,
-    ObjectValidator,
-    FileValidator,
-    string,
-    email,
-    number,
-    boolean,
-    date,
-    array,
-    objectField,
-    fileField
-} = require("../validation/Validator");
+  StringValidator,
+  EmailValidator,
+  NumberValidator,
+  BooleanValidator,
+  ArrayValidator,
+  DateValidator,
+  ObjectValidator,
+  FileValidator,
+  string,
+  email,
+  number,
+  boolean,
+  array,
+  date,
+  object,
+  file,
+} = require('../validation/types');
+
 module.exports = {
-    Validator,
-    BaseValidator,
-    StringValidator, EmailValidator, NumberValidator, BooleanValidator,
-    DateValidator, ArrayValidator, ObjectValidator, FileValidator,
-    string, email, number, boolean, date, array,
-    object: objectField,
-    file: fileField,
-}
+  // Core classes
+  Validator,
+  ValidationError,
+  BaseValidator,
+  // Typed validator classes (for instanceof checks)
+  StringValidator,
+  EmailValidator,
+  NumberValidator,
+  BooleanValidator,
+  ArrayValidator,
+  DateValidator,
+  ObjectValidator,
+  FileValidator,
+  // Factory functions — what developers use
+  string,
+  email,
+  number,
+  boolean,
+  array,
+  date,
+  object,
+  file,
+  // Aliases matching the original zip's core/validation.js exports
+  objectField: object,
+  fileField:   file,
+};

package/src/docs/Docs.js

@@ -0,0 +1,268 @@
+'use strict';
+
+const path    = require('path');
+const express = require('express');
+const { ApiResource } = require('./resources/ApiResource');
+
+/**
+ * Docs
+ *
+ * The singleton that owns all ApiResources, configuration,
+ * and the Express mount logic.
+ *
+ * Lifecycle (mirrors Admin):
+ *   1. DocsServiceProvider.boot() calls Docs.configure({ prefix, title, ... })
+ *   2. Developer calls Docs.register() / Docs.registerMany() in
+ *      AppServiceProvider.boot() or bootstrap/docs.js
+ *   3. AppInitializer._serve() calls Docs.mount(expressApp) after routes are mounted
+ *
+ * Usage in AppServiceProvider.boot():
+ *
+ *   const { Docs } = require('millas/src/docs');
+ *   Docs.registerMany([ UserApiResource, PropertyApiResource ]);
+ */
+class Docs {
+  constructor() {
+    this._resources = new Map();   // slug → ApiResource class
+    this._config    = {
+      prefix:   '/docs',
+      title:    'API Docs',
+      enabled:  true,
+      auth:     false,   // require admin session to view docs
+    };
+    this._routeRegistry = null;    // injected by DocsServiceProvider
+  }
+
+  // ── Configuration ──────────────────────────────────────────────────────────
+
+  configure(config = {}) {
+    Object.assign(this._config, config);
+    return this;
+  }
+
+  setRouteRegistry(registry) {
+    this._routeRegistry = registry;
+    return this;
+  }
+
+  // ── Resource registration ──────────────────────────────────────────────────
+
+  register(ResourceClass) {
+    // Accept raw ApiResource subclass or auto-wrap anything with a controller property
+    if (!(ResourceClass.prototype instanceof ApiResource) &&
+        ResourceClass !== ApiResource) {
+      // Developer passed something that isn't an ApiResource — ignore
+      process.stderr.write(`[Docs] Skipping non-ApiResource: ${ResourceClass?.name}\n`);
+      return this;
+    }
+    this._resources.set(ResourceClass.slug, ResourceClass);
+    return this;
+  }
+
+  registerMany(list = []) {
+    list.forEach(r => this.register(r));
+    return this;
+  }
+
+  resources() {
+    return [...this._resources.values()];
+  }
+
+  // ── Mount ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Mount the docs panel onto an Express app.
+   * Called automatically by AppInitializer when .withDocs() was used.
+   */
+  mount(expressApp) {
+    if (!this._config.enabled) return this;
+
+    const prefix = this._config.prefix;
+
+    // Static assets
+    const staticPath = path.join(__dirname, 'static');
+    expressApp.use(
+      prefix + '/static',
+      express.static(staticPath, { maxAge: '1h' })
+    );
+
+    const PageHandler = require('./handlers/PageHandler');
+    const ApiHandler  = require('./handlers/ApiHandler');
+
+    const page = new PageHandler(this);
+    const api  = new ApiHandler(this);
+
+    // ── UI routes ─────────────────────────────────────────────────────────
+    expressApp.get(prefix,          (q, s) => page.index(q, s));
+    expressApp.get(prefix + '/',    (q, s) => page.index(q, s));
+
+    // ── Internal API routes (used by the "Try it" panel) ──────────────────
+    // Returns the full docs manifest as JSON — all groups, endpoints, schemas
+    expressApp.get(`${prefix}/_api/manifest`,           (q, s) => api.manifest(q, s));
+    // Proxy a real request so the browser never has CORS issues
+    expressApp.post(`${prefix}/_api/try`,               (q, s) => api.tryRequest(q, s));
+    // Export: Postman collection
+    expressApp.get(`${prefix}/_api/export/postman`,     (q, s) => api.exportPostman(q, s));
+    // Export: OpenAPI 3.0
+    expressApp.get(`${prefix}/_api/export/openapi`,     (q, s) => api.exportOpenApi(q, s));
+
+    return this;
+  }
+
+  // ── Internal helpers ───────────────────────────────────────────────────────
+
+  /**
+   * Build the full manifest: all groups with their endpoints.
+   * Merges declared ApiResources with auto-discovered routes.
+   */
+  buildManifest() {
+    const registry = this._routeRegistry;
+    const { inferFields } = require('./SchemaInferrer');
+    const { ApiEndpoint } = require('./resources/ApiResource');
+
+    // ── Phase 1: Build groups from route-level shapes ─────────────────────
+    // Routes with .shape() / .fromShape() are the primary source of truth.
+    // Grouped by shape.group, then shape.label within each group.
+    const shapeGroups = new Map();   // groupName → [endpoint, ...]
+    const claimedPaths = new Set();
+
+    if (registry) {
+      for (const route of registry.all()) {
+        if (_isFrameworkRoute(route.path)) continue;
+        if (!route.shape) continue;
+
+        const shape  = route.shape;
+        const verb   = route.verb.toLowerCase();
+        const group  = shape.group || 'General';
+        const isAuth = (route.middleware || []).includes('auth');
+
+        // Infer body + query fields from the shape validators
+        const bodyFields  = inferFields(shape.in    || {});
+        const queryFields = inferFields(shape.query || {});
+
+        // Build out responses
+        const responses = Object.entries(shape.out || {}).map(([status, example]) => ({
+          status:  Number(status),
+          example: example || null,
+          description: null,
+        }));
+
+        const endpointJson = {
+          verb:           verb,
+          path:           route.path,
+          shortPath:      route.path,
+          label:          shape.label  || _autoLabel(route.path, verb),
+          description:    shape.description || null,
+          auth:           isAuth,
+          body:           bodyFields,
+          query:          queryFields,
+          params:         {},
+          headers:        {},
+          responses,
+          tags:           [],
+          deprecated:     false,
+          bodyEncoding:   shape.encoding || 'json',
+          autoDiscovered: false,
+          unmatched:      false,
+          routeName:      route.name || null,
+          pathParams:     _extractPathParams(route.path),
+        };
+
+        if (!shapeGroups.has(group)) shapeGroups.set(group, []);
+        shapeGroups.get(group).push(endpointJson);
+        claimedPaths.add(`${verb}:${route.path}`);
+      }
+    }
+
+    const groups = [];
+
+    // Convert shapeGroups map → groups array (sorted alphabetically)
+    for (const [groupName, endpoints] of [...shapeGroups.entries()].sort()) {
+      groups.push({
+        slug:        groupName.toLowerCase().replace(/\s+/g, '-'),
+        label:       groupName,
+        group:       groupName,
+        icon:        'code-slash',
+        description: null,
+        endpoints:   endpoints.sort((a, b) => a.path.localeCompare(b.path)),
+      });
+    }
+
+    // ── Phase 2: ApiResource declarations (override / enrich) ────────────
+    for (const R of this._resources.values()) {
+      const endpoints = R._build(registry).map(ep => {
+        const j = ep.toJSON();
+        claimedPaths.add(`${j.verb}:${j.path}`);
+        return j;
+      });
+
+      groups.push({
+        slug:        R.slug,
+        label:       R.label || R.controller?.name || R.slug,
+        group:       R.group,
+        icon:        R.icon,
+        description: R.description,
+        endpoints,
+      });
+    }
+
+    // ── Phase 3: Auto-discovered routes (no shape, no ApiResource) ────────
+    const undocumented = [];
+    if (registry) {
+      for (const route of registry.all()) {
+        if (_isFrameworkRoute(route.path)) continue;
+        const key = `${route.verb.toLowerCase()}:${route.path}`;
+        if (claimedPaths.has(key)) continue;
+
+        const ep = new ApiEndpoint(route.verb.toLowerCase(), route.path);
+        ep._auth           = (route.middleware || []).includes('auth');
+        ep._autoDiscovered = true;
+        ep._routeName      = route.name || null;
+        undocumented.push(ep.toJSON());
+      }
+    }
+
+    if (undocumented.length) {
+      groups.push({
+        slug:        '_undocumented',
+        label:       'Undocumented',
+        group:       null,
+        icon:        'question-circle',
+        description: 'Routes with no .shape() declaration. Add .shape() to document them.',
+        endpoints:   undocumented,
+      });
+    }
+
+    return {
+      title:  this._config.title,
+      prefix: this._config.prefix,
+      groups,
+    };
+  }
+}
+
+function _isFrameworkRoute(p) {
+  return /^\/(admin|docs)(\/|$)/.test(p || '');
+}
+
+function _autoLabel(path, verb) {
+  const parts = (path || '')
+    .split('/').filter(p => p && !p.startsWith(':') && !/^v\d+$/.test(p) && p !== 'api');
+  const base = (parts[parts.length - 1] || 'Endpoint')
+    .replace(/-/g, ' ').replace(/\w/g, c => c.toUpperCase());
+  const hasId = (path || '').includes(':');
+  const v     = (verb || '').toUpperCase();
+  if (v === 'GET'   && hasId)         return 'Get '    + base;
+  if (v === 'GET')                    return 'List '   + base;
+  if (v === 'POST')                   return 'Create ' + base;
+  if (v === 'PUT'  || v === 'PATCH')  return 'Update ' + base;
+  if (v === 'DELETE')                 return 'Delete ' + base;
+  return base;
+}
+
+function _extractPathParams(path) {
+  return ((path || '').match(/:([a-zA-Z_][a-zA-Z0-9_]*)/g) || []).map(function(m) { return m.slice(1); });
+}
+
+// Singleton export — mirrors Admin
+module.exports = new Docs();

package/src/docs/DocsServiceProvider.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const ServiceProvider = require('../providers/ServiceProvider');
+const Docs            = require('./Docs');
+const { ApiResource, ApiEndpoint, ApiField } = require('./resources/ApiResource');
+
+/**
+ * DocsServiceProvider
+ *
+ * Boots the docs panel and wires it to the live RouteRegistry.
+ *
+ * ── Usage (bootstrap/app.js) ─────────────────────────────────────────────────
+ *
+ *   module.exports = Millas.config()
+ *     .providers([AppServiceProvider])
+ *     .withDocs()
+ *     .create();
+ *
+ * ── Optional config/docs.js ──────────────────────────────────────────────────
+ *
+ *   module.exports = {
+ *     prefix:  '/docs',
+ *     title:   'My App API',
+ *     enabled: process.env.NODE_ENV !== 'production',
+ *     auth:    false,   // set true to require admin login
+ *   };
+ *
+ * ── Registering ApiResources ─────────────────────────────────────────────────
+ *
+ *   // In AppServiceProvider.boot():
+ *   const { Docs } = require('millas/src/docs');
+ *   Docs.registerMany([ UserApiResource, PropertyApiResource ]);
+ *
+ *   // Or in a dedicated bootstrap/docs.js:
+ *   const { Docs } = require('millas/src/docs');
+ *   require('../app/docs')(Docs);   // passes Docs to a registration file
+ */
+class DocsServiceProvider extends ServiceProvider {
+  register(container) {
+    container.instance('Docs',        Docs);
+    container.instance('ApiResource', ApiResource);
+    container.instance('ApiEndpoint', ApiEndpoint);
+    container.instance('ApiField',    ApiField);
+  }
+
+  async boot(container) {
+    const basePath = container.make('basePath') || process.cwd();
+
+    // Load optional config/docs.js
+    let docsConfig = {};
+    try { docsConfig = require(basePath + '/config/docs'); } catch { /* optional */ }
+
+    // Resolve the admin prefix so PageHandler can point BI CSS at the
+    // admin's local vendor directory instead of an external CDN.
+    let adminPrefix = '/admin';
+    try {
+      const adminConfig = require(basePath + '/config/admin');
+      if (adminConfig.prefix) adminPrefix = adminConfig.prefix;
+    } catch { /* no config/admin.js — use default */ }
+
+    Docs.configure({
+      prefix:      docsConfig.prefix  || '/docs',
+      title:       docsConfig.title   || process.env.APP_NAME || 'API Docs',
+      enabled:     docsConfig.enabled !== undefined ? docsConfig.enabled : (process.env.NODE_ENV !== 'production'),
+      auth:        docsConfig.auth    || false,
+      adminPrefix,
+      ...docsConfig,
+    });
+
+    // Wire the live RouteRegistry so Docs can auto-discover routes at mount time
+    try {
+      const app = container.make('app');
+      if (app && app.route && typeof app.route.getRegistry === 'function') {
+        Docs.setRouteRegistry(app.route.getRegistry());
+      }
+    } catch { /* app not yet fully wired — will be set during mount */ }
+  }
+}
+
+module.exports = DocsServiceProvider;