@umituz/react-native-storage 1.0.0

package/src/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Storage Domain - Public API
+ *
+ * Domain-Driven Design (DDD) Architecture
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all storage operations.
+ * ALL imports from the storage domain MUST go through this file.
+ *
+ * Architecture:
+ * - domain: Entities, value objects, errors (business logic)
+ * - application: Ports (interfaces), use cases (not needed for simple CRUD)
+ * - infrastructure: Repository implementation (AsyncStorage adapter)
+ * - presentation: Hooks (React integration)
+ *
+ * Usage:
+ *   import { useStorage, useStorageState, StorageKey } from '@umituz/react-native-storage';
+ */
+
+// =============================================================================
+// DOMAIN LAYER - Business Logic
+// =============================================================================
+
+export {
+  StorageKey,
+  createUserKey,
+  createAppKey,
+} from './domain/value-objects/StorageKey';
+
+export type { DynamicStorageKey } from './domain/value-objects/StorageKey';
+
+export {
+  StorageError,
+  StorageReadError,
+  StorageWriteError,
+  StorageDeleteError,
+  StorageSerializationError,
+  StorageDeserializationError,
+} from './domain/errors/StorageError';
+
+export type { StorageResult } from './domain/entities/StorageResult';
+
+export {
+  success,
+  failure,
+  unwrap,
+  map,
+} from './domain/entities/StorageResult';
+
+// =============================================================================
+// APPLICATION LAYER - Ports
+// =============================================================================
+
+export type { IStorageRepository } from './application/ports/IStorageRepository';
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Implementation
+// =============================================================================
+
+export {
+  AsyncStorageRepository,
+  storageRepository,
+} from './infrastructure/repositories/AsyncStorageRepository';
+
+// =============================================================================
+// PRESENTATION LAYER - Hooks
+// =============================================================================
+
+export { useStorage } from './presentation/hooks/useStorage';
+export { useStorageState } from './presentation/hooks/useStorageState';

package/src/infrastructure/repositories/AsyncStorageRepository.ts

@@ -0,0 +1,151 @@
+/**
+ * AsyncStorage Repository
+ *
+ * Domain-Driven Design: Infrastructure implementation of IStorageRepository
+ * Adapts React Native AsyncStorage to domain interface
+ */
+
+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';
+
+/**
+ * AsyncStorage Repository Implementation
+ */
+export class AsyncStorageRepository implements IStorageRepository {
+  /**
+   * 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);
+    }
+  }
+
+  /**
+   * 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));
+    }
+  }
+
+  /**
+   * 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);
+    }
+  }
+
+  /**
+   * 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));
+    }
+  }
+
+  /**
+   * 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 {
+      return false;
+    }
+  }
+
+  /**
+   * Clear all AsyncStorage data (use with caution!)
+   */
+  async clearAll(): Promise<StorageResult<void>> {
+    try {
+      await AsyncStorage.clear();
+      return success(undefined);
+    } catch (error) {
+      return failure(new StorageDeleteError('ALL_KEYS', error));
+    }
+  }
+
+  /**
+   * Get multiple items at once (more efficient than multiple getItem calls)
+   */
+  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));
+    }
+  }
+}
+
+/**
+ * Singleton instance
+ */
+export const storageRepository = new AsyncStorageRepository();

package/src/presentation/hooks/useStorage.ts

@@ -0,0 +1,101 @@
+/**
+ * useStorage Hook
+ *
+ * Domain-Driven Design: Presentation layer hook for storage operations
+ * Provides clean API for components to interact with storage domain
+ */
+
+import { useCallback } from 'react';
+import { storageRepository } from '../../infrastructure/repositories/AsyncStorageRepository';
+import type { StorageResult } from '../../domain/entities/StorageResult';
+import { unwrap } from '../../domain/entities/StorageResult';
+import type { StorageKey } from '../../domain/value-objects/StorageKey';
+
+/**
+ * Storage Hook
+ * Provides type-safe storage operations
+ */
+export const useStorage = () => {
+  /**
+   * Get item from storage
+   */
+  const getItem = useCallback(async <T>(key: string | StorageKey, defaultValue: T): Promise<T> => {
+    const keyString = typeof key === 'string' ? key : String(key);
+    const result = await storageRepository.getItem(keyString, defaultValue);
+    return unwrap(result, defaultValue);
+  }, []);
+
+  /**
+   * Set item in storage
+   */
+  const setItem = useCallback(async <T>(key: string | StorageKey, value: T): Promise<boolean> => {
+    const keyString = typeof key === 'string' ? key : String(key);
+    const result = await storageRepository.setItem(keyString, value);
+    return result.success;
+  }, []);
+
+  /**
+   * Get string from storage
+   */
+  const getString = useCallback(async (key: string | StorageKey, defaultValue: string): Promise<string> => {
+    const keyString = typeof key === 'string' ? key : String(key);
+    const result = await storageRepository.getString(keyString, defaultValue);
+    return unwrap(result, defaultValue);
+  }, []);
+
+  /**
+   * Set string in storage
+   */
+  const setString = useCallback(async (key: string | StorageKey, value: string): Promise<boolean> => {
+    const keyString = typeof key === 'string' ? key : String(key);
+    const result = await storageRepository.setString(keyString, value);
+    return result.success;
+  }, []);
+
+  /**
+   * Remove item from storage
+   */
+  const removeItem = useCallback(async (key: string | StorageKey): Promise<boolean> => {
+    const keyString = typeof key === 'string' ? key : String(key);
+    const result = await storageRepository.removeItem(keyString);
+    return result.success;
+  }, []);
+
+  /**
+   * Check if item exists
+   */
+  const hasItem = useCallback(async (key: string | StorageKey): Promise<boolean> => {
+    const keyString = typeof key === 'string' ? key : String(key);
+    return storageRepository.hasItem(keyString);
+  }, []);
+
+  /**
+   * Clear all storage
+   */
+  const clearAll = useCallback(async (): Promise<boolean> => {
+    const result = await storageRepository.clearAll();
+    return result.success;
+  }, []);
+
+  /**
+   * Get item with full result (success/error)
+   */
+  const getItemWithResult = useCallback(async <T>(
+    key: string | StorageKey,
+    defaultValue: T
+  ): Promise<StorageResult<T>> => {
+    const keyString = typeof key === 'string' ? key : String(key);
+    return storageRepository.getItem(keyString, defaultValue);
+  }, []);
+
+  return {
+    getItem,
+    setItem,
+    getString,
+    setString,
+    removeItem,
+    hasItem,
+    clearAll,
+    getItemWithResult,
+  };
+};

package/src/presentation/hooks/useStorageState.ts

@@ -0,0 +1,55 @@
+/**
+ * useStorageState Hook
+ *
+ * Domain-Driven Design: Presentation layer hook for state + storage sync
+ * Combines React state with automatic storage persistence
+ *
+ * Theme: {{THEME_NAME}} ({{CATEGORY}} category)
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { storageRepository } from '../../infrastructure/repositories/AsyncStorageRepository';
+import { unwrap } from '../../domain/entities/StorageResult';
+import type { StorageKey } from '../../domain/value-objects/StorageKey';
+
+/**
+ * Storage State Hook
+ * Syncs React state with AsyncStorage automatically
+ *
+ * @example
+ * ```typescript
+ * const [theme, setTheme] = useStorageState(StorageKey.THEME_MODE, 'light');
+ * // State is automatically persisted to storage
+ * ```
+ */
+export const useStorageState = <T>(
+  key: string | StorageKey,
+  defaultValue: T
+): [T, (value: T) => Promise<void>, boolean] => {
+  const keyString = typeof key === 'string' ? key : String(key);
+  const [state, setState] = useState<T>(defaultValue);
+  const [isLoading, setIsLoading] = useState(true);
+
+  // Load initial value from storage
+  useEffect(() => {
+    const loadFromStorage = async () => {
+      const result = await storageRepository.getItem(keyString, defaultValue);
+      const value = unwrap(result, defaultValue);
+      setState(value);
+      setIsLoading(false);
+    };
+
+    loadFromStorage();
+  }, [keyString, defaultValue]);
+
+  // Update state and persist to storage
+  const updateState = useCallback(
+    async (value: T) => {
+      setState(value);
+      await storageRepository.setItem(keyString, value);
+    },
+    [keyString]
+  );
+
+  return [state, updateState, isLoading];
+};