@opensaas/stack-storage 0.1.1

package/tests/local-provider.test.ts

@@ -0,0 +1,349 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { LocalStorageProvider } from '../src/providers/local.js'
+import type { LocalStorageConfig } from '../src/config/types.js'
+
+// Mock Node.js filesystem modules
+vi.mock('node:fs/promises', () => ({
+  default: {
+    access: vi.fn(),
+    mkdir: vi.fn(),
+    writeFile: vi.fn(),
+    readFile: vi.fn(),
+    unlink: vi.fn(),
+    stat: vi.fn(),
+  },
+}))
+
+vi.mock('node:crypto', () => ({
+  randomBytes: vi.fn((size: number) => ({
+    toString: () => 'a'.repeat(size * 2), // Hex string is 2x the byte length
+  })),
+}))
+
+describe('LocalStorageProvider', () => {
+  let fs: typeof import('node:fs/promises').default
+
+  beforeEach(async () => {
+    vi.clearAllMocks()
+    fs = (await import('node:fs/promises')).default
+
+    // Default mock implementations
+    fs.access.mockResolvedValue(undefined)
+    fs.mkdir.mockResolvedValue(undefined)
+    fs.writeFile.mockResolvedValue(undefined)
+    fs.readFile.mockResolvedValue(Buffer.from('file-contents'))
+    fs.unlink.mockResolvedValue(undefined)
+    fs.stat.mockResolvedValue({ size: 12345 })
+  })
+
+  describe('constructor', () => {
+    it('should create instance with config', () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+
+      const provider = new LocalStorageProvider(config)
+
+      expect(provider).toBeInstanceOf(LocalStorageProvider)
+    })
+  })
+
+  describe('upload', () => {
+    it('should upload file successfully', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+      const fileBuffer = Buffer.from('test file content')
+      const filename = 'test.txt'
+
+      const result = await provider.upload(fileBuffer, filename)
+
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        expect.stringMatching(/uploads\/\d+-.*\.txt$/),
+        fileBuffer,
+      )
+      expect(result.url).toMatch(/\/uploads\/\d+-.*\.txt/)
+      expect(result.size).toBe(12345)
+      expect(result.contentType).toBe('application/octet-stream')
+    })
+
+    it('should create upload directory if it does not exist', async () => {
+      fs.access.mockRejectedValueOnce(new Error('Directory does not exist'))
+
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './new-uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      await provider.upload(Buffer.from('test'), 'test.txt')
+
+      expect(fs.mkdir).toHaveBeenCalledWith('./new-uploads', { recursive: true })
+    })
+
+    it('should not create directory if it already exists', async () => {
+      fs.access.mockResolvedValueOnce(undefined)
+
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './existing-uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      await provider.upload(Buffer.from('test'), 'test.txt')
+
+      expect(fs.mkdir).not.toHaveBeenCalled()
+    })
+
+    it('should generate unique filenames by default', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      const result1 = await provider.upload(Buffer.from('test1'), 'test.txt')
+      const result2 = await provider.upload(Buffer.from('test2'), 'test.txt')
+
+      expect(result1.filename).not.toBe('test.txt')
+      expect(result2.filename).not.toBe('test.txt')
+      expect(result1.filename).toMatch(/\d+-[a-f0-9]+\.txt/)
+      expect(result2.filename).toMatch(/\d+-[a-f0-9]+\.txt/)
+    })
+
+    it('should preserve original filename when generateUniqueFilenames is false', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+        generateUniqueFilenames: false,
+      }
+      const provider = new LocalStorageProvider(config)
+
+      const result = await provider.upload(Buffer.from('test'), 'original.txt')
+
+      expect(result.filename).toBe('original.txt')
+      expect(result.url).toBe('/uploads/original.txt')
+    })
+
+    it('should preserve file extension when generating unique names', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      const resultTxt = await provider.upload(Buffer.from('test'), 'file.txt')
+      const resultJpg = await provider.upload(Buffer.from('test'), 'photo.jpg')
+      const resultNoExt = await provider.upload(Buffer.from('test'), 'noext')
+
+      expect(resultTxt.filename).toMatch(/\.txt$/)
+      expect(resultJpg.filename).toMatch(/\.jpg$/)
+      expect(resultNoExt.filename).not.toMatch(/\./)
+    })
+
+    it('should use provided content type', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      const result = await provider.upload(Buffer.from('test'), 'test.txt', {
+        contentType: 'text/plain',
+      })
+
+      expect(result.contentType).toBe('text/plain')
+    })
+
+    it('should store custom metadata', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+      const metadata = { uploadedBy: 'user123', category: 'documents' }
+
+      const result = await provider.upload(Buffer.from('test'), 'test.txt', { metadata })
+
+      expect(result.metadata).toEqual(metadata)
+    })
+
+    it('should handle Uint8Array input', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+      const uint8Array = new Uint8Array([1, 2, 3, 4, 5])
+
+      await provider.upload(uint8Array, 'binary.dat')
+
+      expect(fs.writeFile).toHaveBeenCalledWith(expect.any(String), uint8Array)
+    })
+
+    it('should construct correct file path', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './my-uploads',
+        serveUrl: '/files',
+        generateUniqueFilenames: false,
+      }
+      const provider = new LocalStorageProvider(config)
+
+      await provider.upload(Buffer.from('test'), 'test.txt')
+
+      expect(fs.writeFile).toHaveBeenCalledWith('my-uploads/test.txt', expect.any(Buffer))
+    })
+
+    it('should return correct URL', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: 'https://example.com/files',
+        generateUniqueFilenames: false,
+      }
+      const provider = new LocalStorageProvider(config)
+
+      const result = await provider.upload(Buffer.from('test'), 'photo.jpg')
+
+      expect(result.url).toBe('https://example.com/files/photo.jpg')
+    })
+  })
+
+  describe('download', () => {
+    it('should download file successfully', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+      const expectedBuffer = Buffer.from('downloaded file content')
+      fs.readFile.mockResolvedValueOnce(expectedBuffer)
+
+      const result = await provider.download('test-file.txt')
+
+      expect(fs.readFile).toHaveBeenCalledWith('uploads/test-file.txt')
+      expect(result).toBe(expectedBuffer)
+    })
+
+    it('should construct correct file path for download', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './my-storage',
+        serveUrl: '/files',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      await provider.download('document.pdf')
+
+      expect(fs.readFile).toHaveBeenCalledWith('my-storage/document.pdf')
+    })
+
+    it('should propagate filesystem errors', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+      fs.readFile.mockRejectedValueOnce(new Error('File not found'))
+
+      await expect(provider.download('nonexistent.txt')).rejects.toThrow('File not found')
+    })
+  })
+
+  describe('delete', () => {
+    it('should delete file successfully', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      await provider.delete('file-to-delete.txt')
+
+      expect(fs.unlink).toHaveBeenCalledWith('uploads/file-to-delete.txt')
+    })
+
+    it('should construct correct file path for deletion', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './my-storage/files',
+        serveUrl: '/files',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      await provider.delete('old-file.jpg')
+
+      expect(fs.unlink).toHaveBeenCalledWith('my-storage/files/old-file.jpg')
+    })
+
+    it('should propagate filesystem errors on delete', async () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+      fs.unlink.mockRejectedValueOnce(new Error('Permission denied'))
+
+      await expect(provider.delete('protected.txt')).rejects.toThrow('Permission denied')
+    })
+  })
+
+  describe('getUrl', () => {
+    it('should return correct URL for filename', () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      const url = provider.getUrl('photo.jpg')
+
+      expect(url).toBe('/uploads/photo.jpg')
+    })
+
+    it('should work with custom serve URL', () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './storage',
+        serveUrl: 'https://cdn.example.com/files',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      const url = provider.getUrl('document.pdf')
+
+      expect(url).toBe('https://cdn.example.com/files/document.pdf')
+    })
+
+    it('should handle filenames with special characters', () => {
+      const config: LocalStorageConfig = {
+        type: 'local',
+        uploadDir: './uploads',
+        serveUrl: '/uploads',
+      }
+      const provider = new LocalStorageProvider(config)
+
+      const url = provider.getUrl('my file (1).txt')
+
+      expect(url).toBe('/uploads/my file (1).txt')
+    })
+  })
+})

package/tests/upload-utils.test.ts

@@ -0,0 +1,313 @@
+import { describe, it, expect } from 'vitest'
+import {
+  validateFile,
+  formatFileSize,
+  getMimeType,
+  fileToBuffer,
+  parseFileFromFormData,
+  type FileValidationOptions,
+} from '../src/utils/upload.js'
+
+describe('Upload Utilities', () => {
+  describe('validateFile', () => {
+    it('should return valid when no options provided', () => {
+      const file = { size: 1000, name: 'test.txt', type: 'text/plain' }
+      const result = validateFile(file)
+      expect(result.valid).toBe(true)
+      expect(result.error).toBeUndefined()
+    })
+
+    it('should return valid when options are empty', () => {
+      const file = { size: 1000, name: 'test.txt', type: 'text/plain' }
+      const result = validateFile(file, {})
+      expect(result.valid).toBe(true)
+    })
+
+    describe('file size validation', () => {
+      it('should accept files within size limit', () => {
+        const file = { size: 1000, name: 'test.txt', type: 'text/plain' }
+        const options: FileValidationOptions = { maxFileSize: 2000 }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(true)
+      })
+
+      it('should reject files exceeding size limit', () => {
+        const file = { size: 3000, name: 'test.txt', type: 'text/plain' }
+        const options: FileValidationOptions = { maxFileSize: 2000 }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(false)
+        expect(result.error).toContain('File size exceeds maximum')
+        expect(result.error).toContain('1.95 KB')
+      })
+
+      it('should accept files exactly at size limit', () => {
+        const file = { size: 2000, name: 'test.txt', type: 'text/plain' }
+        const options: FileValidationOptions = { maxFileSize: 2000 }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(true)
+      })
+    })
+
+    describe('MIME type validation', () => {
+      it('should accept files with allowed MIME type', () => {
+        const file = { size: 1000, name: 'test.jpg', type: 'image/jpeg' }
+        const options: FileValidationOptions = {
+          acceptedMimeTypes: ['image/jpeg', 'image/png'],
+        }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(true)
+      })
+
+      it('should reject files with disallowed MIME type', () => {
+        const file = { size: 1000, name: 'test.gif', type: 'image/gif' }
+        const options: FileValidationOptions = {
+          acceptedMimeTypes: ['image/jpeg', 'image/png'],
+        }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(false)
+        expect(result.error).toContain('File type')
+        expect(result.error).toContain('image/gif')
+        expect(result.error).toContain('image/jpeg')
+      })
+
+      it('should fall back to filename extension when type is empty', () => {
+        const file = { size: 1000, name: 'test.jpg', type: '' }
+        const options: FileValidationOptions = {
+          acceptedMimeTypes: ['image/jpeg'],
+        }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(true)
+      })
+
+      it('should reject unknown MIME types when restrictions exist', () => {
+        const file = { size: 1000, name: 'test.xyz', type: '' }
+        const options: FileValidationOptions = {
+          acceptedMimeTypes: ['image/jpeg'],
+        }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(false)
+      })
+    })
+
+    describe('file extension validation', () => {
+      it('should accept files with allowed extension', () => {
+        const file = { size: 1000, name: 'test.jpg', type: 'image/jpeg' }
+        const options: FileValidationOptions = {
+          acceptedExtensions: ['.jpg', '.png'],
+        }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(true)
+      })
+
+      it('should reject files with disallowed extension', () => {
+        const file = { size: 1000, name: 'test.gif', type: 'image/gif' }
+        const options: FileValidationOptions = {
+          acceptedExtensions: ['.jpg', '.png'],
+        }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(false)
+        expect(result.error).toContain('File extension')
+        expect(result.error).toContain('.gif')
+      })
+
+      it('should handle case-insensitive extensions', () => {
+        const file = { size: 1000, name: 'test.JPG', type: 'image/jpeg' }
+        const options: FileValidationOptions = {
+          acceptedExtensions: ['.jpg'],
+        }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(true)
+      })
+
+      it('should handle files with multiple dots in name', () => {
+        const file = { size: 1000, name: 'my.test.file.jpg', type: 'image/jpeg' }
+        const options: FileValidationOptions = {
+          acceptedExtensions: ['.jpg'],
+        }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(true)
+      })
+    })
+
+    describe('combined validation', () => {
+      it('should validate all criteria when multiple options provided', () => {
+        const file = { size: 1000, name: 'test.jpg', type: 'image/jpeg' }
+        const options: FileValidationOptions = {
+          maxFileSize: 2000,
+          acceptedMimeTypes: ['image/jpeg'],
+          acceptedExtensions: ['.jpg'],
+        }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(true)
+      })
+
+      it('should fail if any criterion is not met', () => {
+        const file = { size: 3000, name: 'test.jpg', type: 'image/jpeg' }
+        const options: FileValidationOptions = {
+          maxFileSize: 2000,
+          acceptedMimeTypes: ['image/jpeg'],
+          acceptedExtensions: ['.jpg'],
+        }
+        const result = validateFile(file, options)
+        expect(result.valid).toBe(false)
+      })
+    })
+  })
+
+  describe('formatFileSize', () => {
+    it('should format 0 bytes', () => {
+      expect(formatFileSize(0)).toBe('0 Bytes')
+    })
+
+    it('should format bytes', () => {
+      expect(formatFileSize(500)).toBe('500 Bytes')
+      expect(formatFileSize(1023)).toBe('1023 Bytes')
+    })
+
+    it('should format kilobytes', () => {
+      expect(formatFileSize(1024)).toBe('1 KB')
+      expect(formatFileSize(2048)).toBe('2 KB')
+      expect(formatFileSize(1536)).toBe('1.5 KB')
+    })
+
+    it('should format megabytes', () => {
+      expect(formatFileSize(1024 * 1024)).toBe('1 MB')
+      expect(formatFileSize(5 * 1024 * 1024)).toBe('5 MB')
+      expect(formatFileSize(1.5 * 1024 * 1024)).toBe('1.5 MB')
+    })
+
+    it('should format gigabytes', () => {
+      expect(formatFileSize(1024 * 1024 * 1024)).toBe('1 GB')
+      expect(formatFileSize(2.5 * 1024 * 1024 * 1024)).toBe('2.5 GB')
+    })
+
+    it('should round to 2 decimal places', () => {
+      expect(formatFileSize(1536)).toBe('1.5 KB')
+      expect(formatFileSize(1555)).toBe('1.52 KB')
+      expect(formatFileSize(1666)).toBe('1.63 KB')
+    })
+  })
+
+  describe('getMimeType', () => {
+    it('should return correct MIME type for common extensions', () => {
+      expect(getMimeType('test.jpg')).toBe('image/jpeg')
+      expect(getMimeType('test.jpeg')).toBe('image/jpeg')
+      expect(getMimeType('test.png')).toBe('image/png')
+      expect(getMimeType('test.gif')).toBe('image/gif')
+      expect(getMimeType('test.pdf')).toBe('application/pdf')
+      expect(getMimeType('test.txt')).toBe('text/plain')
+      expect(getMimeType('test.html')).toBe('text/html')
+      expect(getMimeType('test.json')).toBe('application/json')
+    })
+
+    it('should handle uppercase extensions', () => {
+      expect(getMimeType('test.JPG')).toBe('image/jpeg')
+      expect(getMimeType('test.PNG')).toBe('image/png')
+    })
+
+    it('should return default MIME type for unknown extensions', () => {
+      // Note: .xyz is recognized by mime-types as 'chemical/x-xyz'
+      // Using a truly unknown extension instead
+      expect(getMimeType('test.unknownext')).toBe('application/octet-stream')
+      expect(getMimeType('noextension')).toBe('application/octet-stream')
+    })
+
+    it('should handle files with multiple dots', () => {
+      expect(getMimeType('my.test.file.jpg')).toBe('image/jpeg')
+    })
+  })
+
+  describe('fileToBuffer', () => {
+    it('should convert File to Buffer', async () => {
+      // Create a mock File object
+      const content = 'test file content'
+      const blob = new Blob([content], { type: 'text/plain' })
+      const file = new File([blob], 'test.txt', { type: 'text/plain' })
+
+      const buffer = await fileToBuffer(file)
+
+      expect(buffer).toBeInstanceOf(Buffer)
+      expect(buffer.toString()).toBe(content)
+    })
+
+    it('should convert Blob to Buffer', async () => {
+      const content = 'test blob content'
+      const blob = new Blob([content], { type: 'text/plain' })
+
+      const buffer = await fileToBuffer(blob)
+
+      expect(buffer).toBeInstanceOf(Buffer)
+      expect(buffer.toString()).toBe(content)
+    })
+
+    it('should handle binary data', async () => {
+      const binaryData = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]) // "Hello"
+      const blob = new Blob([binaryData])
+
+      const buffer = await fileToBuffer(blob)
+
+      expect(buffer).toBeInstanceOf(Buffer)
+      expect(buffer.toString()).toBe('Hello')
+    })
+  })
+
+  describe('parseFileFromFormData', () => {
+    it('should extract file from FormData with default field name', async () => {
+      const content = 'test file content'
+      const file = new File([content], 'test.txt', { type: 'text/plain' })
+      const formData = new FormData()
+      formData.append('file', file)
+
+      const result = await parseFileFromFormData(formData)
+
+      expect(result).not.toBeNull()
+      expect(result!.file).toBeInstanceOf(File)
+      expect(result!.file.name).toBe('test.txt')
+      expect(result!.buffer).toBeInstanceOf(Buffer)
+      expect(result!.buffer.toString()).toBe(content)
+    })
+
+    it('should extract file from FormData with custom field name', async () => {
+      const content = 'custom field content'
+      const file = new File([content], 'custom.txt', { type: 'text/plain' })
+      const formData = new FormData()
+      formData.append('customField', file)
+
+      const result = await parseFileFromFormData(formData, 'customField')
+
+      expect(result).not.toBeNull()
+      expect(result!.file.name).toBe('custom.txt')
+      expect(result!.buffer.toString()).toBe(content)
+    })
+
+    it('should return null when field does not exist', async () => {
+      const formData = new FormData()
+
+      const result = await parseFileFromFormData(formData)
+
+      expect(result).toBeNull()
+    })
+
+    it('should return null when field is not a File', async () => {
+      const formData = new FormData()
+      formData.append('file', 'not a file')
+
+      const result = await parseFileFromFormData(formData)
+
+      expect(result).toBeNull()
+    })
+
+    it('should handle multiple files but only return first', async () => {
+      const file1 = new File(['content1'], 'file1.txt')
+      const file2 = new File(['content2'], 'file2.txt')
+      const formData = new FormData()
+      formData.append('file', file1)
+      formData.append('file', file2)
+
+      const result = await parseFileFromFormData(formData)
+
+      expect(result).not.toBeNull()
+      expect(result!.file.name).toBe('file1.txt')
+    })
+  })
+})

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'json-summary'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/**/*.spec.ts', 'dist/**', 'node_modules/**'],
+    },
+  },
+})