@nodezor/storage-adapter-js

Provider-decoupled unified cloud and in-memory storage adapter interface.

The Problem

Cloud storage SDKs (AWS S3, Cloudflare R2, Google Cloud Storage, Cloudinary, Local Disk) feature completely vendor-locked APIs. Switching providers or writing unit tests without cloud connection mocks requires rewriting file uploading, downloading, stream piping, and deletion logic across the entire codebase.

Features

• 🔌 Unified Storage Interface: Single API contract (put, get, getString, delete, exists, list, getPublicUrl).
• 🧪 In-Memory Testing Adapter: Built-in createMemoryStorageAdapter for instant offline testing without cloud mocks.
• ⚡ Zero External Dependencies: Pure TypeScript native implementation.

Installation

# pnpm
pnpm add @nodezor/storage-adapter-js

# npm
npm install @nodezor/storage-adapter-js

# yarn
yarn add @nodezor/storage-adapter-js

Quick Start / Usage Example

import { createMemoryStorageAdapter } from '@nodezor/storage-adapter-js';

// Swappable storage adapter
const storage = createMemoryStorageAdapter('https://cdn.myapp.com');

async function processFile() {
  // Put file
  await storage.put('avatars/user_1.png', 'raw_file_bytes', { mimeType: 'image/png' });

  // Check existence
  if (await storage.exists('avatars/user_1.png')) {
    const url = storage.getPublicUrl('avatars/user_1.png');
    console.log(`Public URL: ${url}`);
  }
}

API Reference

StorageAdapter Interface

interface StorageAdapter {
  readonly provider: StorageProviderType;
  put(key: string, data: string | Uint8Array, options?: StoragePutOptions): Promise<StorageFileMeta>;
  get(key: string): Promise<Uint8Array | undefined>;
  getString(key: string): Promise<string | undefined>;
  delete(key: string): Promise<boolean>;
  exists(key: string): Promise<boolean>;
  list(prefix?: string): Promise<StorageFileMeta[]>;
  getPublicUrl(key: string): string;
}

createMemoryStorageAdapter(baseUrl?: string): StorageAdapter

Initializes an in-memory storage adapter instance.

License

MIT © PRX2112