@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

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

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:

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:

# 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

# 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