@asterflow/multipart 1.1.0

package/README.md

@@ -0,0 +1,75 @@
+<div align="center">
+
+# @asterflow/multipart
+
+![license-info](https://img.shields.io/github/license/AsterFlow/AsterFlow?style=for-the-badge&colorA=302D41&colorB=f9e2af&logoColor=f9e2af)
+![stars-info](https://img.shields.io/github/stars/AsterFlow/AsterFlow?colorA=302D41&colorB=f9e2af&style=for-the-badge)
+![last-commit](https://img.shields.io/github/last-commit/AsterFlow/AsterFlow?path=plugins%2Fmultipart&style=for-the-badge&colorA=302D41&colorB=b4befe)
+
+![bundle-size](https://img.shields.io/bundlejs/size/@asterflow/multipart?style=for-the-badge&colorA=302D41&colorB=3ac97b)
+
+</div>
+
+> Parses `multipart/form-data` requests before your handler runs, with optional per-route field rules that are checked at runtime and enforced in the handler's types.
+
+## 📦 Installation
+
+```bash
+bun install @asterflow/multipart
+```
+
+Register the plugin on an AsterFlow app:
+
+```ts
+import { AsterFlow } from 'asterflow'
+import { multipartPlugin } from '@asterflow/multipart'
+
+const app = new AsterFlow()
+  .use(multipartPlugin, { limits: { fileSize: 10 * 1024 * 1024 } })
+```
+
+### ✨ Features
+
+- **Automatic parsing** - any `multipart/form-data` request is parsed with `busboy` before it reaches your route.
+- **Per-route criteria** - calling `.multipart({...})` on `Method.create(...)` (or inside a `Router.builder(...).method(...)` chain) validates fields at runtime and narrows `getFile`/`getFiles` in that handler's types - a `required` field types as always-present, a declared `mimeTypes` list narrows `.mimeType`.
+- **Request extensions** - `request.body`, `request.files`, `request.getFile()`, `request.getFiles()`, `request.hasFiles()`, `request.getFilesByType()`, `request.saveAll()` and `request.cleanupMultipart()` are attached directly onto `request`, no wrapper object.
+- **Streaming storage** - files stream into memory or to disk (`fileHandling.keepInMemory`), never buffered twice.
+- **Automatic cleanup** - temp files written to disk are removed after the response is sent.
+- **Standardized errors** - limit, MIME/extension and required-field failures all reject with the same `{ error, code, message }` shape before your handler runs.
+
+## ❓ How to Use
+
+Declare a route's fields with `.multipart(schema)` - the handler only runs once the request passes that schema, and `getFile`/`getFiles` are typed to match it:
+
+```ts
+import { Method } from '@asterflow/router'
+
+export default Method.create(Method.POST, { path: '/avatar' })
+  .multipart({
+    avatar: { mimeTypes: ['image/png', 'image/jpeg'], maxSize: 5 * 1024 * 1024, required: true }
+  })
+  .handler(({ request, response }) => {
+    const avatar = request.getFile('avatar') // always present, mimeType narrowed
+    return response.success({ filename: avatar.filename, size: avatar.size })
+  })
+```
+
+Without a declared schema, the same methods are still there on `request`, just optional and unnarrowed:
+
+```ts
+export default Method.create(Method.POST, { path: '/upload' }).handler(({ request, response }) => {
+  if (!request.hasFiles?.()) return response.badRequest({ error: 'NO_FILES' })
+  return response.success({ files: request.files, fields: request.body })
+})
+```
+
+## 🔗 Related Packages
+
+- [@asterflow/plugin](https://www.npmjs.com/package/@asterflow/plugin) - built as a plugin with `Plugin.create()`
+- [@asterflow/router](https://www.npmjs.com/package/@asterflow/router) - adds `.multipart(...)` to `Method` and `RouteMethodBuilder` via declaration merging
+- [@asterflow/request](https://www.npmjs.com/package/@asterflow/request) - extends `AsterRequest` via `.extend()` to attach parsed multipart data
+- [@asterflow/response](https://www.npmjs.com/package/@asterflow/response) - returns `AsterResponse` errors for malformed or rejected multipart requests
+
+## 📄 License
+
+This project is licensed under the [MIT License](../../LICENSE).

package/dist/cjs/index.cjs

@@ -0,0 +1,437 @@
+"use strict";
+var W = Object.create;
+var L = Object.defineProperty;
+var ee = Object.getOwnPropertyDescriptor;
+var te = Object.getOwnPropertyNames;
+var ie = Object.getPrototypeOf, re = Object.prototype.hasOwnProperty;
+var ne = (t, e) => {
+  for (var i in e)
+    L(t, i, { get: e[i], enumerable: !0 });
+}, O = (t, e, i, r) => {
+  if (e && typeof e == "object" || typeof e == "function")
+    for (let s of te(e))
+      !re.call(t, s) && s !== i && L(t, s, { get: () => e[s], enumerable: !(r = ee(e, s)) || r.enumerable });
+  return t;
+};
+var oe = (t, e, i) => (i = t != null ? W(ie(t)) : {}, O(
+  e || !t || !t.__esModule ? L(i, "default", { value: t, enumerable: !0 }) : i,
+  t
+)), se = (t) => O(L({}, "__esModule", { value: !0 }), t);
+// plugins/multipart/src/index.ts
+var me = {};
+ne(me, {
+  DEFAULT_CONFIG: () => b,
+  ErrorCodes: () => n,
+  MultipartError: () => o,
+  MultipartParser: () => v,
+  default: () => fe,
+  errorResponse: () => A,
+  multipartPlugin: () => K,
+  parseMultipart: () => k,
+  resolveConfig: () => R,
+  validateFields: () => D
+});
+module.exports = se(me);
+var G = require("@asterflow/plugin"), P = require("@asterflow/router"), J = require("fs/promises"), Q = require("os");
+// plugins/multipart/package.json
+var z = "1.1.0";
+// plugins/multipart/src/controllers/multipartExtension.ts
+var x = require("@asterflow/router"), $ = !1;
+function B() {
+  return $ || ($ = !0, x.Method.prototype.multipart = function(t) {
+    return this.extend({}, { multipart: t });
+  }, x.RouteMethodBuilder.prototype.multipart = function(t) {
+    return this.extend({}, { multipart: t });
+  }), !0;
+}
+// plugins/multipart/src/types/multipart.ts
+var b = {
+  limits: {
+    fieldNameSize: 100,
+    fieldSize: 1048576,
+    fields: 1 / 0,
+    fileSize: 10485760,
+    files: 10,
+    parts: 1 / 0
+  },
+  fileHandling: {
+    keepInMemory: !0
+  },
+  validation: {
+    allowedMimeTypes: [],
+    allowedExtensions: []
+  }
+};
+function R(t, e) {
+  return {
+    limits: {
+      ...b.limits,
+      ...t.limits
+    },
+    fileHandling: {
+      keepInMemory: !0,
+      tempDir: e,
+      ...t.fileHandling
+    },
+    validation: {
+      ...b.validation,
+      ...t.validation
+    }
+  };
+}
+var n = {
+  LIMIT_FILE_SIZE: "LIMIT_FILE_SIZE",
+  LIMIT_FILE_COUNT: "LIMIT_FILE_COUNT",
+  LIMIT_FIELD_SIZE: "LIMIT_FIELD_SIZE",
+  LIMIT_FIELD_COUNT: "LIMIT_FIELD_COUNT",
+  LIMIT_PARTS: "LIMIT_PARTS",
+  INVALID_MIME_TYPE: "INVALID_MIME_TYPE",
+  INVALID_EXTENSION: "INVALID_EXTENSION",
+  VALIDATION_FAILED: "VALIDATION_FAILED",
+  FIELD_REQUIRED: "FIELD_REQUIRED",
+  FIELD_TOO_MANY_FILES: "FIELD_TOO_MANY_FILES",
+  PARSE_ERROR: "PARSE_ERROR"
+}, o = class extends Error {
+  code;
+  details;
+  constructor(e, i, r) {
+    super(e), this.name = "MultipartError", this.code = i, this.details = r;
+  }
+};
+// plugins/multipart/src/controllers/validateMultipartFields.ts
+function D(t, e) {
+  for (let [i, r] of Object.entries(e)) {
+    let s = t.files.filter((u) => u.fieldName === i), c = r.multiple ?? !1;
+    if ((r.required ?? !1) && s.length === 0)
+      throw new o(`Field "${i}" is required`, n.FIELD_REQUIRED, { field: i });
+    if (!c && s.length > 1)
+      throw new o(
+        `Field "${i}" accepts only a single file`,
+        n.FIELD_TOO_MANY_FILES,
+        { field: i, count: s.length }
+      );
+    for (let u of s) {
+      if (r.mimeTypes && !r.mimeTypes.includes(u.mimeType))
+        throw new o(
+          `Field "${i}" has unsupported MIME type: ${u.mimeType}`,
+          n.INVALID_MIME_TYPE,
+          { field: i, mimeType: u.mimeType }
+        );
+      if (r.extensions && !r.extensions.map((d) => d.toLowerCase()).includes(u.extension.toLowerCase()))
+        throw new o(
+          `Field "${i}" has unsupported extension: ${u.extension}`,
+          n.INVALID_EXTENSION,
+          { field: i, extension: u.extension }
+        );
+      if (r.maxSize && u.size > r.maxSize)
+        throw new o(
+          `Field "${i}" exceeds max size of ${r.maxSize} bytes`,
+          n.LIMIT_FILE_SIZE,
+          { field: i, size: u.size, maxSize: r.maxSize }
+        );
+    }
+  }
+}
+// plugins/multipart/src/controllers/MultipartParser.ts
+var C = oe(require("busboy"), 1), H = require("crypto"), w = require("fs"), y = require("fs/promises"), j = require("os"), M = require("path"), Y = require("stream"), T = require("stream/promises");
+// plugins/multipart/src/utils/stream.ts
+var q = require("stream");
+function U(t) {
+  return typeof t == "object" && t !== null && typeof t.pipe == "function";
+}
+function ue(t) {
+  return typeof t == "object" && t !== null && typeof t.headers?.forEach == "function" && "body" in t;
+}
+function V(t) {
+  if (U(t)) return t;
+  let e = t?.raw;
+  if (U(e)) return e;
+  if (ue(t)) {
+    let i = t.body;
+    return i ? q.Readable.fromWeb(i) : null;
+  }
+  throw new o(
+    "Unsupported request type for multipart parsing",
+    n.PARSE_ERROR
+  );
+}
+// plugins/multipart/src/controllers/MultipartParser.ts
+var pe = C.default ?? C, _ = class {
+  fieldName;
+  filename;
+  encoding;
+  mimeType;
+  size;
+  extension;
+  buffer;
+  tempPath;
+  constructor(e) {
+    this.fieldName = e.fieldName, this.filename = e.filename, this.encoding = e.encoding, this.mimeType = e.mimeType, this.size = e.size, this.extension = e.extension, this.buffer = e.buffer, this.tempPath = e.tempPath;
+  }
+  async toBuffer() {
+    if (this.buffer) return this.buffer;
+    if (this.tempPath) return (0, y.readFile)(this.tempPath);
+    throw new Error(`No data available for file "${this.filename}"`);
+  }
+  async save(e) {
+    if (await (0, y.mkdir)((0, M.dirname)(e), { recursive: !0 }), this.buffer) {
+      await (0, y.writeFile)(e, this.buffer);
+      return;
+    }
+    if (this.tempPath) {
+      await (0, T.pipeline)((0, w.createReadStream)(this.tempPath), (0, w.createWriteStream)(e));
+      return;
+    }
+    throw new Error(`No data available for file "${this.filename}"`);
+  }
+  stream() {
+    if (this.buffer) return Y.Readable.from(this.buffer);
+    if (this.tempPath) return (0, w.createReadStream)(this.tempPath);
+    throw new Error(`No data available for file "${this.filename}"`);
+  }
+}, v = class {
+  config;
+  events;
+  constructor(e = {}, i = {}) {
+    this.config = R(e, e.fileHandling?.tempDir ?? (0, j.tmpdir)()), this.events = i;
+  }
+  async parse(e) {
+    let i = Date.now(), r = V(e.raw);
+    return r ? new Promise((s, c) => {
+      let p = !1, u = 0, f = 0, d = {}, I = [], F = [], a;
+      try {
+        a = pe({ headers: e.getHeaders(), limits: this.config.limits });
+      } catch (l) {
+        c(new o(
+          l instanceof Error ? l.message : "Failed to initialize the multipart parser",
+          n.PARSE_ERROR
+        ));
+        return;
+      }
+      let m = (l) => {
+        if (p) return;
+        p = !0;
+        let g = l instanceof o ? l : new o(
+          l instanceof Error ? l.message : "Unknown multipart parsing error",
+          n.PARSE_ERROR
+        );
+        this.events.onError?.(g), r.unpipe(a), queueMicrotask(() => a.destroy()), c(g);
+      };
+      a.on("field", (l, g, S) => {
+        if (p) return;
+        if (S.valueTruncated) {
+          m(new o(`Field "${l}" exceeds the configured size limit`, n.LIMIT_FIELD_SIZE));
+          return;
+        }
+        this.events.onField?.(l, g);
+        let h = d[l];
+        d[l] = h === void 0 ? g : Array.isArray(h) ? [...h, g] : [h, g], f++;
+      }), a.on("file", (l, g, S) => {
+        if (p) {
+          g.resume();
+          return;
+        }
+        let h = this.consumeFile(l, g, S, m, (E) => {
+          u += E.length, this.events.onProgress?.(u);
+        }).then((E) => {
+          p || !E || (I.push(E), this.events.onFileEnd?.(E));
+        }).catch((E) => m(E));
+        F.push(h);
+      }), a.on("partsLimit", () => m(new o("Parts limit exceeded", n.LIMIT_PARTS))), a.on("filesLimit", () => m(new o("Files limit exceeded", n.LIMIT_FILE_COUNT))), a.on("fieldsLimit", () => m(new o("Fields limit exceeded", n.LIMIT_FIELD_COUNT))), a.on("error", (l) => m(l)), r.on("error", (l) => m(l)), a.on("close", async () => {
+        try {
+          await Promise.all(F);
+        } catch {
+          return;
+        }
+        p || (p = !0, s({
+          fields: d,
+          files: I,
+          metadata: {
+            processingTime: Date.now() - i,
+            totalSize: u,
+            fieldsCount: f,
+            filesCount: I.length
+          }
+        }));
+      }), r.pipe(a);
+    }) : {
+      fields: {},
+      files: [],
+      metadata: { processingTime: Date.now() - i, totalSize: 0, fieldsCount: 0, filesCount: 0 }
+    };
+  }
+  async consumeFile(e, i, r, s, c) {
+    let p = {
+      fieldName: e,
+      filename: r.filename || "unknown",
+      encoding: r.encoding,
+      mimeType: r.mimeType
+    }, u = !1;
+    i.once("limit", () => {
+      u = !0, s(new o(`File "${p.filename}" exceeds the configured size limit`, n.LIMIT_FILE_SIZE));
+    }), i.on("error", (a) => s(a));
+    let f = await this.validateFile(p);
+    if (!f.valid)
+      return i.resume(), s(f.error), null;
+    this.events.onFileStart?.(p);
+    let d = 0, I = (0, M.extname)(p.filename), F = (a) => {
+      d += a.length, c(a), this.events.onFileData?.(p, a);
+    };
+    try {
+      if (this.config.fileHandling.keepInMemory) {
+        let m = [];
+        return i.on("data", (l) => {
+          F(l), m.push(l);
+        }), await (0, T.finished)(i), u ? null : new _({ ...p, size: d, extension: I, buffer: Buffer.concat(m) });
+      }
+      await (0, y.mkdir)(this.config.fileHandling.tempDir, { recursive: !0 });
+      let a = (0, M.join)(this.config.fileHandling.tempDir, `multipart-${(0, H.randomUUID)()}${I}`);
+      return i.on("data", F), await (0, T.pipeline)(i, (0, w.createWriteStream)(a)), u ? null : new _({ ...p, size: d, extension: I, tempPath: a });
+    } catch (a) {
+      return u || s(a), null;
+    }
+  }
+  async validateFile(e) {
+    let { validation: i } = this.config;
+    if (i.allowedMimeTypes && i.allowedMimeTypes.length > 0 && !i.allowedMimeTypes.includes(e.mimeType))
+      return {
+        valid: !1,
+        error: new o(`MIME type "${e.mimeType}" is not allowed`, n.INVALID_MIME_TYPE)
+      };
+    if (i.allowedExtensions && i.allowedExtensions.length > 0) {
+      let r = (0, M.extname)(e.filename).toLowerCase();
+      if (!i.allowedExtensions.some((s) => s.toLowerCase() === r))
+        return {
+          valid: !1,
+          error: new o(`Extension "${r}" is not allowed`, n.INVALID_EXTENSION)
+        };
+    }
+    if (i.validator)
+      try {
+        if (!await i.validator(e))
+          return {
+            valid: !1,
+            error: new o(`File "${e.filename}" failed custom validation`, n.VALIDATION_FAILED)
+          };
+      } catch (r) {
+        return {
+          valid: !1,
+          error: new o(
+            `Validator threw an error: ${r instanceof Error ? r.message : "Unknown error"}`,
+            n.VALIDATION_FAILED
+          )
+        };
+      }
+    return { valid: !0 };
+  }
+};
+async function k(t, e, i) {
+  return new v(e, i).parse(t);
+}
+// plugins/multipart/src/utils/errors.ts
+function A(t, e) {
+  let i = {
+    code: e.code,
+    message: e.message,
+    ...e.details !== void 0 ? { details: e.details } : {}
+  };
+  switch (e.code) {
+    case n.LIMIT_FILE_SIZE:
+    case n.LIMIT_FILE_COUNT:
+    case n.LIMIT_FIELD_SIZE:
+    case n.LIMIT_FIELD_COUNT:
+    case n.LIMIT_PARTS:
+      return t.status(413).json({ error: "PAYLOAD_TOO_LARGE", ...i });
+    case n.INVALID_MIME_TYPE:
+    case n.INVALID_EXTENSION:
+      return t.status(415).json({ error: "UNSUPPORTED_MEDIA_TYPE", ...i });
+    case n.VALIDATION_FAILED:
+    case n.FIELD_REQUIRED:
+    case n.FIELD_TOO_MANY_FILES:
+      return t.validationError({ error: "VALIDATION_FAILED", ...i });
+    default:
+      return t.badRequest({ error: "MULTIPART_ERROR", ...i });
+  }
+}
+// plugins/multipart/src/utils/log.ts
+var N = {
+  reset: "\x1B[0m",
+  red: "\x1B[31m",
+  blue: "\x1B[34m"
+};
+function Z(...t) {
+  process.env.DEBUG === "true" && console.log(`${N.blue}[AsterFlow Multipart]${N.reset}`, ...t);
+}
+function X(t, e) {
+  console.error(`${N.red}%s %s${N.reset}`, "[AsterFlow Multipart]", t), console.group(), console.error("Error:", e instanceof Error ? e.message : e), e instanceof Error && "code" in e && console.error("Code:", e.code), console.groupEnd();
+}
+// plugins/multipart/src/index.ts
+function de(t) {
+  return {
+    body: t.fields,
+    files: t.files,
+    multipartMetadata: t.metadata,
+    getFile(e) {
+      return t.files.find((i) => i.fieldName === e);
+    },
+    getFiles(e) {
+      return e ? t.files.filter((i) => i.fieldName === e) : t.files;
+    },
+    hasFiles() {
+      return t.files.length > 0;
+    },
+    getFilesByType(e) {
+      return t.files.filter((i) => i.mimeType === e);
+    },
+    async saveAll(e) {
+      let i = [];
+      for (let r of t.files) {
+        let s = `${e}/${r.filename}`;
+        await r.save(s), i.push(s);
+      }
+      return i;
+    },
+    async cleanupMultipart() {
+      await Promise.all(t.files.map(async (e) => {
+        if (e.tempPath)
+          try {
+            await (0, J.unlink)(e.tempPath);
+          } catch {
+          }
+      }));
+    }
+  };
+}
+var K = G.Plugin.create({ name: "multipart" }).decorate("creator", "Ashu11-A").decorate("version", z).decorate("installed", B()).config(b).on("onRequest", async ({ request: t, response: e, router: i, plugin: r }) => {
+  let s = t.getMethod().toLowerCase(), c = i.route instanceof P.Method ? i.route.extensions.multipart : (0, P.getRouteExtensions)(i.route)?.[s]?.multipart, p = t.getHeaders()["content-type"];
+  if (!(!!p && p.toLowerCase().includes("multipart/form-data")))
+    return c ? A(e, new o(
+      "Expected a multipart/form-data request",
+      n.PARSE_ERROR
+    )) : void 0;
+  try {
+    let f = R(r.context, (0, Q.tmpdir)()), d = await k(t, f);
+    c && D(d, c), Z("Multipart request parsed", {
+      Fields: String(d.metadata.fieldsCount),
+      Files: String(d.metadata.filesCount),
+      "Total Size": `${d.metadata.totalSize} bytes`,
+      "Processing Time": `${d.metadata.processingTime}ms`
+    }), t.extend(de(d));
+  } catch (f) {
+    let d = f instanceof o ? f : new o(f instanceof Error ? f.message : "Unknown error", n.PARSE_ERROR);
+    return X("Failed to parse multipart request", d), A(e, d);
+  }
+}).on("onResponse", async ({ request: t }) => {
+  await t.cleanupMultipart?.();
+}), fe = K;
+0 && (module.exports = {
+  DEFAULT_CONFIG,
+  ErrorCodes,
+  MultipartError,
+  MultipartParser,
+  errorResponse,
+  multipartPlugin,
+  parseMultipart,
+  resolveConfig,
+  validateFields
+});

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}