react-achievements 3.3.0 → 3.4.1

package/README.md

@@ -322,6 +322,10 @@ See the [examples directory](./stories/examples) for detailed implementations an
 - Toast notifications
 - Confetti animations
 - TypeScript support
+- **NEW in v3.4.0**: Async storage support (IndexedDB, REST API, Offline Queue)
+- **NEW in v3.4.0**: 50MB+ storage capacity with IndexedDB
+- **NEW in v3.4.0**: Server-side sync with REST API storage
+- **NEW in v3.4.0**: Offline-first capabilities with automatic queue sync
 - **NEW in v3.3.0**: Comprehensive error handling system
 - **NEW in v3.3.0**: Data export/import for achievement portability
 - **NEW in v3.3.0**: Type-safe error classes with recovery guidance
@@ -416,9 +420,185 @@ const achievements = {
 
 The library provides a small set of essential fallback icons for system use (error states, loading, etc.). These are automatically used when needed and don't require any configuration.
 
+## Async Storage (NEW in v3.4.0)
+
+React Achievements now supports async storage backends for modern applications that need large data capacity, server sync, or offline-first capabilities.
+
+### IndexedDB Storage
+
+Browser-native storage with 50MB+ capacity (vs localStorage's 5-10MB limit):
+
+```tsx
+import { AchievementProvider, StorageType } from 'react-achievements';
+
+const App = () => {
+  return (
+    <AchievementProvider
+      achievements={gameAchievements}
+      storage={StorageType.IndexedDB}  // Use IndexedDB for large data
+    >
+      <Game />
+    </AchievementProvider>
+  );
+};
+```
+
+**Benefits:**
+- ✅ 10x larger capacity than localStorage
+- ✅ Structured data storage
+- ✅ Better performance for large datasets
+- ✅ Non-blocking async operations
+
+### REST API Storage
+
+Sync achievements with your backend server:
+
+```tsx
+import { AchievementProvider, StorageType } from 'react-achievements';
+
+const App = () => {
+  return (
+    <AchievementProvider
+      achievements={gameAchievements}
+      storage={StorageType.RestAPI}
+      restApiConfig={{
+        baseUrl: 'https://api.example.com',
+        userId: getCurrentUserId(),
+        headers: {
+          'Authorization': `Bearer ${getAuthToken()}`
+        },
+        timeout: 10000  // Optional, default 10s
+      }}
+    >
+      <Game />
+    </AchievementProvider>
+  );
+};
+```
+
+**API Endpoints Expected:**
+```
+GET    /users/:userId/achievements/metrics
+PUT    /users/:userId/achievements/metrics
+GET    /users/:userId/achievements/unlocked
+PUT    /users/:userId/achievements/unlocked
+DELETE /users/:userId/achievements
+```
+
+**Benefits:**
+- ✅ Cross-device synchronization
+- ✅ Server-side backup
+- ✅ User authentication support
+- ✅ Centralized data management
+
+### Offline Queue Storage
+
+Offline-first storage with automatic sync when back online:
+
+```tsx
+import {
+  AchievementProvider,
+  OfflineQueueStorage,
+  RestApiStorage
+} from 'react-achievements';
+
+// Wrap REST API storage with offline queue
+const restApi = new RestApiStorage({
+  baseUrl: 'https://api.example.com',
+  userId: 'user123',
+  headers: { 'Authorization': 'Bearer token' }
+});
+
+const offlineStorage = new OfflineQueueStorage(restApi);
+
+const App = () => {
+  return (
+    <AchievementProvider
+      achievements={gameAchievements}
+      storage={offlineStorage}
+    >
+      <Game />
+    </AchievementProvider>
+  );
+};
+```
+
+**Benefits:**
+- ✅ Works offline - queues operations locally
+- ✅ Automatic sync when connection restored
+- ✅ Persistent queue survives page refreshes
+- ✅ Graceful degradation for poor connectivity
+
+### Custom Async Storage
+
+You can create custom async storage by implementing the `AsyncAchievementStorage` interface:
+
+```tsx
+import {
+  AsyncAchievementStorage,
+  AchievementMetrics,
+  AsyncStorageAdapter,
+  AchievementProvider
+} from 'react-achievements';
+
+class MyCustomAsyncStorage implements AsyncAchievementStorage {
+  async getMetrics(): Promise<AchievementMetrics> {
+    // Your async implementation (e.g., fetch from database)
+    const response = await fetch('/my-api/metrics');
+    return response.json();
+  }
+
+  async setMetrics(metrics: AchievementMetrics): Promise<void> {
+    await fetch('/my-api/metrics', {
+      method: 'PUT',
+      body: JSON.stringify(metrics)
+    });
+  }
+
+  async getUnlockedAchievements(): Promise<string[]> {
+    const response = await fetch('/my-api/unlocked');
+    return response.json();
+  }
+
+  async setUnlockedAchievements(achievements: string[]): Promise<void> {
+    await fetch('/my-api/unlocked', {
+      method: 'PUT',
+      body: JSON.stringify(achievements)
+    });
+  }
+
+  async clear(): Promise<void> {
+    await fetch('/my-api/clear', { method: 'DELETE' });
+  }
+}
+
+// Wrap with adapter for optimistic updates
+const customStorage = new MyCustomAsyncStorage();
+const adapter = new AsyncStorageAdapter(customStorage, {
+  onError: (error) => console.error('Storage error:', error)
+});
+
+const App = () => {
+  return (
+    <AchievementProvider
+      achievements={gameAchievements}
+      storage={adapter}
+    >
+      <Game />
+    </AchievementProvider>
+  );
+};
+```
+
+**How AsyncStorageAdapter Works:**
+- **Optimistic Updates**: Returns cached data immediately (no waiting)
+- **Eager Loading**: Preloads data during initialization
+- **Background Writes**: All writes happen async without blocking UI
+- **Error Handling**: Optional error callback for failed operations
+
 ## Custom Storage
 
-You can implement your own storage solution by implementing the `AchievementStorage` interface:
+You can implement your own synchronous storage solution by implementing the `AchievementStorage` interface:
 
 ```tsx
 import { AchievementStorage, AchievementMetrics, AchievementProvider } from 'react-achievements';
@@ -946,7 +1126,9 @@ const result = importAchievementData(data, {
   strategy: 'replace',
   achievements
 });
+```
 
+```tsx
 // Merge: Combine imported and existing data
 // - Takes maximum values for metrics
 // - Combines unlocked achievements
@@ -954,6 +1136,9 @@ const result = importAchievementData(data, {
   strategy: 'merge',
   achievements
 });
+```
+
+```tsx
 
 // Preserve: Only import new achievements, keep existing data
 const result = importAchievementData(data, {

package/dist/index.d.ts

@@ -51,6 +51,15 @@ interface AchievementStorage {
     setUnlockedAchievements(achievements: string[]): void;
     clear(): void;
 }
+interface AsyncAchievementStorage {
+    getMetrics(): Promise<AchievementMetrics>;
+    setMetrics(metrics: AchievementMetrics): Promise<void>;
+    getUnlockedAchievements(): Promise<string[]>;
+    setUnlockedAchievements(achievements: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+type AnyAchievementStorage = AchievementStorage | AsyncAchievementStorage;
+declare function isAsyncStorage(storage: AnyAchievementStorage): storage is AsyncAchievementStorage;
 interface AchievementContextValue {
     updateMetrics: (metrics: AchievementMetrics | ((prev: AchievementMetrics) => AchievementMetrics)) => void;
     unlockedAchievements: string[];
@@ -84,8 +93,10 @@ interface AchievementProviderProps$1 {
     onAchievementUnlocked?: (achievement: AchievementDetails) => void;
 }
 declare enum StorageType {
-    Local = "local",
-    Memory = "memory"
+    Local = "local",// Synchronous localStorage
+    Memory = "memory",// Synchronous in-memory storage
+    IndexedDB = "indexeddb",// Asynchronous IndexedDB storage
+    RestAPI = "restapi"
 }
 
 declare class LocalStorage implements AchievementStorage {
@@ -115,6 +126,199 @@ declare class MemoryStorage implements AchievementStorage {
     clear(): void;
 }
 
+/**
+ * Base error class for all achievement-related errors
+ */
+declare class AchievementError extends Error {
+    code: string;
+    recoverable: boolean;
+    remedy?: string | undefined;
+    constructor(message: string, code: string, recoverable: boolean, remedy?: string | undefined);
+}
+/**
+ * Error thrown when browser storage quota is exceeded
+ */
+declare class StorageQuotaError extends AchievementError {
+    bytesNeeded: number;
+    constructor(bytesNeeded: number);
+}
+/**
+ * Error thrown when imported data fails validation
+ */
+declare class ImportValidationError extends AchievementError {
+    validationErrors: string[];
+    constructor(validationErrors: string[]);
+}
+/**
+ * Error thrown when storage operations fail
+ */
+declare class StorageError extends AchievementError {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * Error thrown when configuration is invalid
+ */
+declare class ConfigurationError extends AchievementError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when network sync operations fail
+ */
+declare class SyncError extends AchievementError {
+    readonly statusCode?: number;
+    readonly timeout?: number;
+    constructor(message: string, details?: {
+        statusCode?: number;
+        timeout?: number;
+    });
+}
+/**
+ * Type guard to check if an error is an AchievementError
+ */
+declare function isAchievementError(error: unknown): error is AchievementError;
+/**
+ * Type guard to check if an error is recoverable
+ */
+declare function isRecoverableError(error: unknown): boolean;
+
+declare class AsyncStorageAdapter implements AchievementStorage {
+    private asyncStorage;
+    private cache;
+    private pendingWrites;
+    private onError?;
+    constructor(asyncStorage: AsyncAchievementStorage, options?: {
+        onError?: (error: AchievementError) => void;
+    });
+    /**
+     * Initialize cache by loading from async storage
+     * This happens in the background during construction
+     */
+    private initializeCache;
+    /**
+     * Wait for cache to be loaded (used internally)
+     * Returns immediately if already loaded, otherwise waits
+     */
+    private ensureCacheLoaded;
+    /**
+     * SYNC READ: Returns cached metrics immediately
+     * Cache is loaded eagerly during construction
+     */
+    getMetrics(): AchievementMetrics;
+    /**
+     * SYNC WRITE: Updates cache immediately, writes to storage in background
+     * Uses optimistic updates - assumes write will succeed
+     */
+    setMetrics(metrics: AchievementMetrics): void;
+    /**
+     * SYNC READ: Returns cached unlocked achievements immediately
+     */
+    getUnlockedAchievements(): string[];
+    /**
+     * SYNC WRITE: Updates cache immediately, writes to storage in background
+     */
+    setUnlockedAchievements(achievements: string[]): void;
+    /**
+     * SYNC CLEAR: Clears cache immediately, clears storage in background
+     */
+    clear(): void;
+    /**
+     * Wait for all pending writes to complete (useful for testing/cleanup)
+     * NOT part of AchievementStorage interface - utility method
+     */
+    flush(): Promise<void>;
+}
+
+declare class IndexedDBStorage implements AsyncAchievementStorage {
+    private dbName;
+    private storeName;
+    private db;
+    private initPromise;
+    constructor(dbName?: string);
+    /**
+     * Initialize IndexedDB database and object store
+     */
+    private initDB;
+    /**
+     * Generic get operation from IndexedDB
+     */
+    private get;
+    /**
+     * Generic set operation to IndexedDB
+     */
+    private set;
+    /**
+     * Delete operation from IndexedDB
+     */
+    private delete;
+    getMetrics(): Promise<AchievementMetrics>;
+    setMetrics(metrics: AchievementMetrics): Promise<void>;
+    getUnlockedAchievements(): Promise<string[]>;
+    setUnlockedAchievements(achievements: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
+interface RestApiStorageConfig {
+    baseUrl: string;
+    userId: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+declare class RestApiStorage implements AsyncAchievementStorage {
+    private config;
+    constructor(config: RestApiStorageConfig);
+    /**
+     * Generic fetch wrapper with timeout and error handling
+     */
+    private fetchWithTimeout;
+    getMetrics(): Promise<AchievementMetrics>;
+    setMetrics(metrics: AchievementMetrics): Promise<void>;
+    getUnlockedAchievements(): Promise<string[]>;
+    setUnlockedAchievements(achievements: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
+interface QueuedOperation {
+    id: string;
+    type: 'setMetrics' | 'setUnlockedAchievements' | 'clear';
+    data?: any;
+    timestamp: number;
+}
+declare class OfflineQueueStorage implements AsyncAchievementStorage {
+    private innerStorage;
+    private queue;
+    private isOnline;
+    private isSyncing;
+    private queueStorageKey;
+    constructor(innerStorage: AsyncAchievementStorage);
+    private loadQueue;
+    private saveQueue;
+    private handleOnline;
+    private handleOffline;
+    private processQueue;
+    private queueOperation;
+    getMetrics(): Promise<AchievementMetrics>;
+    setMetrics(metrics: AchievementMetrics): Promise<void>;
+    getUnlockedAchievements(): Promise<string[]>;
+    setUnlockedAchievements(achievements: string[]): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Manually trigger queue processing (useful for testing)
+     */
+    sync(): Promise<void>;
+    /**
+     * Get current queue status (useful for debugging)
+     */
+    getQueueStatus(): {
+        pending: number;
+        operations: QueuedOperation[];
+    };
+    /**
+     * Cleanup listeners (call on unmount)
+     */
+    destroy(): void;
+}
+
 interface BadgesButtonProps {
     onClick: () => void;
     position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
@@ -187,58 +391,6 @@ interface ImportResult {
  */
 declare function importAchievementData(jsonString: string, currentMetrics: AchievementMetrics, currentUnlocked: string[], options?: ImportOptions): ImportResult;
 
-/**
- * Base error class for all achievement-related errors
- */
-declare class AchievementError extends Error {
-    code: string;
-    recoverable: boolean;
-    remedy?: string | undefined;
-    constructor(message: string, code: string, recoverable: boolean, remedy?: string | undefined);
-}
-/**
- * Error thrown when browser storage quota is exceeded
- */
-declare class StorageQuotaError extends AchievementError {
-    bytesNeeded: number;
-    constructor(bytesNeeded: number);
-}
-/**
- * Error thrown when imported data fails validation
- */
-declare class ImportValidationError extends AchievementError {
-    validationErrors: string[];
-    constructor(validationErrors: string[]);
-}
-/**
- * Error thrown when storage operations fail
- */
-declare class StorageError extends AchievementError {
-    originalError?: Error | undefined;
-    constructor(message: string, originalError?: Error | undefined);
-}
-/**
- * Error thrown when configuration is invalid
- */
-declare class ConfigurationError extends AchievementError {
-    constructor(message: string);
-}
-/**
- * Error thrown when sync operations fail (for async storage backends)
- */
-declare class SyncError extends AchievementError {
-    originalError?: Error | undefined;
-    constructor(message: string, originalError?: Error | undefined);
-}
-/**
- * Type guard to check if an error is an AchievementError
- */
-declare function isAchievementError(error: unknown): error is AchievementError;
-/**
- * Type guard to check if an error is recoverable
- */
-declare function isRecoverableError(error: unknown): boolean;
-
 interface AchievementContextType {
     update: (metrics: Record<string, any>) => void;
     achievements: {
@@ -256,10 +408,11 @@ interface AchievementContextType {
 declare const AchievementContext: React$1.Context<AchievementContextType | undefined>;
 interface AchievementProviderProps {
     achievements: AchievementConfigurationType;
-    storage?: AchievementStorage | StorageType;
+    storage?: AchievementStorage | AsyncAchievementStorage | StorageType;
     children: React$1.ReactNode;
     icons?: Record<string, string>;
     onError?: (error: AchievementError) => void;
+    restApiConfig?: RestApiStorageConfig;
 }
 declare const AchievementProvider: React$1.FC<AchievementProviderProps>;
 
@@ -492,7 +645,7 @@ interface ExportedData {
  *
  * @example
  * ```typescript
- * const json = exportAchievementData(metrics, ['score_100', 'level_5']);
+ * const json = exportAchievementData(_metrics, ['score_100', 'level_5']);
  * // Save json to file or send to server
  * ```
  */
@@ -506,4 +659,4 @@ declare function exportAchievementData(metrics: AchievementMetrics, unlocked: st
  */
 declare function createConfigHash(config: any): string;
 
-export { AchievementBuilder, AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextValue, AchievementDetails, AchievementError, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AwardDetails, BadgesButton, BadgesModal, ConfettiWrapper, ConfigurationError, CustomAchievementDetails, ExportedData, ImportOptions, ImportResult, ImportValidationError, InitialAchievementMetrics, LocalStorage, MemoryStorage, SimpleAchievementConfig, SimpleAchievementDetails, StorageError, StorageQuotaError, StorageType, StylesProps, SyncError, createConfigHash, defaultAchievementIcons, defaultStyles, exportAchievementData, importAchievementData, isAchievementError, isRecoverableError, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
+export { AchievementBuilder, AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextValue, AchievementDetails, AchievementError, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AnyAchievementStorage, AsyncAchievementStorage, AsyncStorageAdapter, AwardDetails, BadgesButton, BadgesModal, ConfettiWrapper, ConfigurationError, CustomAchievementDetails, ExportedData, ImportOptions, ImportResult, ImportValidationError, IndexedDBStorage, InitialAchievementMetrics, LocalStorage, MemoryStorage, OfflineQueueStorage, RestApiStorage, RestApiStorageConfig, SimpleAchievementConfig, SimpleAchievementDetails, StorageError, StorageQuotaError, StorageType, StylesProps, SyncError, createConfigHash, defaultAchievementIcons, defaultStyles, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };