@bernierllc/file-uploader 0.1.0

package/.eslintrc.cjs

@@ -0,0 +1,33 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended'
+  ],
+  plugins: ['@typescript-eslint'],
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module'
+  },
+  env: {
+    node: true,
+    es6: true,
+    jest: true
+  },
+  rules: {
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/no-non-null-assertion': 'warn'
+  },
+  ignorePatterns: ['dist/', 'node_modules/', '*.cjs']
+};
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bernier LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @bernierllc/file-uploader
+
+Multipart file upload handler with validation and progress tracking
+
+## Installation
+
+```bash
+npm install @bernierllc/file-uploader
+```
+
+## Features
+
+- **Multipart form parsing** - Handles multipart/form-data uploads
+- **File validation** - Size limits, MIME type checking, file count limits
+- **Progress tracking** - Real-time upload progress callbacks
+- **Framework agnostic** - Works with Express, Koa, Fastify, etc.
+- **Stream-based** - Efficient handling of large files
+- **TypeScript support** - Full type safety
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { FileUploader } from '@bernierllc/file-uploader';
+import express from 'express';
+
+const app = express();
+const uploader = new FileUploader({
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+  allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+  onProgress: (progress) => {
+    console.log(`Upload progress: ${progress.percentage}%`);
+  }
+});
+
+app.post('/upload', async (req, res) => {
+  try {
+    const results = await uploader.handleMultipart(req);
+    res.json({ files: results });
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+```
+
+### File Validation
+
+```typescript
+const uploader = new FileUploader({
+  maxFileSize: 5 * 1024 * 1024, // 5MB
+  allowedMimeTypes: ['image/jpeg', 'image/png'],
+  maxFiles: 5
+});
+
+// Validate before upload
+const fileInfo = {
+  fieldname: 'file',
+  filename: 'photo.jpg',
+  encoding: '7bit',
+  mimeType: 'image/jpeg',
+  size: 1024 * 1024
+};
+
+const validation = uploader.validateFile(fileInfo);
+if (!validation.valid) {
+  console.error(validation.error);
+}
+```
+
+### Progress Tracking
+
+```typescript
+const uploader = new FileUploader({
+  onProgress: (progress) => {
+    console.log(`File ${progress.fileId}: ${progress.percentage}%`);
+    console.log(`Uploaded: ${progress.bytesUploaded}/${progress.totalBytes}`);
+  }
+});
+```
+
+### Custom Destination
+
+```typescript
+const uploader = new FileUploader({
+  destination: async (file) => {
+    // Generate custom path
+    return `/uploads/${Date.now()}-${file.filename}`;
+  }
+});
+```
+
+## API
+
+### `new FileUploader(config?: UploadConfig)`
+
+Creates a new file uploader instance.
+
+### `uploader.handleMultipart(req: IncomingMessage): Promise<UploadResult[]>`
+
+Processes a multipart form upload request.
+
+### `uploader.validateFile(file: FileInfo): { valid: boolean; error?: string }`
+
+Validates a file against configuration rules.
+
+### `uploader.getProgress(fileId: string): UploadProgress | null`
+
+Gets upload progress for a specific file.
+
+## Integration Status
+
+### Logger Integration
+**Status**: ✅ Integrated
+
+Uses `@bernierllc/logger` for upload events, errors, and progress tracking.
+
+### NeverHub Integration
+**Status**: ⚠️ Optional
+
+Can emit upload events to NeverHub for distributed monitoring and observability. File uploader can publish events like `upload.started`, `upload.progress`, `upload.completed`, and `upload.failed` to NeverHub when available.
+
+**Pattern**: Optional service discovery integration - package can emit upload lifecycle events to NeverHub for distributed monitoring.
+
+**Example Integration**:
+```typescript
+// If NeverHub is available, emit events
+if (typeof detectNeverHub === 'function') {
+  uploader.on('upload.completed', (result) => {
+    neverhub.emit('file-uploader.upload.completed', result);
+  });
+}
+```
+
+### Docs-Suite Integration
+**Status**: ✅ Ready
+
+TypeDoc-compatible JSDoc comments are included throughout the source code. All public APIs are documented with examples and type information.
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.
+

package/__tests__/file-uploader.test.ts

@@ -0,0 +1,517 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { FileUploader } from '../src';
+import { IncomingMessage } from 'http';
+import { Readable } from 'stream';
+import type { FileInfo } from '../src/types';
+
+// Mock @bernierllc/logger
+jest.mock('@bernierllc/logger', () => ({
+  createLogger: jest.fn(() => ({
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn()
+  }))
+}));
+
+/**
+ * Create a mock multipart request
+ */
+function createMockRequest(parts: { fieldname: string; filename: string; mimeType: string; data: Buffer }[]): IncomingMessage {
+  const boundary = '----WebKitFormBoundary7MA4YWxkTrZu0gW';
+
+  let body = '';
+  for (const part of parts) {
+    body += `--${boundary}\r\n`;
+    body += `Content-Disposition: form-data; name="${part.fieldname}"; filename="${part.filename}"\r\n`;
+    body += `Content-Type: ${part.mimeType}\r\n\r\n`;
+    body += part.data.toString('binary');
+    body += '\r\n';
+  }
+  body += `--${boundary}--\r\n`;
+
+  const stream = new Readable();
+  stream.push(Buffer.from(body, 'binary'));
+  stream.push(null);
+
+  const req = stream as IncomingMessage;
+  req.headers = {
+    'content-type': `multipart/form-data; boundary=${boundary}`
+  };
+
+  return req;
+}
+
+describe('FileUploader', () => {
+  let uploader: FileUploader;
+
+  beforeEach(() => {
+    uploader = new FileUploader({
+      maxFileSize: 1024 * 1024, // 1MB
+      allowedMimeTypes: ['image/jpeg', 'image/png']
+    });
+  });
+
+  describe('constructor', () => {
+    it('should create a file uploader with default config', () => {
+      const defaultUploader = new FileUploader();
+      expect(defaultUploader).toBeInstanceOf(FileUploader);
+    });
+
+    it('should create a file uploader with custom config', () => {
+      expect(uploader).toBeInstanceOf(FileUploader);
+    });
+
+    it('should accept destination as string', () => {
+      const uploaderWithDestination = new FileUploader({
+        destination: '/custom/path'
+      });
+      expect(uploaderWithDestination).toBeInstanceOf(FileUploader);
+    });
+
+    it('should accept destination as function', () => {
+      const uploaderWithDestination = new FileUploader({
+        destination: async (file: FileInfo) => `/custom/${file.filename}`
+      });
+      expect(uploaderWithDestination).toBeInstanceOf(FileUploader);
+    });
+
+    it('should accept onProgress callback', () => {
+      const onProgress = jest.fn();
+      const uploaderWithProgress = new FileUploader({
+        onProgress
+      });
+      expect(uploaderWithProgress).toBeInstanceOf(FileUploader);
+    });
+  });
+
+  describe('validateFile', () => {
+    it('should validate file with allowed MIME type', () => {
+      const fileInfo: FileInfo = {
+        fieldname: 'file',
+        filename: 'test.jpg',
+        encoding: '7bit',
+        mimeType: 'image/jpeg',
+        size: 1000
+      };
+
+      const result = uploader.validateFile(fileInfo);
+      expect(result.valid).toBe(true);
+      expect(result.error).toBeUndefined();
+    });
+
+    it('should reject invalid MIME types', () => {
+      const fileInfo: FileInfo = {
+        fieldname: 'file',
+        filename: 'test.exe',
+        encoding: '7bit',
+        mimeType: 'application/x-msdownload',
+        size: 1000
+      };
+
+      const result = uploader.validateFile(fileInfo);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('MIME type');
+      expect(result.error).toContain('application/x-msdownload');
+    });
+
+    it('should reject files exceeding size limit', () => {
+      const fileInfo: FileInfo = {
+        fieldname: 'file',
+        filename: 'test.jpg',
+        encoding: '7bit',
+        mimeType: 'image/jpeg',
+        size: 2 * 1024 * 1024 // 2MB
+      };
+
+      const result = uploader.validateFile(fileInfo);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('File size');
+      expect(result.error).toContain('exceeds maximum');
+    });
+
+    it('should accept files when no MIME type restrictions', () => {
+      const noMimeUploader = new FileUploader({
+        maxFileSize: 1024 * 1024
+      });
+
+      const fileInfo: FileInfo = {
+        fieldname: 'file',
+        filename: 'test.exe',
+        encoding: '7bit',
+        mimeType: 'application/x-msdownload',
+        size: 1000
+      };
+
+      const result = noMimeUploader.validateFile(fileInfo);
+      expect(result.valid).toBe(true);
+    });
+
+    it('should accept files at size limit boundary', () => {
+      const fileInfo: FileInfo = {
+        fieldname: 'file',
+        filename: 'test.jpg',
+        encoding: '7bit',
+        mimeType: 'image/jpeg',
+        size: 1024 * 1024 // Exactly 1MB
+      };
+
+      const result = uploader.validateFile(fileInfo);
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe('handleMultipart', () => {
+    it('should handle single file upload', async () => {
+      const mockData = Buffer.from('test file content');
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'test.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      const results = await uploader.handleMultipart(req);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].filename).toBe('test.jpg');
+      expect(results[0].mimeType).toBe('image/jpeg');
+      expect(results[0].size).toBe(mockData.length);
+      expect(results[0].fileId).toBeDefined();
+      expect(results[0].destination).toContain('test.jpg');
+    });
+
+    it('should handle multiple file uploads', async () => {
+      const mockData1 = Buffer.from('file 1 content');
+      const mockData2 = Buffer.from('file 2 content');
+
+      const req = createMockRequest([
+        {
+          fieldname: 'file1',
+          filename: 'test1.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData1
+        },
+        {
+          fieldname: 'file2',
+          filename: 'test2.png',
+          mimeType: 'image/png',
+          data: mockData2
+        }
+      ]);
+
+      const results = await uploader.handleMultipart(req);
+
+      expect(results).toHaveLength(2);
+      expect(results[0].filename).toBe('test1.jpg');
+      expect(results[1].filename).toBe('test2.png');
+    });
+
+    it('should reject when file count exceeds limit', async () => {
+      const uploaderWithLimit = new FileUploader({
+        maxFiles: 1,
+        allowedMimeTypes: ['image/jpeg', 'image/png']
+      });
+
+      const mockData1 = Buffer.from('file 1');
+      const mockData2 = Buffer.from('file 2');
+
+      const req = createMockRequest([
+        {
+          fieldname: 'file1',
+          filename: 'test1.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData1
+        },
+        {
+          fieldname: 'file2',
+          filename: 'test2.png',
+          mimeType: 'image/png',
+          data: mockData2
+        }
+      ]);
+
+      await expect(uploaderWithLimit.handleMultipart(req)).rejects.toThrow('Maximum file count exceeded');
+    });
+
+    it('should reject files with invalid MIME type during upload', async () => {
+      const mockData = Buffer.from('malicious content');
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'malware.exe',
+          mimeType: 'application/x-msdownload',
+          data: mockData
+        }
+      ]);
+
+      await expect(uploader.handleMultipart(req)).rejects.toThrow('MIME type');
+    });
+
+    it('should reject files exceeding size during upload', async () => {
+      const mockData = Buffer.alloc(2 * 1024 * 1024); // 2MB
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'large.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      await expect(uploader.handleMultipart(req)).rejects.toThrow('File size exceeded');
+    });
+
+    it('should call onProgress callback during upload', async () => {
+      const onProgress = jest.fn();
+      const uploaderWithProgress = new FileUploader({
+        maxFileSize: 1024 * 1024,
+        allowedMimeTypes: ['image/jpeg'],
+        onProgress
+      });
+
+      const mockData = Buffer.from('test content for progress tracking');
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'test.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      await uploaderWithProgress.handleMultipart(req);
+
+      expect(onProgress).toHaveBeenCalled();
+      const lastCall = onProgress.mock.calls[onProgress.mock.calls.length - 1][0];
+      expect(lastCall.percentage).toBe(100);
+      expect(lastCall.bytesUploaded).toBe(mockData.length);
+      expect(lastCall.totalBytes).toBe(mockData.length);
+    });
+
+    it('should use custom destination string', async () => {
+      const uploaderWithDest = new FileUploader({
+        destination: '/custom/uploads',
+        allowedMimeTypes: ['image/jpeg']
+      });
+
+      const mockData = Buffer.from('test');
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'test.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      const results = await uploaderWithDest.handleMultipart(req);
+      expect(results[0].destination).toBe('/custom/uploads');
+    });
+
+    it('should use custom destination function', async () => {
+      const uploaderWithDest = new FileUploader({
+        destination: async (file: FileInfo) => `/custom/${file.filename}`,
+        allowedMimeTypes: ['image/jpeg']
+      });
+
+      const mockData = Buffer.from('test');
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'test.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      const results = await uploaderWithDest.handleMultipart(req);
+      expect(results[0].destination).toBe('/custom/test.jpg');
+    });
+
+    it('should handle busboy error', async () => {
+      const req = new Readable() as IncomingMessage;
+      req.headers = {
+        'content-type': 'invalid-content-type'
+      };
+      req.push('invalid data');
+      req.push(null);
+
+      await expect(uploader.handleMultipart(req)).rejects.toThrow();
+    });
+
+    it('should calculate progress percentage correctly', async () => {
+      const progressUpdates: number[] = [];
+      const uploaderWithProgress = new FileUploader({
+        maxFileSize: 1024 * 1024,
+        allowedMimeTypes: ['image/jpeg'],
+        onProgress: (progress) => {
+          progressUpdates.push(progress.percentage);
+        }
+      });
+
+      const mockData = Buffer.from('test content');
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'test.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      await uploaderWithProgress.handleMultipart(req);
+
+      expect(progressUpdates.length).toBeGreaterThan(0);
+      expect(progressUpdates[progressUpdates.length - 1]).toBe(100);
+    });
+  });
+
+  describe('getProgress', () => {
+    it('should return null for unknown file ID', () => {
+      const progress = uploader.getProgress('unknown-id');
+      expect(progress).toBeNull();
+    });
+
+    it('should return progress during active upload', async () => {
+      const onProgress = jest.fn();
+      const uploaderWithProgress = new FileUploader({
+        maxFileSize: 1024 * 1024,
+        allowedMimeTypes: ['image/jpeg'],
+        onProgress
+      });
+
+      const mockData = Buffer.from('test');
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'test.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      await uploaderWithProgress.handleMultipart(req);
+
+      // Progress should be cleared after upload completes
+      const fileId = onProgress.mock.calls[0][0].fileId;
+      const progress = uploaderWithProgress.getProgress(fileId);
+      expect(progress).toBeNull(); // Cleared after completion
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty file', async () => {
+      const mockData = Buffer.alloc(0);
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'empty.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      const results = await uploader.handleMultipart(req);
+      expect(results).toHaveLength(1);
+      expect(results[0].size).toBe(0);
+    });
+
+    it('should handle special characters in filename', async () => {
+      const mockData = Buffer.from('test');
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'test file (1) [copy].jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      const results = await uploader.handleMultipart(req);
+      expect(results).toHaveLength(1);
+      expect(results[0].filename).toBe('test file (1) [copy].jpg');
+    });
+
+    it('should handle no files in request', async () => {
+      const req = createMockRequest([]);
+
+      const results = await uploader.handleMultipart(req);
+      expect(results).toHaveLength(0);
+    });
+
+    it('should handle mixed valid and invalid files', async () => {
+      const mockData1 = Buffer.from('valid file');
+      const mockData2 = Buffer.from('invalid file');
+
+      const req = createMockRequest([
+        {
+          fieldname: 'file1',
+          filename: 'test.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData1
+        },
+        {
+          fieldname: 'file2',
+          filename: 'malware.exe',
+          mimeType: 'application/x-msdownload',
+          data: mockData2
+        }
+      ]);
+
+      await expect(uploader.handleMultipart(req)).rejects.toThrow('MIME type');
+    });
+
+    it('should handle destination function throwing non-Error', async () => {
+      const uploaderWithThrowingDest = new FileUploader({
+        destination: () => {
+          // eslint-disable-next-line @typescript-eslint/no-throw-literal
+          throw 'String error';
+        },
+        allowedMimeTypes: ['image/jpeg']
+      });
+
+      const mockData = Buffer.from('test');
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'test.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      await expect(uploaderWithThrowingDest.handleMultipart(req)).rejects.toThrow();
+    });
+
+    it('should handle destination function throwing Error', async () => {
+      const uploaderWithErrorDest = new FileUploader({
+        destination: () => {
+          throw new Error('Custom destination error');
+        },
+        allowedMimeTypes: ['image/jpeg']
+      });
+
+      const mockData = Buffer.from('test');
+      const req = createMockRequest([
+        {
+          fieldname: 'file',
+          filename: 'test.jpg',
+          mimeType: 'image/jpeg',
+          data: mockData
+        }
+      ]);
+
+      await expect(uploaderWithErrorDest.handleMultipart(req)).rejects.toThrow('Custom destination error');
+    });
+  });
+});