@gune/storage-core

Core abstractions and utilities for the universal storage system.

Installation

npm install @gune/storage-core

Features

• 🎯 Type-Safe: Full TypeScript support with strict generics
• 🔄 Retry Logic: Built-in exponential backoff
• 📊 Progress Tracking: Real-time upload progress events
• 🎪 Event Emitters: Listen to upload/delete events
• 🛠️ Utilities: File key generation, MIME detection, stream helpers

Usage

Basic Upload

import { StorageFactory } from '@gune/storage-core';
import { S3StorageStrategy } from '@gune/storage-s3';
import * as fs from 'fs';

const storage = StorageFactory.create(
  new S3StorageStrategy({
    region: 'us-east-1',
    bucket: 'my-bucket',
    credentials: { ... },
  }),
);

const result = await storage.uploadFile({
  stream: fs.createReadStream('./photo.jpg'),
  filename: 'photo.jpg',
  contentType: 'image/jpeg',
});

console.log(result.url); // https://my-bucket.s3.amazonaws.com/...

Progress Tracking

await storage.uploadFile(
  { stream, filename, contentType },
  {
    onProgress: (progress) => {
      console.log(`${progress.percentage}% complete`);
    },
  },
);

Multiple Strategies

import { LocalStorageStrategy } from '@gune/storage-local';

// Register multiple strategies
StorageFactory.register('s3', s3Strategy);
StorageFactory.register('local', localStrategy);
StorageFactory.setDefault('s3');

// Use specific strategy
const s3Storage = new StorageInstance('s3');
const localStorage = new StorageInstance('local');

Custom Retry Configuration

const storage = new S3StorageStrategy({
  region: 'us-east-1',
  bucket: 'my-bucket',
  credentials: { ... },
  retry: {
    maxAttempts: 5,
    initialDelay: 2000,
    maxDelay: 30000,
    backoffMultiplier: 2,
  },
});

API Reference

StorageFactory

Singleton factory for managing storage strategies.

Methods

• register(name: string, strategy: StorageStrategy) - Register a strategy
• get(name?: string) - Get a registered strategy
• setDefault(name: string) - Set the default strategy
• create(strategy: StorageStrategy) - Create and register in one call
• list() - List all registered strategy names
• unregister(name: string) - Remove a strategy
• clear() - Remove all strategies

StorageInstance

Wrapper for executing storage operations.

Methods

• uploadFile(file: FilePayload, options?: UploadOptions) - Upload a single file
• uploadMultiple(files: FilePayload[], options?) - Upload multiple files
• deleteFile(key: string, options?: DeleteOptions) - Delete a file
• deleteMultiple(keys: string[], options?) - Delete multiple files
• getSignedUrl(key: string, options?: SignedUrlOptions) - Generate signed URL
• listFiles(options?: ListOptions) - List files in storage
• fileExists(key: string) - Check if file exists
• getMetadata(key: string) - Get file metadata

BaseStorageStrategy

Abstract base class for creating custom strategies.

import { BaseStorageStrategy, BaseStorageConfig } from '@gune/storage-core';

export class MyStrategy extends BaseStorageStrategy<MyConfig> {
  readonly name = 'my-strategy';

  protected async executeUpload(
    file: FilePayload,
    key: string,
    options?: UploadOptions,
  ): Promise<UploadResponse> {
    // Your upload logic
  }

  protected async executeDelete(
    key: string,
    options?: DeleteOptions,
  ): Promise<void> {
    // Your delete logic
  }
}

Types

FilePayload

interface FilePayload {
  stream: Readable;
  filename: string;
  contentType: string;
  size?: number;
}

UploadResponse

interface UploadResponse {
  key: string;
  url: string;
  provider: string;
  size: number;
  contentType: string;
  uploadedAt: Date;
  metadata?: Record<string, unknown>;
}

UploadOptions

interface UploadOptions {
  folder?: string;
  metadata?: FileMetadata;
  onProgress?: (progress: UploadProgress) => void;
  signal?: AbortSignal;
}

Utilities

import {
  generateFileKey,
  sanitizeFilename,
  extractKeyFromUrl,
  detectMimeType,
  formatBytes,
} from '@gune/storage-core';

const key = generateFileKey('photo.jpg', 'uploads');
// => "uploads/01HN123ABC-photo.jpg"

const sanitized = sanitizeFilename('my file (1).jpg');
// => "my_file_1.jpg"

const key = extractKeyFromUrl('https://bucket.s3.amazonaws.com/path/file.jpg');
// => "path/file.jpg"

Error Handling

import {
  UploadError,
  DeleteError,
  FileNotFoundError,
  ConfigurationError,
} from '@gune/storage-core';

try {
  await storage.uploadFile(file);
} catch (error) {
  if (error instanceof UploadError) {
    console.error('Upload failed:', error.key, error.context);
  }
}

License

MIT