millas 0.2.16 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "millas",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "A modern batteries-included backend framework for Node.js — built on Express, inspired by Laravel, Django, and FastAPI",
   "main": "src/index.js",
   "exports": {

package/src/http/middleware/UploadMiddleware.js

@@ -11,20 +11,27 @@
  * installed if you actually handle uploads — multer is listed as an optional
  * peer dependency).
  *
- * ── Auto-injection (recommended) ─────────────────────────────────────────────
+ * ── Usage patterns ───────────────────────────────────────────────────────────
  *
- *   When a route shape has encoding: 'multipart' or any file() field in its
- *   "in" schema, the Router injects UploadMiddleware automatically.
- *   You never touch it.
+ *   1. No shape, no config — just add 'upload' to middleware:
  *
- *   Route.post('/media/upload', MediaController, 'upload')
- *     .shape({
- *       label: 'Upload media',
- *       encoding: 'multipart',
- *       in: {
- *         file: file().required().maxSize('50mb').mimeType(['image/jpeg','image/png','video/mp4']),
- *       },
- *     });
+ *      Route.post('/media/upload', ['auth', 'upload'], MediaController, 'upload');
+ *
+ *      async upload({ file, files, user }) {
+ *        // file  — first uploaded file (any field name), UploadedFile instance
+ *        // files — all files keyed by field name
+ *        const path = await file.store('media');
+ *      }
+ *
+ *   2. Parameterized alias — configure field/count inline:
+ *
+ *      'upload'           → any field, 50 MB limit  (default)
+ *      'upload:avatar'    → single field named 'avatar'
+ *      'upload:photos,5'  → field 'photos', up to 5 files
+ *
+ *      Route.post('/avatar', ['auth', 'upload:avatar'], UserController, 'updateAvatar');
+ *
+ *   3. With a shape — Router auto-injects UploadMiddleware, zero manual config:
  *
  *   async upload({ body, file, user }) {
  *     // file is a multer file object: { buffer, mimetype, size, originalname }
@@ -87,13 +94,14 @@ class UploadMiddleware {
    */
   constructor(options = {}) {
     this._options = {
-      field:   options.field   || 'file',
-      fields:  options.fields  || null,
-      any:     options.any     || false,
-      maxSize: options.maxSize !== undefined ? _parseSize(options.maxSize) : 50 * 1024 * 1024,
-      storage: options.storage || 'memory',
-      dest:    options.dest    || null,
-      filter:  options.filter  || null,
+      field:          options.field   || 'file',
+      _explicitField: !!options.field,          // true only when caller set field explicitly
+      fields:         options.fields  || null,
+      any:            options.any     || false,
+      maxSize:        options.maxSize !== undefined ? _parseSize(options.maxSize) : 50 * 1024 * 1024,
+      storage:        options.storage || 'memory',
+      dest:           options.dest    || null,
+      filter:         options.filter  || null,
     };
     this._multerInstance = null;
   }
@@ -106,15 +114,28 @@ class UploadMiddleware {
    *
    * Because multer is Express middleware internally, we reach into ctx.req.raw
    * to get the underlying Express req/res and call multer directly.
+   *
+   * Skips gracefully when the request is not multipart/form-data so that
+   * non-upload requests to the same route (or misconfigured clients) get a
+   * clear 400 rather than a multer internal error.
    */
   async handle(ctx, next) {
+    const expressReq  = ctx.req.raw;
+    const contentType = expressReq.headers?.['content-type'] || '';
+
+    // Skip multer entirely for non-multipart requests.
+    // ctx.file / ctx.files stay null/{} — the handler or shape validation
+    // will surface a missing-required-field error if needed.
+    if (!contentType.includes('multipart/form-data')) {
+      return next();
+    }
+
     const multerMw = this._getMulterMiddleware();
-    const expressReq = ctx.req.raw;
 
     await new Promise((resolve, reject) => {
       // multer needs a real Express res object; we synthesize a minimal one
-      // that satisfies multer's internal usage (it only calls res.end / statusCode
-      // on hard errors, which we convert to thrown exceptions via reject).
+      // that satisfies multer's internal usage (it only calls res.end /
+      // statusCode on hard errors, which we convert to thrown exceptions).
       const fakeRes = _buildFakeRes(reject);
       multerMw(expressReq, fakeRes, (err) => {
         if (err) return reject(err);
@@ -136,14 +157,45 @@ class UploadMiddleware {
     expressReq._millaFile  = file;
     expressReq._millaFiles = files;
 
-    // req.body is already a live reference — multer mutated it in-place,
-    // so non-file form fields are automatically visible via ctx.body.
+    // Also update ctx.body with any non-file multipart fields multer parsed.
+    // req.body is mutated in-place by multer, but ctx.body was built at
+    // RequestContext construction time. Reassign so the handler sees the fields.
+    if (expressReq.body && typeof expressReq.body === 'object') {
+      // Merge multer-parsed text fields into the existing ctx.body object
+      // without breaking the .validate() / .only() / .except() helpers
+      // that _buildBody attached as non-enumerable properties.
+      Object.assign(ctx.body, expressReq.body);
+    }
 
     return next();
   }
 
   // ── Static factory helpers ──────────────────────────────────────────────────
 
+  /**
+   * Build an UploadMiddleware from parameterized alias string parts.
+   * Called by MiddlewareRegistry when the alias includes parameters.
+   *
+   *   'upload'              → any field, 50 MB limit  (default)
+   *   'upload:avatar'       → single field named 'avatar'
+   *   'upload:photos,5'     → field 'photos', up to 5 files
+   *   'upload:*'            → any field (explicit)
+   *
+   * @param {string[]} params  Parts after the colon, split by comma
+   * @returns {UploadMiddleware}
+   */
+  static fromParams(params) {
+    if (!params || !params.length || params[0] === '*') {
+      return new UploadMiddleware({ any: true });
+    }
+    const field    = params[0];
+    const maxCount = params[1] ? parseInt(params[1], 10) : 1;
+    if (maxCount > 1) {
+      return new UploadMiddleware({ fields: [{ name: field, maxCount }] });
+    }
+    return new UploadMiddleware({ field });
+  }
+
   /**
    * Build an UploadMiddleware from a shape definition.
    * Called internally by the Router when auto-injecting.
@@ -208,8 +260,10 @@ class UploadMiddleware {
 
     const upload = multer(multerConfig);
 
-    // Pick the right multer handler based on options
-    if (any) {
+    // Pick the right multer handler based on options.
+    // When used without a shape (e.g. just 'upload' alias), default to .any()
+    // so the handler receives whatever field the client sends, regardless of name.
+    if (any || (!fields && this._options.field === 'file' && !this._options._explicitField)) {
       this._multerInstance = upload.any();
     } else if (fields) {
       this._multerInstance = upload.fields(fields);