@asterflow/multipart 1.1.0

package/dist/mjs/index.js

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

package/dist/mjs/package.json

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

package/dist/types/controllers/MultipartParser.d.ts

@@ -0,0 +1,18 @@
+import { type MultipartConfig, type MultipartResult, type ParserEvents } from '../types/multipart';
+/**
+ * The minimal request shape the parser needs. `AsterRequest` satisfies this
+ * structurally, so no dependency on `@asterflow/request`'s generics is needed here.
+ */
+export interface MultipartRequestLike {
+    raw: unknown;
+    getHeaders(): Record<string, string>;
+}
+export declare class MultipartParser {
+    private readonly config;
+    private readonly events;
+    constructor(config?: MultipartConfig, events?: ParserEvents);
+    parse(request: MultipartRequestLike): Promise<MultipartResult>;
+    private consumeFile;
+    private validateFile;
+}
+export declare function parseMultipart(request: MultipartRequestLike, config?: MultipartConfig, events?: ParserEvents): Promise<MultipartResult>;

package/dist/types/controllers/multipartExtension.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runtime half of `.multipart(schema)`, declared in `types/asterflow.d.ts`
+ * (declaration merging is types-only). Called from `index.ts`; its return
+ * value is threaded into `.decorate(...)` rather than called as a bare
+ * statement because Bun's transpiler dead-code-eliminates a side-effecting
+ * call whose result isn't otherwise used.
+ */
+export declare function installExtension(): true;

package/dist/types/controllers/validateMultipartFields.d.ts

@@ -0,0 +1,3 @@
+import { type MultipartFields, type MultipartResult } from '../types/multipart';
+/** Validates parsed files against a route's declared `multipart` field criteria. Throws the first `MultipartError` found. */
+export declare function validateFields(result: MultipartResult, schema: MultipartFields): void;

package/dist/types/index.d.ts

@@ -0,0 +1,27 @@
+import { Plugin } from '@asterflow/plugin';
+import './types/asterflow.d.ts';
+import { type MultipartConfig } from './types/multipart';
+export * from './controllers/MultipartParser';
+export * from './controllers/validateMultipartFields';
+export * from './types/inferRequest';
+export * from './types/mime';
+export * from './types/multipart';
+export * from './utils/errors';
+export declare const multipartPlugin: Plugin<{
+    decorate: {
+        creator: string;
+        version: string;
+        installed: true;
+    };
+    path: "multipart";
+    instance: import("asterflow").AnyAsterflow;
+    derive: {};
+    extension: {};
+    config: {
+        limits?: import("./index.ts").MultipartLimits | undefined;
+        fileHandling?: import("./index.ts").MultipartFileHandling | undefined;
+        validation?: import("./index.ts").MultipartValidation | undefined;
+        defaultConfig: MultipartConfig;
+    };
+}>;
+export default multipartPlugin;

package/dist/types/types/asterflow.d.ts

@@ -0,0 +1,61 @@
+import type {
+  DefaultMethodProps,
+  DefaultRouteMethodBuilderProps,
+  MergeProps,
+  MethodProps,
+  RouteMethodBuilderProps
+} from '@asterflow/router'
+import type { InferMultipartRequestFragment } from './inferRequest'
+import type { MultipartFields, MultipartFile, MultipartResult } from './multipart'
+
+/**
+ * Ambient fallback for routes that don't call `.multipart(...)` - optional,
+ * since these only exist on `request` for an actual multipart request.
+ * Routes that do call `.multipart(...)` get the stricter, non-optional
+ * typing below instead, which wins for `getFile`/`getFiles`.
+ */
+declare module '@asterflow/request' {
+  interface AsterRequest {
+    /** Parsed form fields. Only set when the request was `multipart/form-data`. */
+    body?: Record<string, string | string[]>
+    /** All processed files from the request. Only set when it was `multipart/form-data`. */
+    files?: MultipartFile[]
+    /** Parsing metadata (timing, counts). Only set when it was `multipart/form-data`. */
+    multipartMetadata?: MultipartResult['metadata']
+
+    getFile?(fieldName: string): MultipartFile | undefined
+    getFiles?(fieldName?: string): MultipartFile[]
+    hasFiles?(): boolean
+    getFilesByType?(mimeType: string): MultipartFile[]
+    /** Saves every file into `directory`, keyed by original filename. Returns the written paths. */
+    saveAll?(directory: string): Promise<string[]>
+    /** Removes any temp files created on disk for this request. Safe to call more than once. */
+    cleanupMultipart?(): Promise<void>
+  }
+}
+
+/**
+ * Adds `.multipart(schema)` onto `Method` and `RouteMethodBuilder` via
+ * declaration merging - the parameter list must match each class's real one
+ * exactly (count, constraints, defaults). No `const` modifier here: Bun's
+ * transpiler can't parse `const` type parameters inside a merged interface,
+ * even though `tsc` accepts it. Runtime implementation lives in
+ * `controllers/multipartExtension.ts`.
+ */
+declare module '@asterflow/router' {
+  interface Method<
+    Props extends MethodProps = DefaultMethodProps
+  > {
+    multipart<Fields extends MultipartFields>(
+      schema: Fields
+    ): Method<MergeProps<Props, { requestExt: Props['requestExt'] & InferMultipartRequestFragment<Fields>, handler: Props['handler'] extends undefined ? undefined : any }>>
+  }
+
+  interface RouteMethodBuilder<
+    Props extends RouteMethodBuilderProps = DefaultRouteMethodBuilderProps
+  > {
+    multipart<Fields extends MultipartFields>(
+      schema: Fields
+    ): RouteMethodBuilder<MergeProps<Props, { requestExt: Props['requestExt'] & InferMultipartRequestFragment<Fields> }>>
+  }
+}

package/dist/types/types/inferRequest.d.ts

@@ -0,0 +1,18 @@
+import type { MultipartFieldCriteria, MultipartFields, MultipartFile } from './multipart';
+type NarrowedFile<Criteria extends MultipartFieldCriteria> = Criteria['mimeTypes'] extends readonly (infer M extends string)[] ? Omit<MultipartFile, 'mimeType'> & {
+    mimeType: M;
+} : MultipartFile;
+type InferFieldFile<Criteria extends MultipartFieldCriteria> = Criteria['required'] extends true ? NarrowedFile<Criteria> : NarrowedFile<Criteria> | undefined;
+type InferFieldFiles<Criteria extends MultipartFieldCriteria> = NarrowedFile<Criteria>[];
+/**
+ * `request` extension for a route that called `.multipart(schema)` -
+ * `getFile`/`getFiles` keyed to the declared field names, schema-narrowed.
+ * `ExtendedRequest` (in `@asterflow/router`) omits the ambient untyped
+ * versions before intersecting this in, so this is the only signature
+ * available, not an extra overload.
+ */
+export type InferMultipartRequestFragment<Schema extends MultipartFields> = {
+    getFile<K extends keyof Schema & string>(field: K): InferFieldFile<Schema[K]>;
+    getFiles<K extends keyof Schema & string>(field: K): InferFieldFiles<Schema[K]>;
+};
+export {};