millas 0.2.13 → 0.2.14

package/src/router/RouteEntry.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const { isShape } = require('../http/Shape');
+
+/**
+ * RouteEntry
+ *
+ * A thin wrapper returned by Route.get/post/put/patch/delete/resource.
+ * Exposes .shape() and .fromShape() for attaching a shape definition,
+ * then writes it back to the registry entry.
+ *
+ * The Route instance itself is passed in so group-level chaining still
+ * works — .shape() returns the RouteEntry, but the Route is unaffected.
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   Route.post('/properties', PropertyController, 'store')
+ *     .shape({ label: 'Create property', in: { name: string().required() }, out: {} });
+ *
+ *   Route.post('/properties', PropertyController, 'store')
+ *     .fromShape(CreatePropertyShape);
+ */
+class RouteEntry {
+  /**
+   * @param {object} entry   — the raw entry object stored in RouteRegistry
+   * @param {Route}  router  — the Route instance (for method chaining back)
+   */
+  constructor(entry, router) {
+    this._entry  = entry;
+    this._router = router;
+  }
+
+  /**
+   * Attach an inline shape definition to this route.
+   *
+   *   Route.post('/users', UserController, 'store')
+   *     .shape({
+   *       label: 'Create user',
+   *       group: 'Users',
+   *       in:  { email: email().required() },
+   *       out: { 201: { id: 1 } },
+   *     });
+   *
+   * The "in" schema runs as validation middleware before the handler.
+   * If validation fails, 422 is returned immediately.
+   * The handler receives clean, coerced data via { body }.
+   *
+   * @param {object} def — plain shape definition OR a shape() result
+   * @returns {RouteEntry}
+   */
+  shape(def) {
+    // Accept both raw objects and shape() factory results
+    // If raw object, wrap through shape() for validation + freezing
+    if (!isShape(def)) {
+      const { shape: makeShape } = require('../http/Shape');
+      def = makeShape(def);
+    }
+    this._entry.shape = def;
+    return this;
+  }
+
+  /**
+   * Attach a pre-built shape from a shapes file.
+   * Identical to .shape() — exists for readability and convention.
+   *
+   *   const { CreatePropertyShape } = require('../app/shapes/PropertyShape');
+   *   Route.post('/properties', PropertyController, 'store')
+   *     .fromShape(CreatePropertyShape);
+   *
+   * @param {object} shapeDefinition — result of shape() factory
+   * @returns {RouteEntry}
+   */
+  fromShape(shapeDefinition) {
+    return this.shape(shapeDefinition);
+  }
+
+  /**
+   * Add extra middleware to this specific route after registration.
+   * Middleware aliases are appended to the existing list.
+   *
+   * @param {string|string[]} middleware
+   * @returns {RouteEntry}
+   */
+  middleware(mw) {
+    const list = Array.isArray(mw) ? mw : [mw];
+    this._entry.middleware = [...(this._entry.middleware || []), ...list];
+    return this;
+  }
+}
+
+module.exports = RouteEntry;

package/src/router/Router.js

@@ -67,7 +67,17 @@ class Router {
 
   _bindRoute(route) {
     const middlewareHandlers = this._resolveMiddleware(route.middleware || []);
-    const terminalHandler    = this._resolveTerminalHandler(
+
+    // ── Shape validation middleware ────────────────────────────────────────
+    // If the route has a .shape() / .fromShape() declaration, inject a
+    // validation middleware that runs BEFORE the handler.
+    // On failure → 422 immediately, handler never runs.
+    // On success → ctx.body is replaced with coerced, validated output.
+    const shapeMiddlewares = route.shape
+      ? this._buildShapeMiddleware(route.shape)
+      : [];
+
+    const terminalHandler = this._resolveTerminalHandler(
       route.handler,
       route.method,
       route.verb,
@@ -77,10 +87,70 @@ class Router {
 
     this._adapter.mountRoute(route.verb, route.path, [
       ...middlewareHandlers,
+      ...shapeMiddlewares,
       terminalHandler,
     ]);
   }
 
+  /**
+   * Build Express middleware functions from a shape definition.
+   * Returns an array of 0, 1, or 2 middleware functions
+   * (one for body/in, one for query) depending on what the shape declares.
+   *
+   * @param {import('../http/Shape').ShapeDefinition} shape
+   * @returns {Function[]}
+   */
+  _buildShapeMiddleware(shape) {
+    const { Validator } = require('../validation/Validator');
+    const middlewares   = [];
+
+    // ── Body / in validation ───────────────────────────────────────────────
+    if (shape.in && Object.keys(shape.in).length) {
+      middlewares.push(async (req, res, next) => {
+        try {
+          const rawBody = req.body || {};
+          const clean   = await Validator.validate(rawBody, shape.in);
+          // Replace req.body with the coerced, validated subset so the
+          // handler's { body } destructure gets clean data automatically.
+          req.body = clean;
+          next();
+        } catch (err) {
+          // ValidationError → 422, any other error → pass to error handler
+          if (err.code === 'EVALIDATION' || err.name === 'ValidationError') {
+            return res.status(422).json({
+              status:  422,
+              message: 'Validation failed',
+              errors:  err.errors || {},
+            });
+          }
+          next(err);
+        }
+      });
+    }
+
+    // ── Query validation ───────────────────────────────────────────────────
+    if (shape.query && Object.keys(shape.query).length) {
+      middlewares.push(async (req, res, next) => {
+        try {
+          const clean = await Validator.validate(req.query || {}, shape.query);
+          req.query   = clean;
+          next();
+        } catch (err) {
+          if (err.code === 'EVALIDATION' || err.name === 'ValidationError') {
+            return res.status(422).json({
+              status:  422,
+              message: 'Validation failed',
+              errors:  err.errors || {},
+            });
+          }
+          next(err);
+        }
+      });
+    }
+
+    return middlewares;
+  }
+
   _resolveMiddleware(list) {
     return list.map(alias => {
       try {

package/src/scaffold/maker.js

@@ -262,6 +262,141 @@ module.exports = {
   return write(filePath, content);
 }
 
+
+async function makeShape(name) {
+  const baseName  = name.endsWith('Shape') ? name : (name + 'Shape');
+  const className = pascalCase(baseName);
+  const filePath  = resolveAppPath('app/shapes', className + '.js');
+  const groupBase = className.replace(/Shape$/, '');
+  const group     = groupBase + 's';
+
+  const lines = [
+    "'use strict';",
+    '',
+    "const { shape }                               = require('millas/core/http');",
+    "const { string, number, boolean, array, email, date } = require('millas/core/validation');",
+    '',
+    '/**',
+    ' * ' + className,
+    ' *',
+    ' * Route input/output contracts for ' + groupBase + ' endpoints.',
+    ' *',
+    ' * Usage:',
+    ' *   Route.post(\'/path\', ' + groupBase + 'Controller, \'store\').fromShape(Create' + groupBase + 'Shape);',
+    ' *   Route.put(\'/path/:id\', ' + groupBase + 'Controller, \'update\').fromShape(Update' + groupBase + 'Shape);',
+    ' *',
+    ' * The "in" schema validates the request body before the handler runs.',
+    ' * Failures return 422 automatically. Use { body } in your handler — it is clean.',
+    ' */',
+    '',
+    'const Create' + groupBase + 'Shape = shape({',
+    "  label:       'Create " + groupBase.toLowerCase() + "',",
+    "  group:       '" + group + "',",
+    '  description: null,',
+    '  in: {',
+    '    // name:   string().required().max(200).example(\'My ' + groupBase + '\'),',
+    '    // email:  email().required().example(\'user@example.com\'),',
+    '    // count:  number().required().min(1).example(1),',
+    '    // active: boolean().optional().example(true),',
+    "    // tags:   array().of(string()).optional().example(['tag1', 'tag2']),",
+    "    // type:   string().required().oneOf(['option_a', 'option_b']),",
+    '  },',
+    '  out: {',
+    '    201: { id: 1 },',
+    "    422: { message: 'Validation failed', errors: {} },",
+    '  },',
+    '});',
+    '',
+    'const Update' + groupBase + 'Shape = shape({',
+    "  label:       'Update " + groupBase.toLowerCase() + "',",
+    "  group:       '" + group + "',",
+    '  in: {',
+    '    // name: string().optional().max(200),',
+    '  },',
+    '  out: {',
+    '    200: { id: 1 },',
+    "    422: { message: 'Validation failed', errors: {} },",
+    '  },',
+    '});',
+    '',
+    'module.exports = { Create' + groupBase + 'Shape, Update' + groupBase + 'Shape };',
+  ];
+
+  return write(filePath, lines.join('\n'));
+}
+async function makeCommand(name) {
+  // If name contains ':' it's a namespaced signature like 'email:SendDigest'.
+  // Split off the namespace prefix and use only the last segment for the
+  // class name / filename, but keep the full input as the signature.
+  const parts      = name.split(':');
+  const basePart   = parts[parts.length - 1];                        // e.g. 'SendDigest'
+  const cleanBase  = basePart.replace(/Command$/i, '');              // strip trailing Command
+  const className  = pascalCase(cleanBase) + 'Command';              // e.g. 'SendDigestCommand'
+
+  // Build signature from the full name:
+  //   'email:SendDigest' → 'email:digest'
+  //   'SendDigest'       → 'send-digest'
+  //   'send-digest'      → 'send-digest'
+  const signatureParts = name
+    .replace(/Command$/i, '')
+    .split(':')
+    .map((seg, i, arr) => {
+      // Last segment: strip camelCase — 'SendDigest' → 'send-digest'
+      if (i === arr.length - 1) {
+        return seg
+          .replace(/([a-z])([A-Z])/g, '$1-$2')
+          .toLowerCase();
+      }
+      // Namespace segments: lowercase as-is
+      return seg.toLowerCase();
+    });
+  const signature = signatureParts.join(':');
+
+  const filePath = resolveAppPath('app/commands', `${className}.js`);
+
+  const content = `'use strict';
+
+const { Command } = require('millas/console');
+
+/**
+ * ${className}
+ *
+ * Run with:  millas call ${signature}
+ */
+class ${className} extends Command {
+  static signature   = '${signature}';
+  static description = 'Description of ${signature}';
+
+  // Optional: positional arguments
+  // static args = [
+  //   { name: 'target', description: 'The target to act on', default: 'all' },
+  // ];
+
+  // Optional: named options / flags
+  // static options = [
+  //   { flag: '--dry-run',    description: 'Preview without making changes' },
+  //   { flag: '--limit <n>',  description: 'Max items to process', default: '50' },
+  // ];
+
+  async handle() {
+    // const target = this.argument('target');
+    // const limit  = this.option('limit');
+    // const dry    = this.option('dryRun');
+
+    this.info('Running ${signature}...');
+
+    // Your command logic here
+
+    this.success('Done.');
+  }
+}
+
+module.exports = ${className};
+`;
+
+  return write(filePath, content);
+}
+
 module.exports = {
   makeController,
   makeModel,
@@ -269,4 +404,6 @@ module.exports = {
   makeService,
   makeJob,
   makeMigration,
-};
+  makeShape,
+  makeCommand,
+};

package/src/scaffold/templates.js

@@ -161,6 +161,18 @@ module.exports = {
   // Set use_i18n: true to enable the translation system.
   // Then run: millas lang:publish <locale>
   use_i18n: false,
+
+  // ── CORS ──────────────────────────────────────────────────────────────────
+  // Uncomment and call .withCors() in bootstrap/app.js to enable.
+  // All values shown are the defaults — only include what you need to change.
+  //
+  // cors: {
+  //   origins:     ['*'],                                          // or ['https://app.example.com']
+  //   methods:     ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  //   headers:     ['Content-Type', 'Authorization', 'X-Requested-With'],
+  //   credentials: false,                                          // true requires explicit origins, not '*'
+  //   maxAge:      86400,                                          // preflight cache in seconds
+  // },
 };
 `,
 

package/src/serializer/Serializer.js

@@ -0,0 +1,239 @@
+'use strict';
+
+/**
+ * Serializer
+ *
+ * Controls the exact shape of API output — what fields go out, what's
+ * nested, and what's hidden. Sits between your model and your JSON response.
+ *
+ * ── Why use a Serializer instead of jsonify(model) ───────────────────────────
+ *
+ *   jsonify(user)            — dumps every column, relies on model.hidden
+ *   UserSerializer.one(user) — precise whitelist, nested relations, custom fields
+ *
+ * ── Defining a Serializer ────────────────────────────────────────────────────
+ *
+ *   const { Serializer } = require('millas/src/serializer/Serializer');
+ *
+ *   class UserSerializer extends Serializer {
+ *     // Whitelist of fields to include. If omitted, all fields are included
+ *     // (minus model.hidden and any fields listed in static hidden below).
+ *     static fields = ['id', 'name', 'email', 'role', 'created_at'];
+ *
+ *     // Extra fields to exclude on top of model.hidden.
+ *     // Only needed when static fields is not set.
+ *     static hidden = ['internal_notes', 'stripe_customer_id'];
+ *
+ *     // Nested serializers — keyed by the relation name on the model.
+ *     // The relation must be eager-loaded (.with('roles')) before serializing.
+ *     // If the relation is not loaded, the key is silently omitted.
+ *     static nested = {
+ *       roles:   RoleSerializer,
+ *       profile: ProfileSerializer,
+ *     };
+ *
+ *     // Computed fields — functions that receive the model instance and
+ *     // return an additional value not stored on the model.
+ *     static computed = {
+ *       full_name: (user) => `${user.first_name} ${user.last_name}`,
+ *       is_admin:  (user) => user.role === 'admin',
+ *     };
+ *   }
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   // Single record
+ *   const user = await User.with('roles', 'profile').find(id);
+ *   return jsonify(UserSerializer.one(user));
+ *
+ *   // Collection
+ *   const users = await User.with('roles').all();
+ *   return jsonify(UserSerializer.many(users));
+ *
+ *   // Paginated
+ *   const result = await User.with('roles').paginate(page, perPage);
+ *   return jsonify(UserSerializer.paginate(result));
+ *
+ *   // With request context (for conditional fields)
+ *   return jsonify(UserSerializer.one(user, { req }));
+ *
+ * ── Nested relations ──────────────────────────────────────────────────────────
+ *
+ *   The relation must be eager-loaded first. If not loaded, it is skipped.
+ *
+ *   // WRONG — roles not loaded, will be silently omitted
+ *   const user = await User.find(id);
+ *   UserSerializer.one(user);
+ *
+ *   // CORRECT — roles eager-loaded, will be serialized through RoleSerializer
+ *   const user = await User.with('roles').find(id);
+ *   UserSerializer.one(user);
+ *
+ * ── Conditional fields ────────────────────────────────────────────────────────
+ *
+ *   Override the instance method serialize(instance, ctx) for per-request logic:
+ *
+ *   class UserSerializer extends Serializer {
+ *     static fields = ['id', 'name', 'email'];
+ *
+ *     serialize(instance, ctx = {}) {
+ *       const data = super.serialize(instance, ctx);
+ *       if (ctx.req?.user?.is_admin) {
+ *         data.internal_notes = instance.internal_notes;
+ *       }
+ *       return data;
+ *     }
+ *   }
+ */
+class Serializer {
+  /**
+   * Whitelist of field names to include.
+   * When set, ONLY these fields appear in output (plus computed + nested).
+   * When null/undefined, all fields are included minus hidden ones.
+   *
+   * @type {string[]|null}
+   */
+  static fields = null;
+
+  /**
+   * Extra fields to exclude, on top of the model's static hidden list.
+   * Only relevant when static fields is not set.
+   *
+   * @type {string[]}
+   */
+  static hidden = [];
+
+  /**
+   * Nested serializers, keyed by relation name.
+   * The relation must be eager-loaded before calling serialize().
+   * If the value on the instance is a function (lazy-loaded), it is skipped.
+   *
+   * @type {Object.<string, typeof Serializer>}
+   */
+  static nested = {};
+
+  /**
+   * Computed fields — functions that receive the model instance and
+   * optional context, returning a value to include in output.
+   *
+   * @type {Object.<string, function(instance, ctx): *>}
+   */
+  static computed = {};
+
+  // ── Core serialization ─────────────────────────────────────────────────────
+
+  /**
+   * Serialize a single model instance.
+   * Override this instance method for per-request conditional logic.
+   *
+   * @param {object} instance  — model instance or plain object
+   * @param {object} [ctx]     — optional context (e.g. { req })
+   * @returns {object}
+   */
+  serialize(instance, ctx = {}) {
+    if (!instance) return null;
+
+    const ctor   = this.constructor;
+    const raw    = typeof instance.toJSON === 'function' ? instance.toJSON() : { ...instance };
+    const result = {};
+
+    // ── Field whitelist or full set ─────────────────────────────────────────
+    if (ctor.fields && ctor.fields.length) {
+      // Whitelist mode — only declared fields
+      for (const key of ctor.fields) {
+        if (key in raw) {
+          result[key] = raw[key];
+        }
+      }
+    } else {
+      // All-fields mode — exclude serializer.hidden on top of model.hidden
+      // (model.hidden is already applied by toJSON())
+      const hiddenSet = new Set(ctor.hidden || []);
+      for (const [key, value] of Object.entries(raw)) {
+        if (!hiddenSet.has(key)) {
+          result[key] = value;
+        }
+      }
+    }
+
+    // ── Computed fields ─────────────────────────────────────────────────────
+    for (const [key, fn] of Object.entries(ctor.computed || {})) {
+      result[key] = fn(instance, ctx);
+    }
+
+    // ── Nested serializers ──────────────────────────────────────────────────
+    for (const [key, NestedSerializer] of Object.entries(ctor.nested || {})) {
+      const value = instance[key];
+
+      // Skip if not loaded (still a function = lazy-load accessor)
+      if (typeof value === 'function') continue;
+      // Skip if not present
+      if (value === undefined) continue;
+
+      const nested = new NestedSerializer();
+
+      if (value === null) {
+        result[key] = null;
+      } else if (Array.isArray(value)) {
+        result[key] = value.map(item => nested.serialize(item, ctx));
+      } else {
+        result[key] = nested.serialize(value, ctx);
+      }
+    }
+
+    return result;
+  }
+
+  // ── Static convenience methods ─────────────────────────────────────────────
+
+  /**
+   * Serialize a single model instance.
+   *
+   *   UserSerializer.one(user)
+   *   UserSerializer.one(user, { req })
+   *
+   * @param {object} instance
+   * @param {object} [ctx]
+   * @returns {object|null}
+   */
+  static one(instance, ctx = {}) {
+    if (!instance) return null;
+    return new this().serialize(instance, ctx);
+  }
+
+  /**
+   * Serialize an array of model instances.
+   *
+   *   UserSerializer.many(users)
+   *   UserSerializer.many(users, { req })
+   *
+   * @param {object[]} instances
+   * @param {object}   [ctx]
+   * @returns {object[]}
+   */
+  static many(instances, ctx = {}) {
+    if (!instances || !instances.length) return [];
+    const s = new this();
+    return instances.map(i => s.serialize(i, ctx));
+  }
+
+  /**
+   * Serialize a paginated result from Model.paginate() or QueryBuilder.paginate().
+   * Preserves the pagination meta and wraps data through the serializer.
+   *
+   *   const result = await User.with('roles').paginate(page, perPage);
+   *   return jsonify(UserSerializer.paginate(result));
+   *
+   * @param {{ data: object[], meta: object }} result
+   * @param {object} [ctx]
+   * @returns {{ data: object[], meta: object }}
+   */
+  static paginate(result, ctx = {}) {
+    return {
+      data: this.many(result.data || [], ctx),
+      meta: result.meta || {},
+    };
+  }
+}
+
+module.exports = { Serializer };