npm package: @nir.arad/unified-blob-storage
Description: Unified blob storage interface supporting Vercel Blob, Azure Blob Storage, and Azurite
Author: Nir Arad
Latest version: 1.4.1

# @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](./docs/QUICK_START.md)** - Get up and running in minutes
- 📖 **[Implementation Guide](./docs/IMPLEMENTATION_GUIDE.md)** - Comprehensive guide with real-world examples
- 🔧 **[API Reference](./docs/API.md)** - Complete API documentation
- ⚡ **[Advanced Caching](./docs/CACHING_GUIDE.md)** - Cached storage features
- 💡 **[Examples](./docs/EXAMPLES.md)** - Real-world implementation examples
- 📦 **[Private Publishing](./docs/PRIVATE_PUBLISHING.md)** - NPM publishing guide
- 🔄 **[Version Updates](./docs/VERSION_UPDATE_README.md)** - 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](./LICENSE) for details.

## Support

- 📖 [Documentation](./docs/)
- 🐛 [Issues](https://github.com/nirarad/unified-blob-storage/issues)
- 💬 [Discussions](https://github.com/nirarad/unified-blob-storage/discussions)