S3-compatible storage library for Nuvix BaaS platform with support for AWS S3, Wasabi, MinIO, and local storage
npm install @nuvix/storageA 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.
- ๐ 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
``bashUsing npm
npm install @nuvix/storage
๐ Quick Start
$3
`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");
`$3
`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
$3
`typescript
import { Local, Storage } from "@nuvix/storage";const localStorage = new Local("./uploads");
Storage.setDevice("local", localStorage);
// 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");
`$3
`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" },
);
`$3
`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);
`$3
`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");
// Check if file exists
const exists = await minioStorage.exists("local-file.txt");
// Get file information
const size = await minioStorage.getFileSize("local-file.txt");
const mimeType = await minioStorage.getFileMimeType("local-file.txt");
`๐ก๏ธ File Validation
$3
`typescript
import { FileExt } from "@nuvix/storage";const imageValidator = new FileExt(["jpg", "png", "gif", "webp"]);
console.log(imageValidator.isValid("photo.jpg")); // true
console.log(imageValidator.isValid("document.pdf")); // false
`$3
`typescript
import { FileSize } 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)
`$3
`typescript
import { FileName } from "@nuvix/storage";const nameValidator = new FileName();
console.log(nameValidator.isValid("validfile123.txt")); // true
console.log(nameValidator.isValid("invalid-file.txt")); // false (contains hyphen)
`$3
`typescript
import { FileType } from "@nuvix/storage";const typeValidator = new FileType(["jpeg", "png", "gif"]);
// Validates based on file content, not extension
console.log(await typeValidator.isValid("./image.jpg")); // true if actual JPEG
`$3
`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
`๐ Advanced Features
$3
`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,
);
}
`$3
`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);
`$3
`typescript
import { Storage } from "@nuvix/storage";console.log(Storage.human(1024)); // "1.00kB"
console.log(Storage.human(1048576)); // "1.00MB"
console.log(Storage.human(1024, 2, "binary")); // "1.00KiB"
`๐๏ธ Building
The library is built using Rollup and provides both ESM and CommonJS outputs:
`bash
Build for production
bun run buildBuild and watch for changes
bun run build:watchClean build directory
bun run clean
`๐งช Testing
Comprehensive test suite with real implementation testing:
`bash
Run all tests
bun testRun tests in watch mode
bun run test:watchRun tests with coverage
bun run test:coverageRun specific test files
bun test storage.test.ts
bun test device/
bun test validator/
`$3
Set environment variables to test against real storage services:
`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"
`๐ API Reference
$3
-
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$3
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
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.
๐ค Contributing
Contributions are welcome! Please read our contributing guidelines and ensure all tests pass:
`bash
bun run lint # Check code style
bun run lint:fix # Fix code style issues
bun test # Run test suite
``MIT ยฉ Nuvix
- GitHub Repository
- NPM Package
- Documentation
- Issue Tracker