@umituz/react-native-storage 1.5.0 → 2.3.2

package/src/domain/value-objects/StorageKey.ts

@@ -3,39 +3,13 @@
  *
  * Domain-Driven Design: Value Object for storage keys
  * Ensures type safety and prevents invalid key usage
- *
- * Theme: {{THEME_NAME}} ({{CATEGORY}} category)
- */
-
-/**
- * Storage Key Type
- * All valid storage keys must be defined here
  */
-export enum StorageKey {
-  // Onboarding
-  ONBOARDING_COMPLETED = '@onboarding_completed',
-
-  // Auth
-  AUTH_SHOW_REGISTER = '@auth_show_register',
-
-  // Localization
-  LANGUAGE = '@app_language',
-
-  // Theme
-  THEME_MODE = '@app_theme_mode',
-
-  // Settings (requires userId suffix)
-  SETTINGS = 'app_settings',
-
-  // Query Cache (requires app name prefix)
-  QUERY_CACHE = '{{APP_NAME}}_query_cache',
-}
 
 /**
  * Storage key with dynamic suffix
  */
 export type DynamicStorageKey = {
-  base: StorageKey;
+  base: string;
   suffix: string;
 };
 
@@ -46,7 +20,7 @@ export type DynamicStorageKey = {
  * @param userId User identifier
  * @returns User-specific key
  */
-export const createUserKey = (baseKey: StorageKey, userId: string): string => {
+export const createUserKey = (baseKey: string, userId: string): string => {
   return `${baseKey}_${userId}`;
 };
 
@@ -57,6 +31,30 @@ export const createUserKey = (baseKey: StorageKey, userId: string): string => {
  * @param appName App identifier
  * @returns App-specific key
  */
-export const createAppKey = (baseKey: StorageKey, appName: string): string => {
+export const createAppKey = (baseKey: string, appName: string): string => {
   return `${appName}_${baseKey}`;
 };
+
+/**
+ * Helper to create namespaced storage key
+ *
+ * @param namespace Key namespace
+ * @param key Specific key
+ * @returns Namespaced key
+ */
+export const createNamespacedKey = (namespace: string, key: string): string => {
+  return `${namespace}:${key}`;
+};
+
+/**
+ * Legacy StorageKey enum for backward compatibility
+ * @deprecated Use createNamespacedKey instead
+ */
+export enum StorageKey {
+  USER_PREFERENCES = '@user_preferences',
+  APP_SETTINGS = '@app_settings',
+  LANGUAGE = '@language',
+  UI_PREFERENCES = '@ui_preferences',
+  QUERY_CACHE = '@query_cache',
+  DATA_CACHE = '@data_cache',
+}

package/src/index.ts

@@ -13,7 +13,7 @@
  * - presentation: Hooks (React integration)
  *
  * Usage:
- *   import { useStorage, useStorageState, StorageKey } from '@umituz/react-native-storage';
+ *   import { useStorage, useStorageState, createStore } from '@umituz/react-native-storage';
  */
 
 // =============================================================================
@@ -48,6 +48,54 @@ export {
   isFailure,
 } from './domain/entities/StorageResult';
 
+// =============================================================================
+// DOMAIN LAYER - Cached Value Entity
+// =============================================================================
+
+export type { CachedValue } from './domain/entities/CachedValue';
+
+export {
+  createCachedValue,
+  isCacheExpired,
+  getRemainingTTL,
+  getCacheAge,
+} from './domain/entities/CachedValue';
+
+// =============================================================================
+// DOMAIN LAYER - Cache Utilities
+// =============================================================================
+
+export {
+  generateCacheKey,
+  generateListCacheKey,
+  parseCacheKey,
+  isCacheKey,
+} from './domain/utils/CacheKeyGenerator';
+
+// =============================================================================
+// DOMAIN LAYER - Cache Constants
+// =============================================================================
+
+export { TIME_MS, DEFAULT_TTL, CACHE_VERSION } from './domain/constants/CacheDefaults';
+
+// =============================================================================
+// DOMAIN LAYER - Development Utilities
+// =============================================================================
+
+export { isDev, devWarn, devError, devLog } from './domain/utils/devUtils';
+
+// =============================================================================
+// DOMAIN LAYER - Store Types
+// =============================================================================
+
+export type { StoreConfig, PersistedState } from './domain/types/Store';
+
+// =============================================================================
+// DOMAIN LAYER - Store Factory
+// =============================================================================
+
+export { createStore } from './domain/factories/StoreFactory';
+
 // =============================================================================
 // APPLICATION LAYER - Ports
 // =============================================================================
@@ -74,3 +122,13 @@ export {
 
 export { useStorage } from './presentation/hooks/useStorage';
 export { useStorageState } from './presentation/hooks/useStorageState';
+export { useStore } from './presentation/hooks/useStore';
+
+export {
+  usePersistentCache,
+  type PersistentCacheOptions,
+  type PersistentCacheResult,
+} from './presentation/hooks/usePersistentCache';
+
+export { useCacheState } from './presentation/hooks/useCacheState';
+export { CacheStorageOperations } from './presentation/hooks/CacheStorageOperations';

package/src/infrastructure/adapters/StorageService.ts

@@ -6,6 +6,7 @@
  */
 
 import AsyncStorage from '@react-native-async-storage/async-storage';
+import { devWarn } from '../../domain/utils/devUtils';
 
 /**
  * StateStorage interface for Zustand persist middleware
@@ -18,13 +19,14 @@ export interface StateStorage {
 
 /**
  * Storage service for Zustand persist middleware
- * Direct AsyncStorage implementation
+ * Direct AsyncStorage implementation with proper error handling
  */
 export const storageService: StateStorage = {
   getItem: async (name: string): Promise<string | null> => {
     try {
       return await AsyncStorage.getItem(name);
-    } catch {
+    } catch (error) {
+      devWarn(`StorageService: Failed to get item "${name}"`, error);
       return null;
     }
   },
@@ -32,16 +34,16 @@ export const storageService: StateStorage = {
   setItem: async (name: string, value: string): Promise<void> => {
     try {
       await AsyncStorage.setItem(name, value);
-    } catch {
-      // Silent fail
+    } catch (error) {
+      devWarn(`StorageService: Failed to set item "${name}"`, error);
     }
   },
 
   removeItem: async (name: string): Promise<void> => {
     try {
       await AsyncStorage.removeItem(name);
-    } catch {
-      // Silent fail
+    } catch (error) {
+      devWarn(`StorageService: Failed to remove item "${name}"`, error);
     }
   },
 };

package/src/infrastructure/repositories/AsyncStorageRepository.ts

@@ -2,178 +2,97 @@
  * AsyncStorage Repository
  *
  * Domain-Driven Design: Infrastructure implementation of IStorageRepository
- * Adapts React Native AsyncStorage to domain interface
+ * Adapts React Native AsyncStorage to domain interface using composition
  */
 
-import AsyncStorage from '@react-native-async-storage/async-storage';
 import type { IStorageRepository } from '../../application/ports/IStorageRepository';
 import type { StorageResult } from '../../domain/entities/StorageResult';
-import { success, failure } from '../../domain/entities/StorageResult';
-import {
-  StorageReadError,
-  StorageWriteError,
-  StorageDeleteError,
-  StorageSerializationError,
-  StorageDeserializationError,
-} from '../../domain/errors/StorageError';
+import { BaseStorageOperations } from './BaseStorageOperations';
+import { StringStorageOperations } from './StringStorageOperations';
+import { BatchStorageOperations } from './BatchStorageOperations';
 
 /**
  * AsyncStorage Repository Implementation
+ * Uses composition to follow Single Responsibility Principle
  */
 export class AsyncStorageRepository implements IStorageRepository {
+  private baseOps: BaseStorageOperations;
+  private stringOps: StringStorageOperations;
+  private batchOps: BatchStorageOperations;
+
+  constructor() {
+    this.baseOps = new BaseStorageOperations();
+    this.stringOps = new StringStorageOperations();
+    this.batchOps = new BatchStorageOperations();
+  }
+
   /**
    * Get item from AsyncStorage with type safety
    */
   async getItem<T>(key: string, defaultValue: T): Promise<StorageResult<T>> {
-    try {
-      const value = await AsyncStorage.getItem(key);
-
-      if (value === null) {
-        // Missing keys on first app launch are NORMAL, not errors
-        return success(defaultValue);
-      }
-
-      try {
-        const parsed = JSON.parse(value) as T;
-        return success(parsed);
-      } catch (parseError) {
-        return failure(new StorageDeserializationError(key, parseError), defaultValue);
-      }
-    } catch (error) {
-      return failure(new StorageReadError(key, error), defaultValue);
-    }
+    return this.baseOps.getItem(key, defaultValue);
   }
 
   /**
    * Set item in AsyncStorage with automatic JSON serialization
    */
   async setItem<T>(key: string, value: T): Promise<StorageResult<T>> {
-    try {
-      let serialized: string;
-      try {
-        serialized = JSON.stringify(value);
-      } catch (serializeError) {
-        return failure(new StorageSerializationError(key, serializeError));
-      }
-
-      await AsyncStorage.setItem(key, serialized);
-      return success(value);
-    } catch (error) {
-      return failure(new StorageWriteError(key, error));
-    }
+    return this.baseOps.setItem(key, value);
   }
 
   /**
    * Get string value (no JSON parsing)
    */
   async getString(key: string, defaultValue: string): Promise<StorageResult<string>> {
-    try {
-      const value = await AsyncStorage.getItem(key);
-
-      if (value === null) {
-        // Missing keys on first app launch are NORMAL, not errors
-        return success(defaultValue);
-      }
-
-      return success(value);
-    } catch (error) {
-      return failure(new StorageReadError(key, error), defaultValue);
-    }
+    return this.stringOps.getString(key, defaultValue);
   }
 
   /**
    * Set string value (no JSON serialization)
    */
   async setString(key: string, value: string): Promise<StorageResult<string>> {
-    try {
-      await AsyncStorage.setItem(key, value);
-      return success(value);
-    } catch (error) {
-      return failure(new StorageWriteError(key, error));
-    }
+    return this.stringOps.setString(key, value);
   }
 
   /**
    * Remove item from AsyncStorage
    */
   async removeItem(key: string): Promise<StorageResult<void>> {
-    try {
-      await AsyncStorage.removeItem(key);
-      return success(undefined);
-    } catch (error) {
-      return failure(new StorageDeleteError(key, error));
-    }
+    return this.baseOps.removeItem(key);
   }
 
   /**
    * Check if key exists in storage
    */
   async hasItem(key: string): Promise<boolean> {
-    try {
-      const value = await AsyncStorage.getItem(key);
-      return value !== null;
-    } catch {
-      return false;
-    }
+    return this.baseOps.hasItem(key);
   }
 
   /**
-   * Clear all AsyncStorage data (use with caution!)
+   * Clear all AsyncStorage data
    */
   async clearAll(): Promise<StorageResult<void>> {
-    try {
-      await AsyncStorage.clear();
-      return success(undefined);
-    } catch (error) {
-      return failure(new StorageDeleteError('ALL_KEYS', error));
-    }
+    return this.baseOps.clearAll();
   }
 
   /**
-   * Get multiple items at once (more efficient than multiple getItem calls)
+   * Get multiple items at once
    */
   async getMultiple(
     keys: string[]
   ): Promise<StorageResult<Record<string, string | null>>> {
-    try {
-      const pairs = await AsyncStorage.multiGet(keys);
-      const result = Object.fromEntries(pairs);
-      return success(result);
-    } catch (error) {
-      return failure(new StorageReadError('MULTIPLE_KEYS', error));
-    }
+    return this.batchOps.getMultiple(keys);
   }
 
   /**
    * Get all keys from storage
    */
   async getAllKeys(): Promise<StorageResult<string[]>> {
-    try {
-      const keys = await AsyncStorage.getAllKeys();
-      return success([...keys]);
-    } catch (error) {
-      return failure(new StorageReadError('ALL_KEYS', error));
-    }
-  }
-
-  /**
-   * Get object from storage (alias for getItem for backward compatibility)
-   * @deprecated Use getItem instead
-   */
-  async getObject<T>(key: string, defaultValue: T): Promise<StorageResult<T>> {
-    return this.getItem(key, defaultValue);
-  }
-
-  /**
-   * Set object in storage (alias for setItem for backward compatibility)
-   * @deprecated Use setItem instead
-   */
-  async setObject<T>(key: string, value: T): Promise<StorageResult<T>> {
-    return this.setItem(key, value);
+    return this.batchOps.getAllKeys();
   }
 }
 
 /**
  * Singleton instance
  */
-export const storageRepository = new AsyncStorageRepository();
+export const storageRepository = new AsyncStorageRepository();

package/src/infrastructure/repositories/BaseStorageOperations.ts

@@ -0,0 +1,101 @@
+/**
+ * Base Storage Operations
+ *
+ * Core storage operations following Single Responsibility Principle
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { IStorageRepository } from '../../application/ports/IStorageRepository';
+import type { StorageResult } from '../../domain/entities/StorageResult';
+import { success, failure } from '../../domain/entities/StorageResult';
+import {
+  StorageReadError,
+  StorageWriteError,
+  StorageDeleteError,
+  StorageSerializationError,
+  StorageDeserializationError,
+} from '../../domain/errors/StorageError';
+import { devWarn } from '../../domain/utils/devUtils';
+
+/**
+ * Base storage operations implementation
+ */
+export class BaseStorageOperations {
+  /**
+   * Get item from AsyncStorage with type safety
+   */
+  async getItem<T>(key: string, defaultValue: T): Promise<StorageResult<T>> {
+    try {
+      const value = await AsyncStorage.getItem(key);
+
+      if (value === null) {
+        return success(defaultValue);
+      }
+
+      try {
+        const parsed = JSON.parse(value) as T;
+        return success(parsed);
+      } catch (parseError) {
+        return failure(new StorageDeserializationError(key, parseError), defaultValue);
+      }
+    } catch (error) {
+      return failure(new StorageReadError(key, error), defaultValue);
+    }
+  }
+
+  /**
+   * Set item in AsyncStorage with automatic JSON serialization
+   */
+  async setItem<T>(key: string, value: T): Promise<StorageResult<T>> {
+    try {
+      let serialized: string;
+      try {
+        serialized = JSON.stringify(value);
+      } catch (serializeError) {
+        return failure(new StorageSerializationError(key, serializeError));
+      }
+
+      await AsyncStorage.setItem(key, serialized);
+      return success(value);
+    } catch (error) {
+      return failure(new StorageWriteError(key, error));
+    }
+  }
+
+  /**
+   * Remove item from AsyncStorage
+   */
+  async removeItem(key: string): Promise<StorageResult<void>> {
+    try {
+      await AsyncStorage.removeItem(key);
+      return success(undefined);
+    } catch (error) {
+      return failure(new StorageDeleteError(key, error));
+    }
+  }
+
+  /**
+   * Check if key exists in storage
+   */
+  async hasItem(key: string): Promise<boolean> {
+    try {
+      const value = await AsyncStorage.getItem(key);
+      return value !== null;
+    } catch (error) {
+      devWarn(`BaseStorageOperations: Failed to check if key "${key}" exists`, error);
+      return false;
+    }
+  }
+
+  /**
+   * Clear all AsyncStorage data
+   */
+  async clearAll(): Promise<StorageResult<void>> {
+    try {
+      await AsyncStorage.clear();
+      return success(undefined);
+    } catch (error) {
+      return failure(new StorageDeleteError('ALL_KEYS', error));
+    }
+  }
+}

package/src/infrastructure/repositories/BatchStorageOperations.ts

@@ -0,0 +1,42 @@
+/**
+ * Batch Storage Operations
+ *
+ * Batch operations following Single Responsibility Principle
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { StorageResult } from '../../domain/entities/StorageResult';
+import { success, failure } from '../../domain/entities/StorageResult';
+import { StorageReadError } from '../../domain/errors/StorageError';
+
+/**
+ * Batch storage operations for efficiency
+ */
+export class BatchStorageOperations {
+  /**
+   * Get multiple items at once
+   */
+  async getMultiple(
+    keys: string[]
+  ): Promise<StorageResult<Record<string, string | null>>> {
+    try {
+      const pairs = await AsyncStorage.multiGet(keys);
+      const result = Object.fromEntries(pairs);
+      return success(result);
+    } catch (error) {
+      return failure(new StorageReadError('MULTIPLE_KEYS', error));
+    }
+  }
+
+  /**
+   * Get all keys from storage
+   */
+  async getAllKeys(): Promise<StorageResult<string[]>> {
+    try {
+      const keys = await AsyncStorage.getAllKeys();
+      return success([...keys]);
+    } catch (error) {
+      return failure(new StorageReadError('ALL_KEYS', error));
+    }
+  }
+}

package/src/infrastructure/repositories/StringStorageOperations.ts

@@ -0,0 +1,44 @@
+/**
+ * String Storage Operations
+ *
+ * Specialized string operations following Single Responsibility Principle
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { StorageResult } from '../../domain/entities/StorageResult';
+import { success, failure } from '../../domain/entities/StorageResult';
+import { StorageReadError, StorageWriteError } from '../../domain/errors/StorageError';
+
+/**
+ * String-specific storage operations
+ */
+export class StringStorageOperations {
+  /**
+   * Get string value (no JSON parsing)
+   */
+  async getString(key: string, defaultValue: string): Promise<StorageResult<string>> {
+    try {
+      const value = await AsyncStorage.getItem(key);
+
+      if (value === null) {
+        return success(defaultValue);
+      }
+
+      return success(value);
+    } catch (error) {
+      return failure(new StorageReadError(key, error), defaultValue);
+    }
+  }
+
+  /**
+   * Set string value (no JSON serialization)
+   */
+  async setString(key: string, value: string): Promise<StorageResult<string>> {
+    try {
+      await AsyncStorage.setItem(key, value);
+      return success(value);
+    } catch (error) {
+      return failure(new StorageWriteError(key, error));
+    }
+  }
+}