@umituz/react-native-storage 1.4.0 → 2.0.0

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@umituz/react-native-storage",
-  "version": "1.4.0",
-  "description": "Domain-Driven Design storage system for React Native apps with type-safe AsyncStorage operations",
+  "version": "2.0.0",
+  "description": "Zustand state management with AsyncStorage persistence and type-safe storage operations for React Native",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit",
-    "version:patch": "npm version patch -m 'chore: release v%s'",
-    "version:minor": "npm version minor -m 'chore: release v%s'",
-    "version:major": "npm version major -m 'chore: release v%s'"
+    "lint": "tsc --noEmit"
   },
   "keywords": [
     "react-native",
     "storage",
     "async-storage",
+    "zustand",
+    "state-management",
+    "persist",
     "ddd",
     "domain-driven-design",
     "type-safe"
@@ -27,6 +27,7 @@
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "^1.21.0",
+    "zustand": "^5.0.0",
     "react": ">=18.2.0",
     "react-native": ">=0.74.0"
   },
@@ -36,7 +37,8 @@
     "@types/react-native": "^0.73.0",
     "react": "^18.2.0",
     "react-native": "^0.74.0",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "zustand": "^5.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/domain/constants/CacheDefaults.ts

@@ -0,0 +1,64 @@
+/**
+ * Cache Default Constants
+ * Domain layer - Default values for caching
+ *
+ * General-purpose constants for any app
+ */
+
+/**
+ * Time constants in milliseconds
+ */
+export const TIME_MS = {
+  SECOND: 1000,
+  MINUTE: 60 * 1000,
+  HOUR: 60 * 60 * 1000,
+  DAY: 24 * 60 * 60 * 1000,
+  WEEK: 7 * 24 * 60 * 60 * 1000,
+} as const;
+
+/**
+ * Default TTL values for different cache types
+ */
+export const DEFAULT_TTL = {
+  /**
+   * Very short cache (1 minute)
+   * Use for: Real-time data, live updates
+   */
+  VERY_SHORT: TIME_MS.MINUTE,
+
+  /**
+   * Short cache (5 minutes)
+   * Use for: Frequently changing data
+   */
+  SHORT: 5 * TIME_MS.MINUTE,
+
+  /**
+   * Medium cache (30 minutes)
+   * Use for: Moderately changing data, user-specific content
+   */
+  MEDIUM: 30 * TIME_MS.MINUTE,
+
+  /**
+   * Long cache (2 hours)
+   * Use for: Slowly changing data, public content
+   */
+  LONG: 2 * TIME_MS.HOUR,
+
+  /**
+   * Very long cache (24 hours)
+   * Use for: Rarely changing data, master data
+   */
+  VERY_LONG: TIME_MS.DAY,
+
+  /**
+   * Permanent cache (7 days)
+   * Use for: Static content, app configuration
+   */
+  PERMANENT: TIME_MS.WEEK,
+} as const;
+
+/**
+ * Cache version for global invalidation
+ * Increment this to invalidate all caches across the app
+ */
+export const CACHE_VERSION = 1;

package/src/domain/entities/CachedValue.ts

@@ -0,0 +1,86 @@
+/**
+ * Cached Value Entity
+ * Domain layer - Represents a cached value with TTL metadata
+ *
+ * General-purpose cache entity for any app that needs persistent caching
+ */
+
+/**
+ * Cached value with time-to-live metadata
+ * Generic type T can be any serializable data
+ */
+export interface CachedValue<T> {
+  /**
+   * The actual cached data
+   */
+  value: T;
+
+  /**
+   * Timestamp when the value was cached (milliseconds)
+   */
+  cachedAt: number;
+
+  /**
+   * Timestamp when the cache expires (milliseconds)
+   */
+  expiresAt: number;
+
+  /**
+   * Optional version for cache invalidation
+   * Increment version to invalidate all caches
+   */
+  version?: number;
+}
+
+/**
+ * Create a new cached value with TTL
+ * @param value - Data to cache
+ * @param ttlMs - Time-to-live in milliseconds
+ * @param version - Optional version number
+ */
+export function createCachedValue<T>(
+  value: T,
+  ttlMs: number,
+  version?: number,
+): CachedValue<T> {
+  const now = Date.now();
+  return {
+    value,
+    cachedAt: now,
+    expiresAt: now + ttlMs,
+    version,
+  };
+}
+
+/**
+ * Check if cached value is expired
+ * @param cached - Cached value to check
+ * @param currentVersion - Optional current version to check against
+ */
+export function isCacheExpired<T>(
+  cached: CachedValue<T>,
+  currentVersion?: number,
+): boolean {
+  const now = Date.now();
+  const timeExpired = now > cached.expiresAt;
+  const versionMismatch = currentVersion !== undefined && cached.version !== currentVersion;
+  return timeExpired || versionMismatch;
+}
+
+/**
+ * Get remaining TTL in milliseconds
+ * Returns 0 if expired
+ */
+export function getRemainingTTL<T>(cached: CachedValue<T>): number {
+  const now = Date.now();
+  const remaining = cached.expiresAt - now;
+  return Math.max(0, remaining);
+}
+
+/**
+ * Get cache age in milliseconds
+ */
+export function getCacheAge<T>(cached: CachedValue<T>): number {
+  const now = Date.now();
+  return now - cached.cachedAt;
+}

package/src/domain/entities/StorageResult.ts

@@ -34,16 +34,28 @@ export const failure = <T>(error: StorageError, fallback?: T): StorageResult<T>
   fallback,
 });
 
+/**
+ * Type guard for success result
+ */
+export const isSuccess = <T>(result: StorageResult<T>): result is { success: true; data: T } => {
+  return result.success === true;
+};
+
+/**
+ * Type guard for failure result
+ */
+export const isFailure = <T>(result: StorageResult<T>): result is { success: false; error: StorageError; fallback?: T } => {
+  return result.success === false;
+};
+
 /**
  * Unwrap result with default value
  */
 export const unwrap = <T>(result: StorageResult<T>, defaultValue: T): T => {
-  if (result.success) {
+  if (isSuccess(result)) {
     return result.data;
   }
-  // result is now narrowed to failure type
-  const failedResult = result;
-  return failedResult.fallback !== undefined ? failedResult.fallback : defaultValue;
+  return result.fallback !== undefined ? result.fallback : defaultValue;
 };
 
 /**
@@ -53,10 +65,8 @@ export const map = <T, U>(
   result: StorageResult<T>,
   fn: (data: T) => U
 ): StorageResult<U> => {
-  if (result.success) {
+  if (isSuccess(result)) {
     return success(fn(result.data));
   }
-  // result is now narrowed to failure type
-  const failedResult = result;
-  return failure(failedResult.error, failedResult.fallback !== undefined ? fn(failedResult.fallback) : undefined);
+  return failure(result.error, result.fallback !== undefined ? fn(result.fallback) : undefined);
 };

package/src/domain/factories/StoreFactory.ts

@@ -0,0 +1,33 @@
+/**
+ * Store Factory
+ * Create Zustand stores with AsyncStorage persistence
+ */
+
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import type { StoreConfig } from '../types/Store';
+import { storageService } from '../../infrastructure/adapters/StorageService';
+
+export function createStore<T extends object>(config: StoreConfig<T>) {
+  if (!config.persist) {
+    return create<T>(() => config.initialState);
+  }
+
+  return create<T>()(
+    persist(
+      () => config.initialState,
+      {
+        name: config.name,
+        storage: createJSONStorage(() => storageService),
+        version: config.version || 1,
+        partialize: config.partialize,
+        onRehydrateStorage: () => (state) => {
+          if (state && config.onRehydrate) {
+            config.onRehydrate(state);
+          }
+        },
+        migrate: config.migrate as any,
+      }
+    )
+  );
+}

package/src/domain/types/Store.ts

@@ -0,0 +1,18 @@
+/**
+ * Store Types
+ */
+
+export interface StoreConfig<T> {
+  name: string;
+  initialState: T;
+  persist?: boolean;
+  version?: number;
+  partialize?: (state: T) => Partial<T>;
+  onRehydrate?: (state: T) => void;
+  migrate?: (persistedState: unknown, version: number) => T;
+}
+
+export interface PersistedState<T> {
+  state: T;
+  version: number;
+}

package/src/domain/utils/CacheKeyGenerator.ts

@@ -0,0 +1,66 @@
+/**
+ * Cache Key Generator
+ * Domain layer - Utility for generating consistent cache keys
+ *
+ * General-purpose key generation for any app
+ */
+
+/**
+ * Generate a cache key from prefix and identifier
+ * @param prefix - Cache key prefix (e.g., 'posts', 'products', 'user')
+ * @param id - Unique identifier
+ * @returns Formatted cache key
+ *
+ * @example
+ * generateCacheKey('posts', '123') // 'cache:posts:123'
+ * generateCacheKey('user', 'profile') // 'cache:user:profile'
+ */
+export function generateCacheKey(prefix: string, id: string | number): string {
+  return `cache:${prefix}:${id}`;
+}
+
+/**
+ * Generate a cache key for a list/collection
+ * @param prefix - Cache key prefix
+ * @param params - Optional query parameters
+ *
+ * @example
+ * generateListCacheKey('posts') // 'cache:posts:list'
+ * generateListCacheKey('posts', { page: 1 }) // 'cache:posts:list:page=1'
+ */
+export function generateListCacheKey(
+  prefix: string,
+  params?: Record<string, string | number>,
+): string {
+  const base = `cache:${prefix}:list`;
+  if (!params) return base;
+
+  const paramString = Object.entries(params)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `${key}=${value}`)
+    .join(':');
+
+  return `${base}:${paramString}`;
+}
+
+/**
+ * Parse a cache key to extract prefix and id
+ * @param key - Cache key to parse
+ * @returns Object with prefix and id, or null if invalid
+ */
+export function parseCacheKey(key: string): { prefix: string; id: string } | null {
+  const parts = key.split(':');
+  if (parts.length < 3 || parts[0] !== 'cache') return null;
+
+  return {
+    prefix: parts[1],
+    id: parts.slice(2).join(':'),
+  };
+}
+
+/**
+ * Check if a key is a cache key
+ */
+export function isCacheKey(key: string): boolean {
+  return key.startsWith('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';
  */
 
 // =============================================================================
@@ -44,8 +44,52 @@ export {
   failure,
   unwrap,
   map,
+  isSuccess,
+  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 - Store Types
+// =============================================================================
+
+export type { StoreConfig, PersistedState } from './domain/types/Store';
+
+// =============================================================================
+// DOMAIN LAYER - Store Factory
+// =============================================================================
+
+export { createStore } from './domain/factories/StoreFactory';
+
 // =============================================================================
 // APPLICATION LAYER - Ports
 // =============================================================================
@@ -72,3 +116,11 @@ 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';

package/src/presentation/hooks/usePersistedState.ts

@@ -0,0 +1,34 @@
+/**
+ * usePersistedState Hook
+ * Like useState but persisted to AsyncStorage
+ */
+
+import { useEffect, useState, useCallback } from 'react';
+import { storageRepository } from '../../infrastructure/repositories/AsyncStorageRepository';
+
+export function usePersistedState<T>(
+  key: string,
+  initialValue: T
+): [T, (value: T) => void, boolean] {
+  const [state, setState] = useState<T>(initialValue);
+  const [isLoaded, setIsLoaded] = useState(false);
+
+  useEffect(() => {
+    storageRepository.getItem(key, initialValue).then((result) => {
+      if (result.success) {
+        setState(result.data);
+      }
+      setIsLoaded(true);
+    });
+  }, [key]);
+
+  const setPersistedState = useCallback(
+    (value: T) => {
+      setState(value);
+      storageRepository.setItem(key, value);
+    },
+    [key]
+  );
+
+  return [state, setPersistedState, isLoaded];
+}

package/src/presentation/hooks/usePersistentCache.ts

@@ -0,0 +1,163 @@
+/**
+ * usePersistentCache Hook
+ * Presentation layer - Hook for persistent caching with TTL
+ *
+ * General-purpose cache hook for any app
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { storageRepository } from '../../infrastructure/repositories/AsyncStorageRepository';
+import type { CachedValue } from '../../domain/entities/CachedValue';
+import { createCachedValue, isCacheExpired } from '../../domain/entities/CachedValue';
+import { DEFAULT_TTL } from '../../domain/constants/CacheDefaults';
+
+/**
+ * Options for persistent cache
+ */
+export interface PersistentCacheOptions {
+  /**
+   * Time-to-live in milliseconds
+   * @default DEFAULT_TTL.MEDIUM (30 minutes)
+   */
+  ttl?: number;
+
+  /**
+   * Cache version for invalidation
+   * Increment to invalidate existing caches
+   */
+  version?: number;
+
+  /**
+   * Whether cache is enabled
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Result from usePersistentCache hook
+ */
+export interface PersistentCacheResult<T> {
+  /**
+   * Cached data (null if not loaded or expired)
+   */
+  data: T | null;
+
+  /**
+   * Whether data is being loaded from storage
+   */
+  isLoading: boolean;
+
+  /**
+   * Whether cached data is expired
+   */
+  isExpired: boolean;
+
+  /**
+   * Set data to cache
+   */
+  setData: (value: T) => Promise<void>;
+
+  /**
+   * Clear cached data
+   */
+  clearData: () => Promise<void>;
+
+  /**
+   * Refresh cache (reload from storage)
+   */
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Hook for persistent caching with TTL support
+ *
+ * @example
+ * ```typescript
+ * const { data, setData, isExpired } = usePersistentCache<Post[]>('posts-page-1', {
+ *   ttl: TIME_MS.HOUR,
+ *   version: 1,
+ * });
+ *
+ * // Check if need to fetch
+ * if (!data || isExpired) {
+ *   const freshData = await fetchPosts();
+ *   await setData(freshData);
+ * }
+ * ```
+ */
+export function usePersistentCache<T>(
+  key: string,
+  options: PersistentCacheOptions = {},
+): PersistentCacheResult<T> {
+  const { ttl = DEFAULT_TTL.MEDIUM, version, enabled = true } = options;
+
+  const [data, setDataState] = useState<T | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [isExpired, setIsExpired] = useState(false);
+
+  const loadFromStorage = useCallback(async () => {
+    if (!enabled) {
+      setIsLoading(false);
+      return;
+    }
+
+    try {
+      const result = await storageRepository.getString(key, '');
+
+      if (result.success && result.data) {
+        const cached = JSON.parse(result.data) as CachedValue<T>;
+        const expired = isCacheExpired(cached, version);
+
+        setDataState(cached.value);
+        setIsExpired(expired);
+      } else {
+        setDataState(null);
+        setIsExpired(true);
+      }
+    } catch {
+      setDataState(null);
+      setIsExpired(true);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [key, version, enabled]);
+
+  const setData = useCallback(
+    async (value: T) => {
+      if (!enabled) return;
+
+      const cached = createCachedValue(value, ttl, version);
+      await storageRepository.setString(key, JSON.stringify(cached));
+      setDataState(value);
+      setIsExpired(false);
+    },
+    [key, ttl, version, enabled],
+  );
+
+  const clearData = useCallback(async () => {
+    if (!enabled) return;
+
+    await storageRepository.removeItem(key);
+    setDataState(null);
+    setIsExpired(true);
+  }, [key, enabled]);
+
+  const refresh = useCallback(async () => {
+    setIsLoading(true);
+    await loadFromStorage();
+  }, [loadFromStorage]);
+
+  useEffect(() => {
+    loadFromStorage();
+  }, [loadFromStorage]);
+
+  return {
+    data,
+    isLoading,
+    isExpired,
+    setData,
+    clearData,
+    refresh,
+  };
+}

package/src/presentation/hooks/useStore.ts

@@ -0,0 +1,13 @@
+/**
+ * useStore Hook
+ * Helper for creating stores in components
+ */
+
+import { useMemo } from 'react';
+import { createStore } from '../../domain/factories/StoreFactory';
+import type { StoreConfig } from '../../domain/types/Store';
+
+export function useStore<T extends object>(config: StoreConfig<T>) {
+  const store = useMemo(() => createStore(config), [config.name]);
+  return store;
+}