@nuvix/storage 1.0.1 → 2.0.1

package/README.md

@@ -1,361 +1,247 @@
 # @nuvix/storage
 
-A powerful, TypeScript-first S3-compatible storage library for the Nuvix BaaS platform. Supports multiple storage backends including local filesystem, AWS S3, Wasabi, and MinIO with a unified API.
+A TypeScript-first storage library for the Nuvix BaaS platform, built entirely on [Bun](https://bun.sh)'s native APIs (`Bun.file`, `Bun.S3Client`). Provides a unified API across local filesystem, AWS S3, Wasabi, and MinIO — with zero runtime dependencies.
 
-## ✨ Features
+## Requirements
 
-- 🚀 **S3-Compatible API** - Consistent interface across all storage providers
-- 🔌 **Multiple Storage Backends** - Local, AWS S3, Wasabi, MinIO, and more
-- 📝 **TypeScript First** - Full type safety with comprehensive TypeScript definitions
-- ✅ **File Validation** - Built-in validators for file types, sizes, names, and extensions
-- 🔄 **Chunked Uploads** - Support for large file uploads with multipart upload
-- 🌐 **Modern Builds** - ESM and CommonJS support for maximum compatibility
-- 🧪 **Well Tested** - Comprehensive test suite with real implementation testing
+- **[Bun](https://bun.sh) >= 1.2.0** (required at runtime — this library is Bun-only)
 
-## 📦 Installation
+## Features
 
-```bash
-# Using npm
-npm install @nuvix/storage
-
-# Using yarn
-yarn add @nuvix/storage
+- 🚀 **Zero dependencies** — signing, multipart uploads, and XML parsing are handled natively by `Bun.S3Client`
+- 🔌 **Multiple backends** — Local filesystem, AWS S3, Wasabi, and MinIO behind one interface
+- ✍️ **Options-object constructors** — explicit, typed configuration for every device
+- 🔏 **Presigned URLs** — generate time-limited upload/download URLs offline (no network call)
+- 📊 **File stats** — size + MIME type in a single `stat()` call
+- 🔄 **Chunked uploads** — large files assembled from ordered chunks, with abort support
+- 🛡️ **Typed errors** — every failure throws a `StorageError` with a machine-readable `code`
+- ✅ **Validators** — file extension, name, size, content type (magic bytes), and upload checks
 
-# Using pnpm
-pnpm add @nuvix/storage
+## Installation
 
-# Using bun
+```bash
 bun add @nuvix/storage
 ```
 
-## 🚀 Quick Start
-
-### ESM (Modern)
+## Quick Start
 
 ```typescript
-import {
-  Storage,
-  Local,
-  Wasabi,
-  MinIO,
-  FileExt,
-  FileSize,
-} from "@nuvix/storage";
-
-// Set up local storage
-const localStorage = new Local("./uploads");
-Storage.setDevice(Storage.DEVICE_LOCAL, localStorage);
-
-// Upload a file
-const localDevice = Storage.getDevice(Storage.DEVICE_LOCAL);
-await localDevice.write("test.txt", "Hello, World!", "text/plain");
-```
+import { Storage, Local } from "@nuvix/storage";
 
-### CommonJS (Legacy)
-
-```javascript
-const { Storage, Local, Wasabi, MinIO } = require("@nuvix/storage");
-
-// Set up local storage
 const localStorage = new Local("./uploads");
 Storage.setDevice(Storage.DEVICE_LOCAL, localStorage);
-```
-
-## 🔧 Storage Devices
 
-### Local File System
-
-```typescript
-import { Local, Storage } from "@nuvix/storage";
-
-const localStorage = new Local("./uploads");
-Storage.setDevice("local", localStorage);
+const device = Storage.getDevice(Storage.DEVICE_LOCAL);
+await device.write("hello.txt", "Hello, World!", "text/plain");
 
-// Write file
-await localStorage.write("documents/file.txt", "content", "text/plain");
-
-// Read file
-const content = await localStorage.read("documents/file.txt");
-
-// Check if file exists
-const exists = await localStorage.exists("documents/file.txt");
+console.log(await device.read("hello.txt")); // Buffer("Hello, World!")
 ```
 
-### Wasabi Cloud Storage
-
-```typescript
-import { Wasabi, Storage } from "@nuvix/storage";
-
-const wasabiStorage = new Wasabi(
-  "my-app-uploads", // root path
-  "your-access-key", // access key
-  "your-secret-key", // secret key
-  "your-bucket-name", // bucket name
-  Wasabi.US_CENTRAL_1, // region
-  Wasabi.ACL_PRIVATE, // ACL (optional)
-);
-
-Storage.setDevice("wasabi", wasabiStorage);
-
-// Upload with metadata
-await wasabiStorage.uploadData(
-  "Hello, Cloud!",
-  "cloud-file.txt",
-  "text/plain",
-  1,
-  1,
-  { author: "user123" },
-);
-```
+## Storage Devices
 
-### AWS S3
+### Local Filesystem
 
 ```typescript
-import { S3, Storage } from "@nuvix/storage";
-
-const s3Storage = new S3(
-  "my-app-uploads", // root path
-  "your-access-key", // access key
-  "your-secret-key", // secret key
-  "your-bucket-name", // bucket name
-  S3.US_EAST_1, // region
-  S3.ACL_PRIVATE, // ACL (optional)
-);
-
-Storage.setDevice("s3", s3Storage);
-```
-
-### MinIO
-
-```typescript
-import { MinIO, Storage } from "@nuvix/storage";
-
-const minioStorage = new MinIO(
-  "my-app-uploads", // root path
-  "minioadmin", // access key (default MinIO credentials)
-  "minioadmin", // secret key (default MinIO credentials)
-  "your-bucket-name", // bucket name
-  "localhost:9000", // MinIO endpoint
-  MinIO.ACL_PRIVATE, // ACL (optional)
-  false, // useSSL (optional, default: false)
-);
-
-Storage.setDevice("minio", minioStorage);
-
-// Upload to MinIO
-await minioStorage.write("local-file.txt", "Hello, MinIO!", "text/plain");
-
-// Read from MinIO
-const content = await minioStorage.read("local-file.txt");
+import { Local } from "@nuvix/storage";
 
-// Check if file exists
-const exists = await minioStorage.exists("local-file.txt");
+// Root defaults to the current working directory
+const device = new Local("./uploads");
 
-// Get file information
-const size = await minioStorage.getFileSize("local-file.txt");
-const mimeType = await minioStorage.getFileMimeType("local-file.txt");
+await device.write("docs/report.pdf", buffer);
+await device.exists("docs/report.pdf"); // true
+await device.stat("docs/report.pdf");   // { size, mimeType }
 ```
 
-## 🛡️ File Validation
-
-### File Extension Validation
+### AWS S3
 
 ```typescript
-import { FileExt } from "@nuvix/storage";
+import { S3 } from "@nuvix/storage";
 
-const imageValidator = new FileExt(["jpg", "png", "gif", "webp"]);
+const device = new S3({
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "your-bucket",
+  region: S3.US_EAST_1,       // default
+  acl: S3.ACL_PRIVATE,        // optional
+  root: "app-uploads",        // optional key prefix
+  endpoint: "https://...",    // optional custom endpoint (path-style URLs)
+});
 
-console.log(imageValidator.isValid("photo.jpg")); // true
-console.log(imageValidator.isValid("document.pdf")); // false
+// Presigned URL — computed locally, no network round-trip
+const url = device.presign("reports/q3.pdf", { expiresIn: 3600 });
 ```
 
-### File Size Validation
+### Wasabi
 
 ```typescript
-import { FileSize } from "@nuvix/storage";
+import { Wasabi } from "@nuvix/storage";
 
-const sizeValidator = new FileSize(5 * 1024 * 1024); // 5MB limit
-
-console.log(sizeValidator.isValid(1024 * 1024)); // true (1MB)
-console.log(sizeValidator.isValid(10 * 1024 * 1024)); // false (10MB)
+// Endpoint is derived automatically: https://s3.{region}.wasabisys.com
+const device = new Wasabi({
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "your-bucket",
+  region: Wasabi.EU_CENTRAL_1, // default
+});
 ```
 
-### File Name Validation
+### MinIO
 
 ```typescript
-import { FileName } from "@nuvix/storage";
+import { MinIO } from "@nuvix/storage";
 
-const nameValidator = new FileName();
-
-console.log(nameValidator.isValid("validfile123.txt")); // true
-console.log(nameValidator.isValid("invalid-file.txt")); // false (contains hyphen)
+const device = new MinIO({
+  accessKeyId: "minioadmin",
+  secretAccessKey: "minioadmin",
+  bucket: "your-bucket",
+  endpoint: "localhost:9000", // default; protocol prefix is stripped
+  useSSL: false,              // default
+});
 ```
 
-### File Type (MIME) Validation
+## File Validation
 
 ```typescript
-import { FileType } from "@nuvix/storage";
-
-const typeValidator = new FileType(["jpeg", "png", "gif"]);
+import { FileExt, FileName, FileSize, FileType, Upload } from "@nuvix/storage";
 
-// Validates based on file content, not extension
-console.log(await typeValidator.isValid("./image.jpg")); // true if actual JPEG
-```
+new FileExt(["jpg", "png"]).isValid("photo.jpg");     // true
+new FileName().isValid("report_2024.pdf");            // true
+new FileSize(5 * 1024 * 1024).isValid(1024);          // true (< 5MB)
 
-### Upload File Validation
+// Content-type check via magic bytes — reads only the first few bytes of the file
+await new FileType([FileType.FILE_TYPE_PNG]).isValid("./maybe-image.png");
 
-```typescript
-import { Upload } from "@nuvix/storage";
-
-const uploadValidator = new Upload();
-
-console.log(await uploadValidator.isValid("./existing-file.txt")); // true
-console.log(await uploadValidator.isValid("./non-existent.txt")); // false
+// Verifies the file actually exists on disk
+await new Upload().isValid("./uploaded.txt");
 ```
 
-## 🔄 Advanced Features
+## Error Handling
 
-### Chunked Uploads
+All failures throw a `StorageError` with a stable `code` you can branch on:
 
 ```typescript
-// Upload large files in chunks
-const chunks = ["chunk1", "chunk2", "chunk3"];
-const metadata = {};
-
-for (let i = 0; i < chunks.length; i++) {
-  await device.uploadData(
-    chunks[i],
-    "large-file.txt",
-    "text/plain",
-    i + 1, // current chunk
-    chunks.length, // total chunks
-    metadata,
-  );
+import { StorageError } from "@nuvix/storage";
+
+try {
+  await device.read("missing.txt");
+} catch (error) {
+  if (error instanceof StorageError && error.code === "FILE_NOT_FOUND") {
+    // handle gracefully
+  }
 }
 ```
 
-### File Transfer Between Devices
+| Code | Thrown when |
+|------|-------------|
+| `DEVICE_NOT_FOUND` | `Storage.getDevice()` with an unregistered name |
+| `FILE_NOT_FOUND` | Reading/stat a missing file, or aborting an upload with no staged parts |
+| `WRITE_FAILED` / `READ_FAILED` | Filesystem or S3 I/O failure |
+| `UPLOAD_FAILED` | A chunk could not be staged |
+| `TRANSFER_FAILED` | Cross-device transfer failed mid-stream |
+| `DELETE_FAILED` | Deletion failed |
+| `UNSUPPORTED_OPERATION` | e.g. `presign()` on a device without support |
+| `INVALID_CONFIG` | Device constructed with missing credentials |
 
-```typescript
-const sourceDevice = Storage.getDevice("local");
-const targetDevice = Storage.getDevice("wasabi");
-
-// Transfer file from local to cloud
-await sourceDevice.transfer("local-file.txt", "cloud-file.txt", targetDevice);
-```
+## Chunked Uploads
 
-### Human-Readable File Sizes
+Upload large files in ordered chunks; the final chunk triggers assembly:
 
 ```typescript
-import { Storage } from "@nuvix/storage";
+const metadata = {};
+for (let chunk = 1; chunk <= totalChunks; chunk++) {
+  await device.uploadData(chunkBuffer, "big-file.bin", "application/octet-stream", chunk, totalChunks, metadata);
+}
 
-console.log(Storage.human(1024)); // "1.00kB"
-console.log(Storage.human(1048576)); // "1.00MB"
-console.log(Storage.human(1024, 2, "binary")); // "1.00KiB"
+// Or give up and clean any staged parts:
+await device.abort("big-file.bin");
 ```
 
-## 🏗️ Building
-
-The library is built using Rollup and provides both ESM and CommonJS outputs:
-
-```bash
-# Build for production
-bun run build
+## Device Registry & Utilities
 
-# Build and watch for changes
-bun run build:watch
+```typescript
+Storage.setDevice("avatars", device);   // register
+Storage.getDevice("avatars");           // retrieve (throws DEVICE_NOT_FOUND)
+Storage.exists("avatars");              // boolean
+Storage.listDevices();                  // string[]
+Storage.removeDevice("avatars");        // unregister
 
-# Clean build directory
-bun run clean
+Storage.human(1536);                    // "1.54kB"
+Storage.human(1048576, 2, "binary");    // "1.00MiB"
 ```
 
-## 🧪 Testing
+### Common Device Methods
 
-Comprehensive test suite with real implementation testing:
+Every device implements the same interface:
 
-```bash
-# Run all tests
-bun test
+- `write(path, data, contentType?)` / `read(path, offset?, length?)`
+- `upload(source, path, chunk?, chunks?, metadata?)` — move a file from disk into storage
+- `uploadData(data, path, contentType, chunk?, chunks?, metadata?)` — upload raw data
+- `exists(path)` / `delete(path)` / `deletePath(path)`
+- `stat(path)` → `{ size, mimeType }`
+- `getFileSize(path)` / `getFileMimeType(path)` / `getFileHash(path)` (MD5)
+- `transfer(source, destination, targetDevice)` / `move(source, target)`
+- `createDirectory(path)` / `getDirectorySize(path)` / `getFiles(dir)`
+- `presign(path, options?)` — presigned URL where supported
+- `getTransferChunkSize()` / `setTransferChunkSize(bytes)`
 
-# Run tests in watch mode
-bun run test:watch
+## Migrating from v1
 
-# Run tests with coverage
-bun run test:coverage
+v2.0.0 is a breaking release:
 
-# Run specific test files
-bun test storage.test.ts
-bun test device/
-bun test validator/
-```
+- **Bun only** — Node.js is no longer supported. The hand-rolled SigV4/XML client was replaced by `Bun.S3Client`.
+- **Constructors take a single options object** instead of positional arguments:
+  ```diff
+  - new S3("root", accessKey, secretKey, bucket, S3.US_EAST_1)
+  + new S3({ accessKeyId, secretAccessKey, bucket, region: S3.US_EAST_1, root: "root" })
+  ```
+- **ESM only** — CommonJS builds are no longer published.
+- **Errors are typed** — methods throw `StorageError` (with `.code`) instead of plain `Error`s or silent booleans.
+- **Fixed:** `S3.SA_EAST_1` now maps to `"sa-east-1"` (previously incorrectly mapped to `"eu-north-1"`).
+- **New:** `stat()`, `presign()`, `Storage.removeDevice()`, `Storage.listDevices()`, `move()`, `abort()`.
 
-### Testing with Real Cloud Storage
+See [MIGRATION.md](./MIGRATION.md) for the full step-by-step migration guide.
 
-Set environment variables to test against real storage services:
+## Development
 
 ```bash
-# For Wasabi testing
-export WASABI_ACCESS_KEY="your-access-key"
-export WASABI_SECRET_KEY="your-secret-key"
-export WASABI_BUCKET="your-test-bucket"
-
-# For AWS S3 testing
-export AWS_ACCESS_KEY="your-access-key"
-export AWS_SECRET_KEY="your-secret-key"
-export AWS_BUCKET="your-test-bucket"
-
-# For MinIO testing
-export MINIO_ACCESS_KEY="minioadmin"
-export MINIO_SECRET_KEY="minioadmin"
-export MINIO_BUCKET="test-bucket"
-export MINIO_ENDPOINT="localhost:9000"
+bun install              # install dev dependencies
+bun test                 # run offline test suite
+bun run test:watch       # watch mode
+bun run lint             # oxlint
+bun run typecheck        # tsc --noEmit
+bun run build            # bundle to dist/ (ESM + declarations)
 ```
 
-## 📝 API Reference
+The default suite is fully offline — cloud devices are exercised through offline-presign URL checks and config validation, so no credentials are ever needed.
 
-### Storage Class
+### Integration Tests
 
-- `Storage.setDevice(name, device)` - Register a storage device
-- `Storage.getDevice(name)` - Get a registered storage device
-- `Storage.exists(name)` - Check if a device is registered
-- `Storage.human(bytes, decimals?, system?)` - Format bytes to human-readable string
+An opt-in integration suite (`__tests__/integration/`) runs against a real MinIO server and is skipped unless `MINIO_TEST_URL` is set:
 
-### Device Interface
-
-All storage devices implement the same interface:
-
-- `upload(source, path, chunk?, chunks?, metadata?)` - Upload file
-- `uploadData(data, path, contentType, chunk?, chunks?, metadata?)` - Upload data
-- `read(path, offset?, length?)` - Read file content
-- `write(path, data, contentType)` - Write file
-- `delete(path, recursive?)` - Delete file/directory
-- `exists(path)` - Check if file exists
-- `getFileSize(path)` - Get file size
-- `getFileMimeType(path)` - Get file MIME type
-- `getFileHash(path)` - Get file MD5 hash
-- `transfer(source, destination, targetDevice)` - Transfer file
-
-## 🌍 Browser Support
+```bash
+# 1. Start MinIO and create the test bucket
+docker run -d --name storage-test-minio -p 9000:9000 -p 9001:9001 \
+  -e MINIO_ROOT_USER=minioadmin -e MINIO_ROOT_PASSWORD=minioadmin-test \
+  minio/minio server /data --console-address ":9001"
+docker exec storage-test-minio mc alias set local http://localhost:9000 minioadmin minioadmin-test
+docker exec storage-test-minio mc mb --ignore-existing local/nuvix-storage-test
 
-This library is designed for Node.js environments. For browser usage, you'll need to provide polyfills for Node.js modules or use a bundler that can handle Node.js dependencies.
+# 2. Run the integration tests
+MINIO_TEST_URL=http://localhost:9000 bun run test:integration
+```
 
-## 🤝 Contributing
+These cover real S3 protocol behavior the offline suite can't: chunked upload assembly, abort cleanup, presigned GET/PUT round-trips, and cross-device transfers.
 
-Contributions are welcome! Please read our contributing guidelines and ensure all tests pass:
+## Contributing
 
-```bash
-bun run lint        # Check code style
-bun run lint:fix    # Fix code style issues
-bun test           # Run test suite
-```
+Contributions are welcome! Please ensure `bun test`, `bun run lint`, and `bun run typecheck` all pass before opening a PR.
 
-## 📄 License
+## License
 
 MIT © [Nuvix](https://github.com/nuvix-tech/storage)
 
-## 🔗 Links
+## Links
 
 - [GitHub Repository](https://github.com/nuvix-tech/storage)
 - [NPM Package](https://www.npmjs.com/package/@nuvix/storage)
-- [Documentation](https://github.com/nuvix-tech/storage#readme)
 - [Issue Tracker](https://github.com/nuvix-tech/storage/issues)