npm package: @gune/storage-core
Description: Core abstractions for universal storage system
Author: BUDDGUN92
Latest version: 0.1.0

# @gune/storage-core

Core abstractions and utilities for the universal storage system.

## Installation

```bash
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

```typescript
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

```typescript
await storage.uploadFile(
  { stream, filename, contentType },
  {
    onProgress: (progress) => {
      console.log(`${progress.percentage}% complete`);
    },
  },
);
```

### Multiple Strategies

```typescript
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

```typescript
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.

```typescript
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`

```typescript
interface FilePayload {
  stream: Readable;
  filename: string;
  contentType: string;
  size?: number;
}
```

### `UploadResponse`

```typescript
interface UploadResponse {
  key: string;
  url: string;
  provider: string;
  size: number;
  contentType: string;
  uploadedAt: Date;
  metadata?: Record<string, unknown>;
}
```

### `UploadOptions`

```typescript
interface UploadOptions {
  folder?: string;
  metadata?: FileMetadata;
  onProgress?: (progress: UploadProgress) => void;
  signal?: AbortSignal;
}
```

## Utilities

```typescript
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

```typescript
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