@jskit-ai/uploads-runtime 0.1.1 → 0.1.2

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/uploads-runtime",
-  version: "0.1.1",
+  version: "0.1.2",
   kind: "runtime",
   description: "Reusable upload runtime primitives for multipart parsing, policy validation, and blob storage.",
   dependsOn: [
@@ -38,10 +38,6 @@ export default Object.freeze({
           subpath: "./server/multipart/registerMultipartSupport",
           summary: "Exports Fastify multipart registration helper."
         },
-        {
-          subpath: "./server/multipart/readMultipartFiles",
-          summary: "Exports normalized multipart file parsing helpers."
-        },
         {
           subpath: "./server/multipart/readSingleMultipartFile",
           summary: "Exports a convenience helper for single-file multipart uploads."
@@ -75,7 +71,7 @@ export default Object.freeze({
     dependencies: {
       runtime: {
         "@fastify/multipart": "^9.4.0",
-        "@jskit-ai/kernel": "0.1.23"
+        "@jskit-ai/kernel": "0.1.24"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/uploads-runtime",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -10,13 +10,12 @@
     "./shared": "./src/shared/index.js",
     "./server/providers/UploadsRuntimeServiceProvider": "./src/server/providers/UploadsRuntimeServiceProvider.js",
     "./server/multipart/registerMultipartSupport": "./src/server/multipart/registerMultipartSupport.js",
-    "./server/multipart/readMultipartFiles": "./src/server/multipart/readMultipartFiles.js",
     "./server/multipart/readSingleMultipartFile": "./src/server/multipart/readSingleMultipartFile.js",
     "./server/policy/uploadPolicy": "./src/server/policy/uploadPolicy.js",
     "./server/storage/createUploadStorageService": "./src/server/storage/createUploadStorageService.js"
   },
   "dependencies": {
     "@fastify/multipart": "^9.4.0",
-    "@jskit-ai/kernel": "0.1.23"
+    "@jskit-ai/kernel": "0.1.24"
   }
 }

package/src/server/multipart/readSingleMultipartFile.js

@@ -1,11 +1,98 @@
-import { readMultipartFiles } from "./readMultipartFiles.js";
+import { createUploadFieldError } from "../policy/uploadPolicy.js";
+
+function normalizeFieldName(value) {
+  return String(value || "").trim();
+}
+
+function resolveFieldName(options = {}) {
+  const normalizedFieldName = normalizeFieldName(options.fieldName);
+  if (normalizedFieldName) {
+    return normalizedFieldName;
+  }
+
+  const fieldNames = Array.isArray(options.fieldNames) ? options.fieldNames : [];
+  if (fieldNames.length !== 1) {
+    return "";
+  }
+
+  return normalizeFieldName(fieldNames[0]);
+}
+
+function resolveMaxBytes(value) {
+  const normalized = Number(value);
+  return Number.isInteger(normalized) && normalized > 0 ? normalized : 0;
+}
+
+function formatMaxSizeMb(maxBytes) {
+  return Math.floor(maxBytes / (1024 * 1024));
+}
+
+function isMultipartError(error, code) {
+  return String(error?.code || "").trim().toUpperCase() === String(code || "").trim().toUpperCase();
+}
 
 async function readSingleMultipartFile(request, options = {}) {
-  const result = await readMultipartFiles(request, {
-    ...options,
-    maxFiles: 1
+  if (!request || typeof request.file !== "function") {
+    throw new TypeError("readSingleMultipartFile requires a request with file().");
+  }
+
+  const normalizedFieldName = resolveFieldName(options);
+  const normalizedFieldErrorKey =
+    normalizeFieldName(options.fieldErrorKey) || normalizedFieldName || "file";
+  const normalizedLabel = normalizeFieldName(options.label) || "File";
+  const normalizedMaxBytes = resolveMaxBytes(options.maxBytes);
+
+  let filePart = null;
+
+  try {
+    filePart = await request.file({
+      throwFileSizeLimit: true,
+      limits: {
+        files: 1,
+        ...(normalizedMaxBytes > 0 ? { fileSize: normalizedMaxBytes } : {})
+      }
+    });
+  } catch (error) {
+    if (isMultipartError(error, "FST_REQ_FILE_TOO_LARGE") && normalizedMaxBytes > 0) {
+      throw createUploadFieldError(
+        normalizedFieldErrorKey,
+        `${normalizedLabel} file is too large. Maximum allowed size is ${formatMaxSizeMb(normalizedMaxBytes)}MB.`
+      );
+    }
+
+    if (isMultipartError(error, "FST_FILES_LIMIT")) {
+      throw createUploadFieldError(normalizedFieldErrorKey, `${normalizedLabel} upload allows only one file.`);
+    }
+
+    throw error;
+  }
+
+  if (!filePart) {
+    if (options.required === true) {
+      throw createUploadFieldError(normalizedFieldErrorKey, `${normalizedLabel} file is required.`);
+    }
+    return null;
+  }
+
+  const actualFieldName = normalizeFieldName(filePart.fieldname);
+  if (normalizedFieldName && actualFieldName && actualFieldName !== normalizedFieldName) {
+    if (filePart.file && typeof filePart.file.resume === "function") {
+      filePart.file.resume();
+    }
+    throw createUploadFieldError(
+      normalizedFieldErrorKey,
+      `${normalizedLabel} field "${actualFieldName}" is not allowed.`
+    );
+  }
+
+  return Object.freeze({
+    fieldName: actualFieldName,
+    fileName: normalizeFieldName(filePart.filename),
+    mimeType: normalizeFieldName(filePart.mimetype).toLowerCase(),
+    encoding: normalizeFieldName(filePart.encoding).toLowerCase(),
+    stream: filePart.file,
+    fields: filePart.fields && typeof filePart.fields === "object" ? filePart.fields : {}
   });
-  return result.files[0] || null;
 }
 
 export { readSingleMultipartFile };

package/src/server/providers/UploadsRuntimeServiceProvider.js

@@ -1,5 +1,4 @@
 import { registerMultipartSupport } from "../multipart/registerMultipartSupport.js";
-import { readMultipartFiles } from "../multipart/readMultipartFiles.js";
 import { readSingleMultipartFile } from "../multipart/readSingleMultipartFile.js";
 import {
   createUploadFieldError,
@@ -14,7 +13,6 @@ import {
 
 const UPLOADS_RUNTIME_SERVER_API = Object.freeze({
   registerMultipartSupport,
-  readMultipartFiles,
   readSingleMultipartFile,
   createUploadFieldError,
   readUploadBuffer,

package/test/exportsContract.test.js

@@ -18,7 +18,6 @@ test("uploads-runtime exports are explicit and aligned with usage", () => {
       "./shared",
       "./server/providers/UploadsRuntimeServiceProvider",
       "./server/multipart/registerMultipartSupport",
-      "./server/multipart/readMultipartFiles",
       "./server/multipart/readSingleMultipartFile",
       "./server/policy/uploadPolicy",
       "./server/storage/createUploadStorageService"

package/test/readSingleMultipartFile.test.js

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Readable } from "node:stream";
+import { readSingleMultipartFile } from "../src/server/multipart/readSingleMultipartFile.js";
+
+test("readSingleMultipartFile normalizes file parts and forwards size limits", async () => {
+  let receivedOptions = null;
+  const request = {
+    async file(options) {
+      receivedOptions = options;
+      return {
+        fieldname: "avatar",
+        filename: " face.png ",
+        mimetype: " IMAGE/PNG ",
+        encoding: " 7BIT ",
+        file: Readable.from([Buffer.from("png")]),
+        fields: {
+          uploadDimension: {
+            value: "256"
+          }
+        }
+      };
+    }
+  };
+
+  const filePart = await readSingleMultipartFile(request, {
+    fieldName: "avatar",
+    required: true,
+    label: "Avatar",
+    maxBytes: 5 * 1024 * 1024
+  });
+
+  assert.deepEqual(receivedOptions, {
+    throwFileSizeLimit: true,
+    limits: {
+      files: 1,
+      fileSize: 5 * 1024 * 1024
+    }
+  });
+  assert.equal(filePart?.fieldName, "avatar");
+  assert.equal(filePart?.fileName, "face.png");
+  assert.equal(filePart?.mimeType, "image/png");
+  assert.equal(filePart?.encoding, "7bit");
+  assert.equal(filePart?.fields?.uploadDimension?.value, "256");
+});
+
+test("readSingleMultipartFile rejects missing required files", async () => {
+  const request = {
+    async file() {
+      return null;
+    }
+  };
+
+  await assert.rejects(
+    () =>
+      readSingleMultipartFile(request, {
+        fieldName: "avatar",
+        required: true,
+        fieldErrorKey: "avatar",
+        label: "Avatar"
+      }),
+    (error) => {
+      assert.equal(error?.message, "Validation failed.");
+      assert.equal(error?.details?.fieldErrors?.avatar, "Avatar file is required.");
+      return true;
+    }
+  );
+});
+
+test("readSingleMultipartFile maps multipart size errors to validation errors", async () => {
+  const request = {
+    async file() {
+      const error = new Error("request file too large");
+      error.code = "FST_REQ_FILE_TOO_LARGE";
+      throw error;
+    }
+  };
+
+  await assert.rejects(
+    () =>
+      readSingleMultipartFile(request, {
+        fieldName: "avatar",
+        fieldErrorKey: "avatar",
+        label: "Avatar",
+        maxBytes: 5 * 1024 * 1024
+      }),
+    (error) => {
+      assert.equal(error?.message, "Validation failed.");
+      assert.equal(error?.details?.fieldErrors?.avatar, "Avatar file is too large. Maximum allowed size is 5MB.");
+      return true;
+    }
+  );
+});
+
+test("readSingleMultipartFile rejects unexpected field names", async () => {
+  let resumeCount = 0;
+  const request = {
+    async file() {
+      return {
+        fieldname: "document",
+        filename: "face.png",
+        mimetype: "image/png",
+        encoding: "7bit",
+        file: {
+          resume() {
+            resumeCount += 1;
+          }
+        },
+        fields: {}
+      };
+    }
+  };
+
+  await assert.rejects(
+    () =>
+      readSingleMultipartFile(request, {
+        fieldName: "avatar",
+        fieldErrorKey: "avatar",
+        label: "Avatar"
+      }),
+    (error) => {
+      assert.equal(error?.message, "Validation failed.");
+      assert.equal(error?.details?.fieldErrors?.avatar, 'Avatar field "document" is not allowed.');
+      return true;
+    }
+  );
+
+  assert.equal(resumeCount, 1);
+});

package/src/server/multipart/readMultipartFiles.js

@@ -1,111 +0,0 @@
-import { createUploadFieldError } from "../policy/uploadPolicy.js";
-
-function normalizeFieldName(value) {
-  return String(value || "").trim();
-}
-
-function appendField(fields, fieldName, value) {
-  const normalizedFieldName = normalizeFieldName(fieldName);
-  if (!normalizedFieldName) {
-    return;
-  }
-
-  const normalizedValue = value == null ? "" : String(value);
-  if (!Object.hasOwn(fields, normalizedFieldName)) {
-    fields[normalizedFieldName] = {
-      value: normalizedValue,
-      values: [normalizedValue]
-    };
-    return;
-  }
-
-  fields[normalizedFieldName].values.push(normalizedValue);
-}
-
-function toAllowedFieldSet(fieldNames = []) {
-  const normalizedFieldNames = Array.isArray(fieldNames)
-    ? fieldNames.map(normalizeFieldName).filter(Boolean)
-    : [];
-  return normalizedFieldNames.length > 0 ? new Set(normalizedFieldNames) : null;
-}
-
-async function readMultipartFiles(
-  request,
-  {
-    fieldNames = [],
-    maxFiles = Number.POSITIVE_INFINITY,
-    required = false,
-    fieldErrorKey = "",
-    label = "File"
-  } = {}
-) {
-  if (!request || typeof request.parts !== "function") {
-    throw new TypeError("readMultipartFiles requires a request with parts().");
-  }
-
-  const allowedFieldNames = toAllowedFieldSet(fieldNames);
-  const normalizedFieldErrorKey =
-    normalizeFieldName(fieldErrorKey) ||
-    (allowedFieldNames && allowedFieldNames.size === 1 ? [...allowedFieldNames][0] : "file");
-  const normalizedMaxFiles =
-    Number.isInteger(maxFiles) && maxFiles > 0 ? maxFiles : Number.POSITIVE_INFINITY;
-
-  const fields = {};
-  const files = [];
-
-  for await (const part of request.parts()) {
-    if (part?.type === "field") {
-      appendField(fields, part.fieldname, part.value);
-      continue;
-    }
-
-    if (part?.type !== "file") {
-      continue;
-    }
-
-    const fieldName = normalizeFieldName(part.fieldname);
-    if (allowedFieldNames && !allowedFieldNames.has(fieldName)) {
-      if (part.file && typeof part.file.resume === "function") {
-        part.file.resume();
-      }
-      throw createUploadFieldError(
-        normalizedFieldErrorKey,
-        `${label} field "${fieldName || "unknown"}" is not allowed.`
-      );
-    }
-
-    if (files.length >= normalizedMaxFiles) {
-      if (part.file && typeof part.file.resume === "function") {
-        part.file.resume();
-      }
-      throw createUploadFieldError(
-        normalizedFieldErrorKey,
-        normalizedMaxFiles === 1
-          ? `${label} upload allows only one file.`
-          : `${label} upload allows at most ${normalizedMaxFiles} files.`
-      );
-    }
-
-    files.push(
-      Object.freeze({
-        fieldName,
-        fileName: String(part.filename || "").trim(),
-        mimeType: String(part.mimetype || "").trim().toLowerCase(),
-        encoding: String(part.encoding || "").trim().toLowerCase(),
-        stream: part.file,
-        fields
-      })
-    );
-  }
-
-  if (required && files.length === 0) {
-    throw createUploadFieldError(normalizedFieldErrorKey, `${label} file is required.`);
-  }
-
-  return Object.freeze({
-    fields: Object.freeze(fields),
-    files: Object.freeze(files)
-  });
-}
-
-export { readMultipartFiles };

package/test/readMultipartFiles.test.js

@@ -1,80 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { Readable } from "node:stream";
-import { readMultipartFiles } from "../src/server/multipart/readMultipartFiles.js";
-import { readSingleMultipartFile } from "../src/server/multipart/readSingleMultipartFile.js";
-
-function createRequestStub(parts) {
-  return {
-    async *parts() {
-      for (const part of parts) {
-        yield part;
-      }
-    }
-  };
-}
-
-test("readMultipartFiles normalizes fields and files", async () => {
-  const request = createRequestStub([
-    { type: "field", fieldname: "uploadDimension", value: "256" },
-    {
-      type: "file",
-      fieldname: "avatar",
-      filename: "face.png",
-      mimetype: "image/png",
-      encoding: "7bit",
-      file: Readable.from([Buffer.from("png")])
-    }
-  ]);
-
-  const result = await readMultipartFiles(request, {
-    fieldNames: ["avatar"],
-    required: true,
-    label: "Avatar"
-  });
-
-  assert.equal(result.files.length, 1);
-  assert.equal(result.files[0].fieldName, "avatar");
-  assert.equal(result.files[0].fileName, "face.png");
-  assert.equal(result.files[0].mimeType, "image/png");
-  assert.equal(result.fields.uploadDimension.value, "256");
-});
-
-test("readSingleMultipartFile returns the first file and enforces maxFiles", async () => {
-  const request = createRequestStub([
-    {
-      type: "file",
-      fieldname: "avatar",
-      filename: "face.png",
-      mimetype: "image/png",
-      encoding: "7bit",
-      file: Readable.from([Buffer.from("png")])
-    }
-  ]);
-
-  const file = await readSingleMultipartFile(request, {
-    fieldNames: ["avatar"],
-    required: true,
-    label: "Avatar"
-  });
-
-  assert.equal(file?.fileName, "face.png");
-});
-
-test("readMultipartFiles rejects missing required files", async () => {
-  const request = createRequestStub([]);
-
-  await assert.rejects(
-    () =>
-      readMultipartFiles(request, {
-        fieldNames: ["avatar"],
-        required: true,
-        label: "Avatar"
-      }),
-    (error) => {
-      assert.equal(error?.message, "Validation failed.");
-      assert.equal(error?.details?.fieldErrors?.avatar, "Avatar file is required.");
-      return true;
-    }
-  );
-});