@nir.arad/unified-blob-storage

A unified interface for blob storage supporting Vercel Blob, Azure Blob Storage, Azurite, and Google Drive. This package provides a consistent API across different blob storage providers, making it easy to switch between providers or use different providers in different environments.

Features

- 🚀 Unified API - Single interface for all supported storage providers
- 🔄 Provider Flexibility - Switch between Vercel Blob, Azure Blob Storage, Azurite, and Google Drive
- 🏗️ Environment-Based Configuration - Automatic provider selection based on environment variables
- ⚡ Advanced Caching - Hybrid caching with memory and filesystem strategies
- 🎯 Smart Cache Selection - Automatic cache strategy based on file type and size
- 🔧 Manual Cache Refresh - Admin-triggered cache updates for static sites
- 📊 Cache Statistics - Comprehensive performance monitoring and metrics
- 📦 TypeScript Support - Full TypeScript definitions included
- 🧪 Comprehensive Testing - 100% test coverage with Jest
- 📚 Well Documented - Complete API documentation and examples
- 🔧 Zero Dependencies - Minimal external dependencies

Supported Providers

| Provider | Use Case | Environment |
|----------|----------|-------------|
| Vercel Blob | Production deployments on Vercel | vercel |
| Azure Blob Storage | Enterprise production environments | azure |
| Azurite | Local development and testing | azurite |
| Google Drive | Read-only access to Google Drive files | google-drive |

Quick Start

``bash
npm install @nir.arad/unified-blob-storage
`

`typescript
import { UnifiedBlobStorage } from '@nir.arad/unified-blob-storage';

const storage = new UnifiedBlobStorage();

// Fetch files
const content = await storage.fetchFileContent('data/config.json');
const jsonData = await storage.fetchJsonFile('data/galleries/art.json');

// Upload files
await storage.saveFileContent('data/new-file.json', JSON.stringify(data));

// Delete files
await storage.deleteFile('images/category/photo.jpg');
`

Documentation

- 🚀 Quick Start Guide - Get up and running in minutes
- 📖 Implementation Guide - Comprehensive guide with real-world examples
- 🔧 API Reference - Complete API documentation
- ⚡ Advanced Caching - Cached storage features
- 💡 Examples - Real-world implementation examples
- 📦 Private Publishing - NPM publishing guide
- 🔄 Version Updates - Automated version management

Advanced Caching

For high-performance applications, use the cached storage with automatic strategy selection:

`typescript
import { CachedUnifiedBlobStorage } from '@nir.arad/unified-blob-storage';

const cachedStorage = new CachedUnifiedBlobStorage({
cacheStrategy: 'filesystem', // Default for large files
maxCacheSize: 500 1024 1024, // 500MB
cacheDir: './cache'
});

await cachedStorage.initialize();

// Files are automatically cached based on type and size
const jsonData = await cachedStorage.fetchJsonFile('data/galleries/art.json'); // → Memory cache
const imageContent = await cachedStorage.fetchFileContent('images/photo.jpg'); // → Filesystem cache

// Manual cache refresh for static sites
await cachedStorage.refreshAllMetadata();
`

Environment Configuration

The package automatically detects the storage provider based on environment variables:

`bash


For Vercel Blob

BLOB_PROVIDER=vercel
BLOB_BASE_URL=https://your-blob-url.vercel-storage.com

For Azure Blob Storage

BLOB_PROVIDER=azure
AZURE_STORAGE_CONNECTION_STRING=your-connection-string
AZURE_CONTAINER_NAME=your-container

For Azurite (local development)

BLOB_PROVIDER=azurite
AZURITE_CONNECTION_STRING=DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=your-account-key;BlobEndpoint=your-blob-endpoint;

For Google Drive (read-only)

BLOB_PROVIDER=google-drive
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

OR

GOOGLE_DRIVE_CREDENTIALS='{"type":"service_account",...}'
GOOGLE_DRIVE_FOLDER_ID=optional-root-folder-id
`

Development

`bash


Install dependencies

npm install

Run tests

npm test

Build package

npm run build

Build in watch mode

npm run dev
``

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE for details.

Support

- 📖 Documentation
- 🐛 Issues
- 💬 Discussions