@kiyasov/platform-hono 1.6.1 → 2.0.1

package/src/multer/multipart/handlers/base-handler.ts

@@ -0,0 +1,204 @@
+import { BadRequestException } from '@nestjs/common';
+import { BodyData } from 'hono/utils/body';
+
+import { StorageFile } from '../../storage/storage';
+import { removeStorageFiles } from '../file';
+import { filterUpload } from '../filter';
+import { UploadOptions } from '../options';
+import { THonoRequest, getParts } from '../request';
+
+export interface ProcessedFile {
+  file: StorageFile;
+  fieldName: string;
+}
+
+export interface FileProcessResult {
+  body: BodyData;
+  remove: () => Promise<void>;
+}
+
+export interface SingleFileResult extends FileProcessResult {
+  file?: StorageFile;
+}
+
+export interface MultipleFilesResult extends FileProcessResult {
+  files: StorageFile[];
+}
+
+export interface FileFieldsResult extends FileProcessResult {
+  files: Record<string, StorageFile[]>;
+}
+
+export class FileHandler {
+  private readonly body: BodyData = {};
+  private readonly files: StorageFile[] = [];
+  private readonly filesByField: Record<string, StorageFile[]> = {};
+  private processed = false;
+  private cleanedUp = false;
+
+  constructor(
+    private readonly req: THonoRequest,
+    private readonly options: UploadOptions,
+  ) {}
+
+  /**
+   * Processes all parts in the multipart request.
+   */
+  async process(
+    processor: (fieldName: string, file: File) => Promise<void>,
+  ): Promise<void> {
+    if (this.processed) {
+      throw new Error('Request already processed');
+    }
+
+    this.processed = true;
+    const parts = getParts(this.req, this.options);
+
+    try {
+      for await (const [fieldName, part] of Object.entries(parts)) {
+        // Handle array of files (for multiple file uploads with same field name)
+        if (Array.isArray(part) && part.every((item) => item instanceof File)) {
+          for (const file of part) {
+            await processor(fieldName, file);
+          }
+          continue;
+        }
+
+        if (!(part instanceof File)) {
+          this.body[fieldName] = part;
+          continue;
+        }
+
+        await processor(fieldName, part);
+      }
+    } catch (error) {
+      await this.cleanup(true);
+      throw error;
+    }
+  }
+
+  /**
+   * Handles a single file upload for a specific field.
+   */
+  async handleSingleFile(
+    fieldName: string,
+    file: File,
+  ): Promise<StorageFile | undefined> {
+    const storageFile = await this.options.storage!.handleFile(
+      file,
+      this.req,
+      fieldName,
+    );
+
+    if (await filterUpload(this.options, this.req, storageFile)) {
+      return storageFile;
+    }
+
+    // If file was filtered out, remove it from storage
+    await this.options.storage!.removeFile(storageFile, true);
+    return undefined;
+  }
+
+  /**
+   * Validates that the field name matches the expected field name.
+   */
+  validateFieldName(fieldName: string, expectedFieldName: string): void {
+    if (fieldName !== expectedFieldName) {
+      throw new BadRequestException(
+        `Field "${fieldName}" doesn't accept file.`,
+      );
+    }
+  }
+
+  /**
+   * Validates that only one file is uploaded for a field.
+   */
+  validateSingleFile(currentFile: StorageFile | undefined): void {
+    if (currentFile) {
+      throw new BadRequestException('Field accepts only one file.');
+    }
+  }
+
+  /**
+   * Validates the maximum number of files for a field.
+   */
+  validateMaxCount(
+    fieldName: string,
+    currentCount: number,
+    maxCount: number,
+  ): void {
+    if (currentCount >= maxCount) {
+      throw new BadRequestException(
+        `Field "${fieldName}" accepts max ${maxCount} files.`,
+      );
+    }
+  }
+
+  /**
+   * Adds a file to the files collection.
+   */
+  addFile(fieldName: string, file: StorageFile): void {
+    this.files.push(file);
+
+    if (!this.filesByField[fieldName]) {
+      this.filesByField[fieldName] = [];
+    }
+    this.filesByField[fieldName].push(file);
+  }
+
+  /**
+   * Returns all processed files.
+   */
+  getFiles(): StorageFile[] {
+    return [...this.files];
+  }
+
+  /**
+   * Returns files grouped by field name.
+   */
+  getFilesByField(): Record<string, StorageFile[]> {
+    return { ...this.filesByField };
+  }
+
+  /**
+   * Returns the request body.
+   */
+  getBody(): BodyData {
+    return { ...this.body };
+  }
+
+  /**
+   * Cleans up all uploaded files.
+   * Prevents multiple cleanups and clears references to avoid memory leaks.
+   */
+  async cleanup(error?: boolean): Promise<void> {
+    if (this.cleanedUp) {
+      return;
+    }
+
+    this.cleanedUp = true;
+
+    await removeStorageFiles(this.options.storage!, this.files, error);
+
+    // Clear references to allow garbage collection
+    this.files.length = 0;
+    for (const key of Object.keys(this.filesByField)) {
+      delete this.filesByField[key];
+    }
+  }
+
+  /**
+   * Creates a remove function for cleanup that prevents multiple calls.
+   */
+  createRemoveFunction(): () => Promise<void> {
+    let called = false;
+
+    return async () => {
+      if (called) {
+        return;
+      }
+      called = true;
+      await this.cleanup();
+    };
+  }
+}

package/src/multer/multipart/handlers/file-fields.ts

@@ -1,11 +1,9 @@
 import { BadRequestException } from '@nestjs/common';
-import { BodyData } from 'hono/utils/body';
 
 import { StorageFile } from '../../storage/storage';
-import { removeStorageFiles } from '../file';
-import { filterUpload } from '../filter';
 import { UploadOptions } from '../options';
-import { THonoRequest, getParts } from '../request';
+import { THonoRequest } from '../request';
+import { FileHandler, FileFieldsResult } from './base-handler';
 
 export interface UploadField {
   name: string;
@@ -16,74 +14,48 @@ export type UploadFieldMapEntry = Required<Pick<UploadField, 'maxCount'>>;
 
 /**
  * Converts an array of upload fields into a map for easy lookup.
- * @param {UploadField[]} uploadFields - Array of upload field definitions.
- * @returns {Map<string, UploadFieldMapEntry>} A map of field names to their max count settings.
  */
-export const uploadFieldsToMap = (uploadFields: UploadField[]) =>
+export const uploadFieldsToMap = (
+  uploadFields: UploadField[],
+): Map<string, UploadFieldMapEntry> =>
   new Map(
     uploadFields.map(({ name, ...opts }) => [name, { maxCount: 1, ...opts }]),
   );
 
 /**
  * Handles multipart file fields by processing form-data parts.
- * @param {THonoRequest} req - The incoming request object.
- * @param {Map<string, UploadFieldMapEntry>} fieldsMap - A map of allowed upload fields.
- * @param {UploadOptions} options - Upload options including storage handler.
- * @returns {Promise<{ body: BodyData, files: Record<string, StorageFile[]>, remove: () => Promise<void> }>} The parsed body and files with a removal function.
  */
 export const handleMultipartFileFields = async (
   req: THonoRequest,
   fieldsMap: Map<string, UploadFieldMapEntry>,
   options: UploadOptions,
-): Promise<{
-  body: BodyData;
-  files: Record<string, StorageFile[]>;
-  remove: () => Promise<void>;
-}> => {
-  const parts = getParts(req, options);
-  const body: BodyData = {};
+): Promise<FileFieldsResult> => {
+  const handler = new FileHandler(req, options);
   const files: Record<string, StorageFile[]> = {};
 
-  /**
-   * Removes stored files in case of an error or cleanup.
-   * @param {boolean} [error=false] - Whether the removal is due to an error.
-   * @returns {Promise<void>} Resolves after files are removed.
-   */
-  const removeFiles = async (error?: boolean): Promise<void> => {
-    const allFiles = Object.values(files).flat();
-    return removeStorageFiles(options.storage!, allFiles, error);
-  };
-
-  try {
-    for await (const [fieldName, part] of Object.entries(parts)) {
-      if (!(part instanceof File)) {
-        body[fieldName] = part;
-        continue;
-      }
-
-      const fieldOptions = fieldsMap.get(fieldName);
-      if (!fieldOptions) {
-        throw new BadRequestException(
-          `Field ${fieldName} doesn't accept files`,
-        );
-      }
-
-      files[fieldName] = files[fieldName] || [];
-      if (files[fieldName].length >= fieldOptions.maxCount) {
-        throw new BadRequestException(
-          `Field ${fieldName} accepts max ${fieldOptions.maxCount} files`,
-        );
-      }
+  await handler.process(async (fieldName, part) => {
+    const fieldOptions = fieldsMap.get(fieldName);
+    if (!fieldOptions) {
+      throw new BadRequestException(`Field ${fieldName} doesn't accept files`);
+    }
 
-      const file = await options.storage!.handleFile(part, req, fieldName);
-      if (await filterUpload(options, req, file)) {
-        files[fieldName].push(file);
-      }
+    files[fieldName] = files[fieldName] || [];
+    handler.validateMaxCount(
+      fieldName,
+      files[fieldName].length,
+      fieldOptions.maxCount,
+    );
+
+    const storageFile = await handler.handleSingleFile(fieldName, part);
+    if (storageFile) {
+      files[fieldName].push(storageFile);
+      handler.addFile(fieldName, storageFile);
     }
-  } catch (error) {
-    await removeFiles(true);
-    throw error;
-  }
+  });
 
-  return { body, files, remove: removeFiles };
+  return {
+    body: handler.getBody(),
+    files,
+    remove: handler.createRemoveFunction(),
+  };
 };

package/src/multer/multipart/handlers/index.ts

@@ -1 +1,11 @@
-export { UploadField } from './file-fields';
+export { UploadField, uploadFieldsToMap } from './file-fields';
+export { handleMultipartSingleFile } from './single-file';
+export { handleMultipartMultipleFiles } from './multiple-files';
+export { handleMultipartFileFields } from './file-fields';
+export { handleMultipartAnyFiles } from './any-files';
+export {
+  FileHandler,
+  SingleFileResult,
+  MultipleFilesResult,
+  FileFieldsResult,
+} from './base-handler';

package/src/multer/multipart/handlers/multiple-files.ts

@@ -1,70 +1,39 @@
 import { BadRequestException } from '@nestjs/common';
-import { BodyData } from 'hono/utils/body';
 
-import { StorageFile } from '../../storage';
-import { removeStorageFiles } from '../file';
-import { filterUpload } from '../filter';
+import { StorageFile } from '../../storage/storage';
 import { UploadOptions } from '../options';
-import { THonoRequest, getParts } from '../request';
+import { THonoRequest } from '../request';
+import { FileHandler, MultipleFilesResult } from './base-handler';
 
 export const handleMultipartMultipleFiles = async (
   req: THonoRequest,
   fieldname: string,
   maxCount: number,
   options: UploadOptions,
-) => {
-  const parts = getParts(req, options);
-  const body: BodyData = {};
-
+): Promise<MultipleFilesResult> => {
+  const handler = new FileHandler(req, options);
   const files: StorageFile[] = [];
 
-  const removeFiles = async (error?: boolean) => {
-    return await removeStorageFiles(options.storage!, files, error);
-  };
-
-  try {
-    for await (const [partFieldName, part] of Object.entries(parts)) {
-      if (!(part instanceof File || Array.isArray(part))) {
-        body[partFieldName] = part;
-        continue;
-      }
-
-      const partArray = Array.isArray(part) ? part : [part];
-
-      for (const singlePart of partArray) {
-        if (!(singlePart instanceof File)) {
-          throw new BadRequestException(
-            `Field ${partFieldName} contains invalid file data`,
-          );
-        }
-
-        if (partFieldName !== fieldname) {
-          throw new BadRequestException(
-            `Field ${partFieldName} doesn't accept files`,
-          );
-        }
-
-        if (files.length >= maxCount) {
-          throw new BadRequestException(
-            `Field ${partFieldName} accepts max ${maxCount} files`,
-          );
-        }
+  await handler.process(async (fieldName, part) => {
+    if (!(part instanceof File)) {
+      throw new BadRequestException(
+        `Field ${fieldName} contains invalid file data`,
+      );
+    }
 
-        const file = await options.storage!.handleFile(
-          singlePart,
-          req,
-          partFieldName,
-        );
+    handler.validateFieldName(fieldName, fieldname);
+    handler.validateMaxCount(fieldName, files.length, maxCount);
 
-        if (await filterUpload(options, req, file)) {
-          files.push(file);
-        }
-      }
+    const storageFile = await handler.handleSingleFile(fieldName, part);
+    if (storageFile) {
+      files.push(storageFile);
+      handler.addFile(fieldName, storageFile);
     }
-  } catch (error) {
-    await removeFiles(error);
-    throw error;
-  }
+  });
 
-  return { body, files, remove: () => removeFiles() };
+  return {
+    body: handler.getBody(),
+    files,
+    remove: handler.createRemoveFunction(),
+  };
 };

package/src/multer/multipart/handlers/single-file.ts

@@ -1,10 +1,7 @@
-import { BadRequestException } from '@nestjs/common';
-import { BodyData } from 'hono/utils/body';
-
-import { StorageFile } from '../../storage';
-import { filterUpload } from '../filter';
+import { StorageFile } from '../../storage/storage';
 import { UploadOptions } from '../options';
-import { THonoRequest, getParts } from '../request';
+import { THonoRequest } from '../request';
+import { FileHandler, SingleFileResult } from './base-handler';
 
 /**
  * Handles a single file upload in a multipart request.
@@ -17,53 +14,23 @@ export const handleMultipartSingleFile = async (
   req: THonoRequest,
   fieldname: string,
   options: UploadOptions,
-) => {
-  const parts = getParts(req, options);
-  const body: BodyData = {};
+): Promise<SingleFileResult> => {
+  const handler = new FileHandler(req, options);
   let file: StorageFile | undefined;
 
-  /**
-   * Removes uploaded file in case of an error or cleanup.
-   * @param error - Whether the removal is due to an error.
-   */
-  const removeFiles = async (error?: boolean) => {
-    if (!file) return;
-    await options.storage!.removeFile(file, error);
-  };
-
-  try {
-    for await (const [partFieldName, part] of Object.entries(parts)) {
-      if (!(part instanceof File)) {
-        body[partFieldName] = part;
-        continue;
-      }
-
-      if (partFieldName !== fieldname) {
-        throw new BadRequestException(
-          `Field "${partFieldName}" doesn't accept file.`,
-        );
-      }
-
-      if (file) {
-        throw new BadRequestException(
-          `Field "${fieldname}" accepts only one file.`,
-        );
-      }
-
-      const _file = await options.storage!.handleFile(part, req, partFieldName);
+  await handler.process(async (fieldName, part) => {
+    handler.validateFieldName(fieldName, fieldname);
+    handler.validateSingleFile(file);
 
-      if (await filterUpload(options, req, _file)) {
-        file = _file;
-      }
+    const storageFile = await handler.handleSingleFile(fieldName, part);
+    if (storageFile) {
+      file = storageFile;
     }
-  } catch (error) {
-    await removeFiles(true);
-    throw error;
-  }
+  });
 
   return {
-    body,
+    body: handler.getBody(),
     file,
-    remove: () => removeFiles(),
+    remove: handler.createRemoveFunction(),
   };
 };

package/src/multer/multipart/index.ts

@@ -1,3 +1,3 @@
 export * from './options';
 export * from './filter';
-export { UploadFilterFile, UploadFilterHandler } from './filter';
+export { type UploadFilterFile, type UploadFilterHandler } from './filter';

package/src/multer/multipart/options.ts

@@ -1,20 +1,38 @@
-import busboy from 'busboy';
-
-import { DiskStorage, MemoryStorage, Storage } from '../storage';
+import { DiskStorage, MemoryStorage, Storage, StorageFile } from '../storage';
 import { UploadFilterHandler } from './filter';
 
-export type UploadOptions = busboy.BusboyConfig & {
+/**
+ * Upload limits configuration
+ */
+export interface UploadLimits {
+  /** Maximum file size in bytes */
+  fileSize?: number;
+  /** Maximum number of files for a field */
+  files?: number;
+  /** Maximum number of fields (for file fields upload) */
+  fields?: number;
+}
+
+/**
+ * File upload options
+ */
+export type UploadOptions = {
+  /** Destination directory for disk storage */
   dest?: string;
-  storage?: Storage;
+  /** Storage implementation */
+  storage?: Storage<StorageFile>;
+  /** File filter function */
   filter?: UploadFilterHandler;
+  /** Upload limits */
+  limits?: UploadLimits;
 };
 
 export const DEFAULT_UPLOAD_OPTIONS: Partial<UploadOptions> = {
   storage: new MemoryStorage(),
 };
 
-export const transformUploadOptions = (opts?: UploadOptions) => {
-  if (opts == null) return DEFAULT_UPLOAD_OPTIONS;
+export const transformUploadOptions = (opts?: UploadOptions): UploadOptions => {
+  if (opts == null) return DEFAULT_UPLOAD_OPTIONS as UploadOptions;
 
   if (opts.dest != null) {
     return {
@@ -26,5 +44,5 @@ export const transformUploadOptions = (opts?: UploadOptions) => {
     };
   }
 
-  return { ...DEFAULT_UPLOAD_OPTIONS, ...opts };
+  return { ...DEFAULT_UPLOAD_OPTIONS, ...opts } as UploadOptions;
 };

package/src/multer/multipart/request.ts

@@ -36,10 +36,26 @@ export const getParts = (
 ): BodyData => {
   const parts = req.body ?? {};
 
-  for (const [key, file] of Object.entries(parts)) {
-    if (file instanceof File) {
+  for (const [key, value] of Object.entries(parts)) {
+    // Handle array of files
+    if (Array.isArray(value) && value.every((item) => item instanceof File)) {
       const maxSize = options?.limits?.fileSize;
-      if (maxSize && file.size > maxSize) {
+      if (maxSize) {
+        for (const file of value) {
+          if (file.size > maxSize) {
+            throw new BadRequestException(
+              `File "${key}" is too large. Maximum size is ${maxSize} bytes.`,
+            );
+          }
+        }
+      }
+      continue;
+    }
+
+    // Handle single file
+    if (value instanceof File) {
+      const maxSize = options?.limits?.fileSize;
+      if (maxSize && value.size > maxSize) {
         throw new BadRequestException(
           `File "${key}" is too large. Maximum size is ${maxSize} bytes.`,
         );

package/src/multer/storage/disk-storage.ts

@@ -77,7 +77,8 @@ export class DiskStorage
       path,
       mimetype: file.type,
       encoding: 'utf-8',
-      fieldname: fieldName,
+      fieldName: fieldName,
+      uploadedAt: new Date().toISOString(),
     };
   }
 

package/src/multer/storage/memory-storage.ts

@@ -8,26 +8,33 @@ export interface MemoryStorageFile extends StorageFile {
 }
 
 export class MemoryStorage implements Storage<MemoryStorageFile> {
-  public async handleFile(file: File, _req: HonoRequest, fieldName: string) {
+  public async handleFile(
+    file: File,
+    _req: HonoRequest,
+    fieldName: string,
+  ): Promise<MemoryStorageFile> {
     const buffer = await file
       .stream()
       .pipeTo(new WritableStream())
       .then(() => file.arrayBuffer())
-      .then((buffer) => Buffer.from(buffer));
+      .then((buf) => Buffer.from(buf));
 
     return {
       buffer,
       size: buffer.length,
       encoding: 'utf-8',
       mimetype: file.type,
-      fieldname: fieldName,
+      fieldName: fieldName,
       originalFilename: file.name,
+      uploadedAt: new Date().toISOString(),
       stream: () => file.stream(),
-      lastModified: file.lastModified,
     };
   }
 
-  public async removeFile(file: MemoryStorageFile) {
-    delete file.buffer;
+  public async removeFile(file: StorageFile): Promise<void> {
+    // Check if it's a MemoryStorageFile before deleting buffer
+    if ('buffer' in file) {
+      delete (file as MemoryStorageFile).buffer;
+    }
   }
 }

package/src/multer/storage/storage.ts

@@ -1,16 +1,23 @@
 import { HonoRequest } from 'hono';
 
 export interface StorageFile {
-  size: number;
-  fieldname: string;
-  encoding: string;
-  mimetype: string;
+  /** Field name in the multipart form */
+  fieldName: string;
+  /** Original filename provided by client */
   originalFilename: string;
+  /** MIME type of the file */
+  mimetype: string;
+  /** Encoding type (e.g., '7bit', '8bit', 'binary') */
+  encoding: string;
+  /** Size of the file in bytes */
+  size: number;
+  /** Timestamp when file was uploaded (ISO 8601) */
+  uploadedAt?: string;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface Storage<T extends StorageFile = StorageFile, K = any> {
   handleFile: (file: File, req: HonoRequest, fieldName: string) => Promise<T>;
-  removeFile: (file: T, force?: boolean) => Promise<void> | void;
+  removeFile: (file: T | StorageFile, force?: boolean) => Promise<void> | void;
   options?: K;
 }