@umituz/react-native-storage 2.0.0 → 2.3.3

package/src/domain/entities/__tests__/StorageResult.test.ts

@@ -0,0 +1,122 @@
+/**
+ * StorageResult Entity Tests
+ *
+ * Unit tests for StorageResult entity
+ */
+
+import { success, failure, unwrap, map, isSuccess, isFailure } from '../../domain/entities/StorageResult';
+import { StorageError } from '../../domain/errors/StorageError';
+
+describe('StorageResult Entity', () => {
+  describe('success', () => {
+    it('should create a successful result', () => {
+      const data = { test: 'value' };
+      const result = success(data);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe(data);
+      expect(result.error).toBeUndefined();
+    });
+  });
+
+  describe('failure', () => {
+    it('should create a failure result', () => {
+      const error = new StorageError('test-key', new Error('Test error'));
+      const defaultValue = 'default';
+      const result = failure(error, defaultValue);
+
+      expect(result.success).toBe(false);
+      expect(result.data).toBe(defaultValue);
+      expect(result.error).toBe(error);
+    });
+  });
+
+  describe('unwrap', () => {
+    it('should return data for successful result', () => {
+      const data = { test: 'value' };
+      const result = success(data);
+      const defaultValue = 'default';
+
+      const unwrapped = unwrap(result, defaultValue);
+
+      expect(unwrapped).toBe(data);
+    });
+
+    it('should return default value for failure result', () => {
+      const error = new StorageError('test-key', new Error('Test error'));
+      const defaultValue = 'default';
+      const result = failure(error, defaultValue);
+
+      const unwrapped = unwrap(result, defaultValue);
+
+      expect(unwrapped).toBe(defaultValue);
+    });
+  });
+
+  describe('map', () => {
+    it('should map successful result', () => {
+      const data = { count: 1 };
+      const result = success(data);
+      const mapper = (value: typeof data) => ({ ...value, count: value.count + 1 });
+
+      const mapped = map(result, mapper);
+
+      expect(mapped.success).toBe(true);
+      expect(mapped.data).toEqual({ count: 2 });
+    });
+
+    it('should not map failure result', () => {
+      const error = new StorageError('test-key', new Error('Test error'));
+      const defaultValue = { count: 0 };
+      const result = failure(error, defaultValue);
+      const mapper = jest.fn();
+
+      const mapped = map(result, mapper);
+
+      expect(mapped.success).toBe(false);
+      expect(mapper).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('isSuccess', () => {
+    it('should return true for successful result', () => {
+      const result = success('test');
+      expect(isSuccess(result)).toBe(true);
+    });
+
+    it('should return false for failure result', () => {
+      const error = new StorageError('test-key', new Error('Test error'));
+      const result = failure(error);
+      expect(isSuccess(result)).toBe(false);
+    });
+  });
+
+  describe('isFailure', () => {
+    it('should return false for successful result', () => {
+      const result = success('test');
+      expect(isFailure(result)).toBe(false);
+    });
+
+    it('should return true for failure result', () => {
+      const error = new StorageError('test-key', new Error('Test error'));
+      const result = failure(error);
+      expect(isFailure(result)).toBe(true);
+    });
+  });
+
+  describe('Type Safety', () => {
+    it('should maintain type information', () => {
+      interface TestData {
+        id: number;
+        name: string;
+      }
+
+      const data: TestData = { id: 1, name: 'test' };
+      const result = success<TestData>(data);
+
+      // TypeScript should infer the type correctly
+      const typedData: TestData = result.data;
+      expect(typedData).toEqual(data);
+    });
+  });
+});

package/src/domain/errors/StorageError.ts

@@ -3,8 +3,6 @@
  *
  * Domain-Driven Design: Domain errors for storage operations
  * Typed errors for better error handling and debugging
- *
- * Theme: {{THEME_NAME}} ({{CATEGORY}} category)
  */
 
 /**

package/src/domain/errors/__tests__/StorageError.test.ts

@@ -0,0 +1,127 @@
+/**
+ * StorageError Tests
+ *
+ * Unit tests for StorageError classes
+ */
+
+import {
+  StorageError,
+  StorageReadError,
+  StorageWriteError,
+  StorageDeleteError,
+  StorageSerializationError,
+  StorageDeserializationError,
+} from '../../domain/errors/StorageError';
+
+describe('StorageError Classes', () => {
+  describe('StorageError', () => {
+    it('should create base storage error', () => {
+      const key = 'test-key';
+      const cause = new Error('Original error');
+      const error = new StorageError(key, cause);
+
+      expect(error.key).toBe(key);
+      expect(error.cause).toBe(cause);
+      expect(error.name).toBe('StorageError');
+      expect(error.message).toContain(key);
+    });
+
+    it('should serialize error details', () => {
+      const key = 'test-key';
+      const cause = new Error('Original error');
+      const error = new StorageError(key, cause);
+
+      const serialized = JSON.stringify(error);
+      const parsed = JSON.parse(serialized);
+
+      expect(parsed.key).toBe(key);
+      expect(parsed.message).toContain(key);
+    });
+  });
+
+  describe('StorageReadError', () => {
+    it('should create read error', () => {
+      const key = 'test-key';
+      const cause = new Error('Read failed');
+      const error = new StorageReadError(key, cause);
+
+      expect(error.key).toBe(key);
+      expect(error.cause).toBe(cause);
+      expect(error.name).toBe('StorageReadError');
+      expect(error.message).toContain('read');
+    });
+  });
+
+  describe('StorageWriteError', () => {
+    it('should create write error', () => {
+      const key = 'test-key';
+      const cause = new Error('Write failed');
+      const error = new StorageWriteError(key, cause);
+
+      expect(error.key).toBe(key);
+      expect(error.cause).toBe(cause);
+      expect(error.name).toBe('StorageWriteError');
+      expect(error.message).toContain('write');
+    });
+  });
+
+  describe('StorageDeleteError', () => {
+    it('should create delete error', () => {
+      const key = 'test-key';
+      const cause = new Error('Delete failed');
+      const error = new StorageDeleteError(key, cause);
+
+      expect(error.key).toBe(key);
+      expect(error.cause).toBe(cause);
+      expect(error.name).toBe('StorageDeleteError');
+      expect(error.message).toContain('delete');
+    });
+  });
+
+  describe('StorageSerializationError', () => {
+    it('should create serialization error', () => {
+      const key = 'test-key';
+      const cause = new Error('Serialization failed');
+      const error = new StorageSerializationError(key, cause);
+
+      expect(error.key).toBe(key);
+      expect(error.cause).toBe(cause);
+      expect(error.name).toBe('StorageSerializationError');
+      expect(error.message).toContain('serialize');
+    });
+  });
+
+  describe('StorageDeserializationError', () => {
+    it('should create deserialization error', () => {
+      const key = 'test-key';
+      const cause = new Error('Deserialization failed');
+      const error = new StorageDeserializationError(key, cause);
+
+      expect(error.key).toBe(key);
+      expect(error.cause).toBe(cause);
+      expect(error.name).toBe('StorageDeserializationError');
+      expect(error.message).toContain('deserialize');
+    });
+  });
+
+  describe('Error Inheritance', () => {
+    it('should maintain error chain', () => {
+      const key = 'test-key';
+      const cause = new Error('Original error');
+      const error = new StorageReadError(key, cause);
+
+      expect(error instanceof Error).toBe(true);
+      expect(error instanceof StorageError).toBe(true);
+      expect(error instanceof StorageReadError).toBe(true);
+    });
+
+    it('should preserve stack trace', () => {
+      const key = 'test-key';
+      const cause = new Error('Original error');
+      const error = new StorageReadError(key, cause);
+
+      expect(error.stack).toBeDefined();
+      expect(error.stack).toContain('StorageReadError');
+    });
+  });
+});

package/src/domain/utils/__tests__/devUtils.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Development Utilities Tests
+ */
+
+import { isDev, devWarn, devError, devLog } from '../devUtils';
+
+// Mock console methods
+const mockConsoleWarn = jest.fn();
+const mockConsoleError = jest.fn();
+const mockConsoleLog = jest.fn();
+
+describe('Development Utilities', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    
+    // Mock console methods
+    console.warn = mockConsoleWarn;
+    console.error = mockConsoleError;
+    console.log = mockConsoleLog;
+  });
+
+  describe('isDev', () => {
+    it('should return true when __DEV__ is true', () => {
+      (globalThis as any).__DEV__ = true;
+      expect(isDev()).toBe(true);
+    });
+
+    it('should return false when __DEV__ is false', () => {
+      (globalThis as any).__DEV__ = false;
+      expect(isDev()).toBe(false);
+    });
+
+    it('should return false when __DEV__ is undefined', () => {
+      delete (globalThis as any).__DEV__;
+      expect(isDev()).toBe(false);
+    });
+  });
+
+  describe('devWarn', () => {
+    it('should log warning when in development mode', () => {
+      (globalThis as any).__DEV__ = true;
+      
+      devWarn('Test warning', { data: 'test' });
+      
+      expect(mockConsoleWarn).toHaveBeenCalledWith('Test warning', { data: 'test' });
+    });
+
+    it('should not log warning when not in development mode', () => {
+      (globalThis as any).__DEV__ = false;
+      
+      devWarn('Test warning', { data: 'test' });
+      
+      expect(mockConsoleWarn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('devError', () => {
+    it('should log error when in development mode', () => {
+      (globalThis as any).__DEV__ = true;
+      
+      devError('Test error', new Error('test'));
+      
+      expect(mockConsoleError).toHaveBeenCalledWith('Test error', new Error('test'));
+    });
+
+    it('should not log error when not in development mode', () => {
+      (globalThis as any).__DEV__ = false;
+      
+      devError('Test error', new Error('test'));
+      
+      expect(mockConsoleError).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('devLog', () => {
+    it('should log info when in development mode', () => {
+      (globalThis as any).__DEV__ = true;
+      
+      devLog('Test log', { info: 'test' });
+      
+      expect(mockConsoleLog).toHaveBeenCalledWith('Test log', { info: 'test' });
+    });
+
+    it('should not log info when not in development mode', () => {
+      (globalThis as any).__DEV__ = false;
+      
+      devLog('Test log', { info: 'test' });
+      
+      expect(mockConsoleLog).not.toHaveBeenCalled();
+    });
+  });
+
+  afterEach(() => {
+    // Clean up __DEV__ after each test
+    delete (globalThis as any).__DEV__;
+  });
+});

package/src/domain/utils/devUtils.ts

@@ -0,0 +1,37 @@
+/**
+ * Development utilities
+ */
+
+/**
+ * Check if running in development mode
+ */
+export const isDev = (): boolean => {
+  return (globalThis as any).__DEV__ === true;
+};
+
+/**
+ * Log warning in development mode only
+ */
+export const devWarn = (message: string, ...args: any[]): void => {
+  if (isDev()) {
+    console.warn(message, ...args);
+  }
+};
+
+/**
+ * Log error in development mode only
+ */
+export const devError = (message: string, ...args: any[]): void => {
+  if (isDev()) {
+    console.error(message, ...args);
+  }
+};
+
+/**
+ * Log info in development mode only
+ */
+export const devLog = (message: string, ...args: any[]): void => {
+  if (isDev()) {
+    console.log(message, ...args);
+  }
+};

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

@@ -78,6 +78,12 @@ export {
 
 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
 // =============================================================================
@@ -117,10 +123,12 @@ export {
 export { useStorage } from './presentation/hooks/useStorage';
 export { useStorageState } from './presentation/hooks/useStorageState';
 export { useStore } from './presentation/hooks/useStore';
-export { usePersistedState } from './presentation/hooks/usePersistedState';
 
 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);
     }
   },
 };