# @isa/core/storage

A powerful, type-safe storage library for Angular applications built on top of NgRx Signals. This library provides seamless integration between NgRx Signal Stores and various storage backends including localStorage, sessionStorage, IndexedDB, and server-side user state.

## Features

- 🔄 **Auto-sync with NgRx Signals**: Seamlessly integrates with NgRx Signal Stores
- 🏪 **Multiple Storage Providers**: Support for localStorage, sessionStorage, IndexedDB, memory, and server-side storage
- 🚀 **Auto-save with Debouncing**: Automatically persist state changes with configurable debouncing
- 👤 **User-scoped Storage**: Automatic user-specific storage keys using OAuth identity claims
- 🔒 **Type-safe**: Full TypeScript support with Zod schema validation
- 🎛️ **Configurable**: Flexible configuration options for different use cases
- 🧩 **Extensible**: Easy to add custom storage providers

## Installation

This library is part of the ISA Frontend monorepo and is already available as `@isa/core/storage`.

## Quick Start

```typescript
import { signalStore, withState } from '@ngrx/signals';
import { withStorage, LocalStorageProvider } from '@isa/core/storage';

// Create a store with automatic localStorage persistence
const UserPreferencesStore = signalStore(
  withState({ theme: 'dark', language: 'en' }),
  withStorage('user-preferences', LocalStorageProvider)
);

// The store will automatically:
// 1. Load saved state on initialization
// 2. Provide manual save/load methods
// 3. Auto-save state changes (if enabled)
```

## Storage Providers

### LocalStorageProvider
Persists data to the browser's localStorage (survives browser restarts).

```typescript
import { LocalStorageProvider } from '@isa/core/storage';

const store = signalStore(
  withState({ count: 0 }),
  withStorage('counter', LocalStorageProvider)
);
```

### SessionStorageProvider
Persists data to sessionStorage (cleared when tab closes).

```typescript
import { SessionStorageProvider } from '@isa/core/storage';

const store = signalStore(
  withState({ tempData: null }),
  withStorage('session-data', SessionStorageProvider)
);
```

### IDBStorageProvider
Uses IndexedDB for larger data storage with better performance.

```typescript
import { IDBStorageProvider } from '@isa/core/storage';

const store = signalStore(
  withState({ largeDataSet: [] }),
  withStorage('large-data', IDBStorageProvider)
);
```

### UserStorageProvider
Server-side storage tied to the authenticated user's account.

```typescript
import { UserStorageProvider } from '@isa/core/storage';

const store = signalStore(
  withState({ userSettings: {} }),
  withStorage('user-settings', UserStorageProvider)
);
```

### MemoryStorageProvider
In-memory storage for testing or temporary data.

```typescript
import { MemoryStorageProvider } from '@isa/core/storage';

const store = signalStore(
  withState({ testData: null }),
  withStorage('test-data', MemoryStorageProvider)
);
```

## Configuration Options

The `withStorage` function accepts an optional configuration object:

```typescript
interface WithStorageConfig {
  autosave?: boolean;     // Enable automatic state persistence (default: false)
  debounceTime?: number;  // Debounce time in milliseconds (default: 300)
  autoload?: boolean;     // Enable automatic state loading on initialization (default: true)
}
```

### Manual Save/Load with Auto-load (Default Behavior)

```typescript
const store = signalStore(
  withState({ data: 'initial' }),
  withStorage('my-data', LocalStorageProvider)
  // Default: autoload = true, autosave = false
);

// State is automatically loaded on initialization
// Manual save/load operations available
store.saveToStorage();    // Save current state
store.loadFromStorage();  // Manually reload state
```

### Disable Auto-load for Full Manual Control

```typescript
const store = signalStore(
  withState({ data: 'initial' }),
  withStorage('my-data', LocalStorageProvider, {
    autoload: false  // Disable automatic loading
  })
);

// Manual operations only
store.saveToStorage();    // Save current state
store.loadFromStorage();  // Load and restore state
```

### Auto-save with Auto-load

```typescript
const store = signalStore(
  withState({ count: 0 }),
  withStorage('counter', LocalStorageProvider, {
    autosave: true
    // autoload: true (default) - state loaded on initialization
    // Will auto-save with 300ms debounce
  })
);
```

### Auto-save with Custom Debouncing

```typescript
const store = signalStore(
  withState({ settings: {} }),
  withStorage('settings', LocalStorageProvider, {
    autosave: true,
    autoload: true,     // Load saved settings on initialization (default)
    debounceTime: 1000  // Save 1 second after last change
  })
);
```

## Real-World Examples

### Tab Management with Auto-save

```typescript
// From libs/core/tabs/src/lib/tab.ts
export const TabService = signalStore(
  { providedIn: 'root' },
  withDevtools('TabService'),
  withStorage('tabs', UserStorageProvider), // Server-side user storage
  withState<{ activatedTabId: number | null }>({
    activatedTabId: null,
  }),
  withEntities<Tab>(),
  // ... other features
);
```

### Shopping Cart with Auto-persistence

```typescript
const ShoppingCartStore = signalStore(
  withState<{ items: CartItem[], total: number }>({
    items: [],
    total: 0
  }),
  withStorage('shopping-cart', LocalStorageProvider, {
    autosave: true,
    debounceTime: 500  // Save 500ms after changes stop
  }),
  withMethods((store) => ({
    addItem(item: CartItem) {
      const items = [...store.items(), item];
      const total = items.reduce((sum, item) => sum + item.price, 0);
      patchState(store, { items, total });
      // State automatically saved after 500ms
    },
    removeItem(id: string) {
      const items = store.items().filter(item => item.id !== id);
      const total = items.reduce((sum, item) => sum + item.price, 0);
      patchState(store, { items, total });
      // State automatically saved after 500ms
    }
  }))
);
```

### User Preferences with Manual Control

```typescript
const UserPreferencesStore = signalStore(
  withState({
    theme: 'light' as 'light' | 'dark',
    language: 'en',
    notifications: true
  }),
  withStorage('user-preferences', LocalStorageProvider),
  withMethods((store) => ({
    updateTheme(theme: 'light' | 'dark') {
      patchState(store, { theme });
      store.saveToStorage(); // Manual save
    },
    resetToDefaults() {
      patchState(store, {
        theme: 'light',
        language: 'en',
        notifications: true
      });
      store.saveToStorage(); // Manual save
    }
  }))
);
```

## Advanced Usage

### User-scoped Storage Keys

The library automatically creates user-specific storage keys when using any storage provider:

```typescript
// Internal key generation (user sub: "user123", key: "settings")
// Results in: "user123:a1b2c3" (where a1b2c3 is a hash of "settings")
```

This ensures that different users' data never conflicts, even on shared devices.

### Schema Validation with Zod

The underlying `Storage` class supports optional Zod schema validation:

```typescript
import { z } from 'zod';
import { injectStorage, LocalStorageProvider } from '@isa/core/storage';

const UserSchema = z.object({
  name: z.string(),
  age: z.number()
});

// In a service or component
const storage = injectStorage(LocalStorageProvider);

// Type-safe get with validation
const userData = storage.get('user', UserSchema);
// userData is properly typed as z.infer<typeof UserSchema>
```

### Custom Storage Provider

Create your own storage provider by implementing the `StorageProvider` interface:

```typescript
import { Injectable } from '@angular/core';
import { StorageProvider } from '@isa/core/storage';

@Injectable({ providedIn: 'root' })
export class CustomStorageProvider implements StorageProvider {
  async init?(): Promise<void> {
    // Optional initialization logic
  }

  async reload?(): Promise<void> {
    // Optional reload logic
  }

  set(key: string, value: unknown): void {
    // Your storage implementation
    console.log(`Saving ${key}:`, value);
  }

  get(key: string): unknown {
    // Your retrieval implementation
    console.log(`Loading ${key}`);
    return null;
  }

  clear(key: string): void {
    // Your clear implementation
    console.log(`Clearing ${key}`);
  }
}
```

## API Reference

### `withStorage(storageKey, storageProvider, config?)`

NgRx Signals store feature that adds storage capabilities.

**Parameters:**
- `storageKey: string` - Unique key for storing data
- `storageProvider: Type<StorageProvider>` - Storage provider class
- `config?: WithStorageConfig` - Optional configuration

**Returns:**
- `SignalStoreFeature` with added methods:
  - `saveToStorage()` - Manually save current state
  - `loadFromStorage()` - Manually load and apply stored state

### `injectStorage(storageProvider)`

Injectable function to get a storage instance.

**Parameters:**
- `storageProvider: Type<StorageProvider>` - Storage provider class

**Returns:**
- `Storage` instance with methods:
  - `set<T>(key, value)` - Store value
  - `get<T>(key, schema?)` - Retrieve value with optional validation
  - `clear(key)` - Remove value

### Storage Providers

All storage providers implement the `StorageProvider` interface:

```typescript
interface StorageProvider {
  init?(): Promise<void>;           // Optional initialization
  reload?(): Promise<void>;         // Optional reload
  set(key: string, value: unknown): void;      // Store value
  get(key: string): unknown;                   // Retrieve value
  clear(key: string): void;                    // Remove value
}
```

**Available Providers:**
- `LocalStorageProvider` - Browser localStorage
- `SessionStorageProvider` - Browser sessionStorage
- `IDBStorageProvider` - IndexedDB
- `UserStorageProvider` - Server-side user storage
- `MemoryStorageProvider` - In-memory storage

## Best Practices

### 1. Choose the Right Storage Provider

- **LocalStorageProvider**: User preferences, settings that should persist across sessions
- **SessionStorageProvider**: Temporary data that should be cleared when tab closes
- **IDBStorageProvider**: Large datasets, complex objects, better performance needs
- **UserStorageProvider**: Cross-device synchronization, server-backed user data
- **MemoryStorageProvider**: Testing, temporary data during app lifecycle

### 2. Configure Auto-save and Auto-load Wisely

```typescript
// For frequent changes (like form inputs)
withStorage('form-draft', LocalStorageProvider, {
  autosave: true,
  autoload: true,     // Restore draft on page reload
  debounceTime: 1000  // Longer debounce
})

// For infrequent changes (like settings)
withStorage('user-settings', LocalStorageProvider, {
  autosave: true,
  autoload: true,     // Load saved settings immediately
  debounceTime: 100   // Shorter debounce
})

// For critical data that needs manual control
withStorage('important-data', LocalStorageProvider, {
  autoload: false     // Disable automatic loading
})
// Use manual saveToStorage() and loadFromStorage() for precise control
```

### 3. Handle Storage Errors

Storage operations can fail (quota exceeded, network issues, etc.). The library handles errors gracefully:

- Failed saves are logged to console but don't throw
- Failed loads return undefined/null
- State continues to work in memory even if storage fails

### 4. Consider Storage Size Limits

- **localStorage/sessionStorage**: ~5-10MB per domain
- **IndexedDB**: Much larger, varies by browser and device
- **UserStorageProvider**: Depends on server configuration

### 5. Test with Different Storage Providers

Use `MemoryStorageProvider` in tests for predictable, isolated behavior:

```typescript
// In tests
const testStore = signalStore(
  withState({ data: 'test' }),
  withStorage('test-key', MemoryStorageProvider)
);
```

## Architecture Notes

The library consists of several key components:

1. **Storage Class**: Core storage abstraction with user-scoping
2. **StorageProvider Interface**: Pluggable storage backends
3. **withStorage Feature**: NgRx Signals integration
4. **Hash Utilities**: Efficient key generation
5. **User Token**: OAuth-based user identification

The architecture promotes:
- **Separation of Concerns**: Storage logic separate from business logic
- **Type Safety**: Full TypeScript support throughout
- **Extensibility**: Easy to add new storage providers
- **User Privacy**: Automatic user-scoping prevents data leaks
- **Performance**: Debounced saves prevent excessive writes

## Migration Guide

### From Manual localStorage

```typescript
// Before
localStorage.setItem('settings', JSON.stringify(settings));
const settings = JSON.parse(localStorage.getItem('settings') || '{}');

// After
const SettingsStore = signalStore(
  withState(defaultSettings),
  withStorage('settings', LocalStorageProvider, { autosave: true })
);
```

### From Custom Storage Services

```typescript
// Before
@Injectable()
class SettingsService {
  private settings = signal(defaultSettings);

  save() {
    localStorage.setItem('settings', JSON.stringify(this.settings()));
  }

  load() {
    const data = localStorage.getItem('settings');
    if (data) this.settings.set(JSON.parse(data));
  }
}

// After
const SettingsStore = signalStore(
  withState(defaultSettings),
  withStorage('settings', LocalStorageProvider, { autosave: true })
);
```

## Troubleshooting

### Common Issues

1. **Storage not persisting**: Check if storage provider supports your environment
2. **Data not loading**: Verify storage key consistency
3. **Performance issues**: Adjust debounce time or switch storage providers
4. **User data conflicts**: Ensure USER_SUB token is properly configured

### Debug Mode

The storage feature uses the centralized `@isa/core/logging` system. All storage operations are logged with appropriate context including the storage key, autosave settings, and operation details.

To see debug logs, configure the logging system at the application level:

```typescript
// The storage feature automatically logs:
// - Debug: Successful operations, state loading/saving
// - Warn: Validation failures, data type issues
// - Error: Storage failures, fallback application errors

const store = signalStore(
  withState({ data: null }),
  withStorage('my-data', LocalStorageProvider)
);
// All operations will be logged with context: { module: 'storage', storageKey: 'my-data', ... }
```

## Testing

Run unit tests with:

```bash
nx test core-storage
```

## License

This library is part of the ISA Frontend project and follows the project's licensing terms.