@umituz/react-native-design-system 2.8.7 → 2.8.8

package/src/storage/domain/factories/README.md

@@ -0,0 +1,138 @@
+# Domain Factories
+
+Factory functions for creating Zustand stores with persistence.
+
+## Overview
+
+Factory functions for creating Zustand stores with AsyncStorage persistence. Located at `src/domain/factories/`.
+
+## Strategies
+
+### Store Creation
+- Use createStore() factory for all Zustand stores
+- Provide type inference for state and actions
+- Support optional persistence
+- Enable store composition
+
+### Persistence Strategy
+- Use persist middleware for AsyncStorage integration
+- Configure storage adapter (StorageService)
+- Support selective persistence (partialize)
+- Enable versioning and migration
+
+### Store Configuration
+- Require unique store name
+- Define initial state clearly
+- Create actions with set/get helpers
+- Support middleware configuration
+
+### Type Safety
+- Infer state types from initial state
+- Separate state and actions types
+- Enable type-safe selectors
+- Support generic store types
+
+## Restrictions
+
+### Store Creation
+- DO NOT create stores without factory
+- DO NOT duplicate store names
+- DO NOT mix state and actions unnecessarily
+- DO NOT create stores without clear purpose
+
+### Persistence
+- DO NOT enable persist without unique name
+- DO NOT persist sensitive data without encryption
+- DO NOT forget version when schema changes
+- DO NOT omit migration for breaking changes
+
+### Type Safety
+- DO NOT use `any` for state type
+- DO NOT bypass type inference
+- DO NOT cast state to wrong type
+- DO NOT create circular type dependencies
+
+## Rules
+
+### Factory Function
+- MUST provide createStore(config) function
+- MUST accept name parameter (required)
+- MUST accept initialState parameter (required)
+- MUST accept actions parameter (optional)
+- MUST accept persist parameter (optional)
+
+### Store Configuration
+- MUST require unique store name
+- MUST define complete initial state
+- MUST provide type inference
+- MUST validate configuration
+- MUST return configured store
+
+### Persistence Setup
+- MUST use zustand persist middleware
+- MUST use storageService adapter
+- MUST include store name in config
+- MUST support version parameter
+- MUST support partialize function
+
+### Actions Creation
+- MUST provide set helper for updates
+- MUST provide get helper for reads
+- MUST support both object and function updates
+- MUST enable action composition
+- MUST preserve type safety
+
+### Type Inference
+- MUST infer state type from initialState
+- MUST infer actions type from actions return
+- MUST support ReturnType for external use
+- MUST enable Pick for action subsets
+
+### Version Management
+- MUST increment version on schema changes
+- MUST provide migrate function
+- MUST handle old persisted states
+- MUST document breaking changes
+- MUST support multiple version migrations
+
+### Partialize Function
+- MUST accept full state parameter
+- MUST return partial state for persistence
+- MUST exclude transient state
+- MUST include all persistent state
+- MUST enable optimization
+
+### Migration Function
+- MUST accept persistedState parameter
+- MUST accept version parameter
+- MUST return migrated state
+- MUST handle all old versions
+- MUST default to identity for current version
+
+### OnRehydrate Callback
+- MUST accept hydrated state parameter
+- MUST execute after rehydration
+- MUST enable initialization logic
+- MUST not block hydration
+- MUST support async operations
+
+### Error Handling
+- MUST validate store configuration
+- MUST throw descriptive errors for invalid config
+- MUST handle persistence errors gracefully
+- MUST log errors in development
+- MUST provide fallback when possible
+
+### Testing Support
+- MUST enable store reset in tests
+- MUST support mocking persistence
+- MUST provide test utilities
+- MUST clear state between tests
+- MUST not have hidden dependencies
+
+### Documentation
+- MUST document store purpose
+- MUST specify state structure
+- MUST document all actions
+- MUST explain persistence strategy
+- MUST warn about common mistakes

package/src/storage/domain/factories/StoreFactory.ts

@@ -0,0 +1,59 @@
+/**
+ * Store Factory
+ * Create Zustand stores with AsyncStorage persistence and actions
+ */
+
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import type { StoreApi } from 'zustand';
+import type { StoreConfig } from '../types/Store';
+import { storageService } from '../../infrastructure/adapters/StorageService';
+
+/**
+ * Create a Zustand store with optional persistence and actions
+ */
+export function createStore<
+  TState extends object,
+  TActions extends object = object
+>(config: StoreConfig<TState, TActions>) {
+  type Store = TState & TActions;
+  type SetState = StoreApi<Store>['setState'];
+  type GetState = StoreApi<Store>['getState'];
+
+  const stateCreator = (set: SetState, get: GetState): Store => {
+    const state = config.initialState as TState;
+    const actions = config.actions
+      ? config.actions(set, get)
+      : ({} as TActions);
+    return { ...state, ...actions } as Store;
+  };
+
+  if (!config.persist) {
+    return create<Store>(stateCreator);
+  }
+
+  return create<Store>()(
+    persist<Store>(stateCreator, {
+      name: config.name,
+      storage: createJSONStorage(() => storageService),
+      version: config.version || 1,
+      partialize: config.partialize
+        ? (state: Store) => config.partialize!(state as any) as any
+        : (state: Store) => {
+            const persisted: Record<string, unknown> = {};
+            for (const key of Object.keys(state)) {
+              if (typeof state[key as keyof Store] !== 'function') {
+                persisted[key] = state[key as keyof Store];
+              }
+            }
+            return persisted as any;
+          },
+      onRehydrateStorage: () => (state: Store | undefined) => {
+        if (state && config.onRehydrate) {
+          config.onRehydrate(state as any);
+        }
+      },
+      migrate: config.migrate as any,
+    })
+  );
+}

package/src/storage/domain/types/README.md

@@ -0,0 +1,522 @@
+# Domain Types
+
+Storage domain için TypeScript tipleri ve interface'ler.
+
+## Types
+
+```tsx
+import type {
+  StoreConfig,
+  PersistedState,
+  SetState,
+  GetState,
+  ActionsCreator,
+} from '@umituz/react-native-storage';
+
+import type {
+  StoreApi,
+  UseBoundStore,
+} from 'zustand';
+
+import type {
+  StateCreator,
+  StoreMutatorIdentifier,
+} from 'zustand/vanilla';
+```
+
+## Store Types
+
+### StoreConfig
+
+Store konfigürasyonu için tip.
+
+```tsx
+interface StoreConfig<TState, TActions> {
+  name: string;
+  initialState: TState;
+  actions?: ActionsCreator<TState, TActions>;
+  persist?: boolean;
+  version?: number;
+  partialize?: (state: TState & TActions) => Partial<TState>;
+  onRehydrate?: (state: TState & TActions) => void;
+  migrate?: (persistedState: unknown, version: number) => TState & TActions;
+}
+```
+
+### PersistedState
+
+Persist edilmiş state için tip.
+
+```tsx
+interface PersistedState<T> {
+  version: number;
+  state: T;
+}
+```
+
+### SetState
+
+State güncelleme fonksiyonu tipi.
+
+```tsx
+type SetState<T> = (
+  partial: Partial<T> | ((state: T) => Partial<T>),
+  replace?: boolean
+) => void;
+```
+
+### GetState
+
+State okuma fonksiyonu tipi.
+
+```tsx
+type GetState<T> = () => T;
+```
+
+### ActionsCreator
+
+Action oluşturucu fonksiyon tipi.
+
+```tsx
+type ActionsCreator<TState, TActions> = (
+  set: SetState<TState & TActions>,
+  get: GetState<TState & TActions>
+) => TActions;
+```
+
+## Zustand Types
+
+### StoreApi
+
+Zustand store API tipi.
+
+```tsx
+interface StoreApi<T> {
+  getState: () => T;
+  setState: (partial: Partial<T> | ((state: T) => Partial<T>), replace?: boolean) => void;
+  subscribe: (listener: (state: T, prevState: T) => void) => () => void;
+  destroy: () => void;
+}
+```
+
+### UseBoundStore
+
+React hook tipi.
+
+```tsx
+type UseBoundStore<T> = {
+  (): T;
+  <U>(selector: (state: T) => U, equalityFn?: (a: U, b: U) => boolean): U;
+};
+```
+
+### StateCreator
+
+State oluşturucu tipi.
+
+```tsx
+type StateCreator<T, Mis = []> = (
+  set: SetState<T>,
+  get: GetState<T>,
+  api: StoreApi<T>,
+) => T;
+```
+
+## Kullanım Örnekleri
+
+### Basit Store Type
+
+```tsx
+import type { StoreConfig } from '@umituz/react-native-storage';
+
+interface CounterState {
+  count: number;
+}
+
+interface CounterActions {
+  increment: () => void;
+  decrement: () => void;
+  reset: () => void;
+}
+
+type CounterStore = CounterState & CounterActions;
+
+const config: StoreConfig<CounterState, CounterActions> = {
+  name: 'counter',
+  initialState: { count: 0 },
+  actions: (set) => ({
+    increment: () => set((state) => ({ count: state.count + 1 })),
+    decrement: () => set((state) => ({ count: state.count - 1 })),
+    reset: () => set({ count: 0 }),
+  }),
+};
+```
+
+### Generic Store Type
+
+```tsx
+import type { StoreConfig, ActionsCreator } from '@umituz/react-native-storage';
+
+interface ListState<T> {
+  items: T[];
+  loading: boolean;
+}
+
+interface ListActions<T> {
+  setItems: (items: T[]) => void;
+  addItem: (item: T) => void;
+  removeItem: (id: string) => void;
+  loadItems: () => Promise<void>;
+}
+
+function createListStore<T>(config: {
+  name: string;
+  fetcher: () => Promise<T[]>;
+}) {
+  return createStore<ListState<T>, ListActions<T>>({
+    name: config.name,
+    initialState: {
+      items: [],
+      loading: false,
+    },
+    actions: (set, get) => ({
+      setItems: (items) => set({ items }),
+      addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+      removeItem: (id) => set((state) => ({
+        items: state.items.filter((item) => (item as any).id !== id),
+      })),
+      loadItems: async () => {
+        set({ loading: true });
+        const items = await config.fetcher();
+        set({ items, loading: false });
+      },
+    }),
+  });
+}
+
+// Kullanım
+const userStore = createListStore<User>({
+  name: 'users',
+  fetcher: () => fetch('/api/users').then(r => r.json()),
+});
+```
+
+### Union Type State
+
+```tsx
+type Theme = 'light' | 'dark';
+
+interface SettingsState {
+  theme: Theme;
+  language: 'en' | 'tr';
+}
+
+const settingsStore = createStore<SettingsState>({
+  name: 'settings',
+  initialState: {
+    theme: 'light',
+    language: 'en',
+  },
+});
+```
+
+### Discriminated Union
+
+```tsx
+type LoadingState = {
+  status: 'loading';
+};
+
+type SuccessState<T> = {
+  status: 'success';
+  data: T;
+};
+
+type ErrorState = {
+  status: 'error';
+  error: Error;
+};
+
+type AsyncState<T> = LoadingState | SuccessState<T> | ErrorState;
+
+interface DataState {
+  user: AsyncState<User>;
+  posts: AsyncState<Post[]>;
+}
+
+const dataStore = createStore<DataState>({
+  name: 'data',
+  initialState: {
+    user: { status: 'loading' },
+    posts: { status: 'loading' },
+  },
+  actions: (set) => ({
+    loadUser: async () => {
+      set({ user: { status: 'loading' } });
+
+      try {
+        const user = await fetchUser();
+        set({ user: { status: 'success', data: user } });
+      } catch (error) {
+        set({ user: { status: 'error', error: error as Error } });
+      }
+    },
+  }),
+});
+```
+
+### Recursive Type
+
+```tsx
+interface TreeNode {
+  id: string;
+  value: any;
+  children: TreeNode[];
+}
+
+interface TreeState {
+  root: TreeNode | null;
+}
+
+const treeStore = createStore<TreeState>({
+  name: 'tree',
+  initialState: { root: null },
+  actions: (set, get) => ({
+    setRoot: (root: TreeNode) => set({ root }),
+
+    findNode: (id: string): TreeNode | null => {
+      const { root } = get();
+
+      const search = (node: TreeNode | null): TreeNode | null => {
+        if (!node) return null;
+        if (node.id === id) return node;
+
+        for (const child of node.children) {
+          const found = search(child);
+          if (found) return found;
+        }
+
+        return null;
+      };
+
+      return search(root);
+    },
+  }),
+});
+```
+
+### Conditional Type
+
+```tsx
+type StoreType<T> = T extends true
+  ? PersistedStore<T>
+  : EphemeralStore<T>;
+
+interface PersistedStore<T> {
+  getState: () => T;
+  setState: (partial: Partial<T>) => void;
+  persist: true;
+}
+
+interface EphemeralStore<T> {
+  getState: () => T;
+  setState: (partial: Partial<T>) => void;
+}
+```
+
+### Utility Types
+
+```tsx
+// DeepPartial - tüm nested özellikler optional
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object
+    ? DeepPartial<T[P]>
+    : T[P];
+};
+
+// ReadOnly
+type ReadOnlyState<T> = {
+  readonly [P in keyof T]: T[P];
+};
+
+// Optional
+type OptionalState<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+// Required
+type RequiredState<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+```
+
+## Type Guards
+
+```tsx
+function isSuccessState<T>(state: AsyncState<T>): state is SuccessState<T> {
+  return state.status === 'success';
+}
+
+function isErrorState<T>(state: AsyncState<T>): state is ErrorState {
+  return state.status === 'error';
+}
+
+function isLoadingState<T>(state: AsyncState<T>): state is LoadingState {
+  return state.status === 'loading';
+}
+
+// Kullanım
+const { user } = dataStore.getState();
+
+if (isSuccessState(user)) {
+  console.log(user.data.name); // Type narrowing: user.data exists
+} else if (isErrorState(user)) {
+  console.error(user.error.message); // Type narrowing: user.error exists
+}
+```
+
+## Type Inference
+
+### Infer State from Store
+
+```tsx
+import { createStore } from '@umituz/react-native-storage';
+
+const store = createStore({
+  name: 'counter',
+  initialState: { count: 0 },
+  actions: (set) => ({
+    increment: () => set((state) => ({ count: state.count + 1 })),
+  }),
+});
+
+// State tipi otomatik çıkarılır
+type CounterState = ReturnType<typeof store.getState>;
+// { count: number; increment: () => void; }
+```
+
+### Extract Actions
+
+```tsx
+type Actions = Pick<CounterState, 'increment'>;
+// { increment: () => void; }
+```
+
+### Extract State
+
+```tsx
+type State = Omit<CounterState, 'increment'>;
+// { count: number; }
+```
+
+## Branded Types
+
+```tsx
+type UserId = string & { readonly __brand: unique symbol };
+type PostId = string & { readonly __brand: unique symbol };
+
+function createUserId(id: string): UserId {
+  return id as UserId;
+}
+
+function createPostId(id: string): PostId {
+  return id as PostId;
+}
+
+// Yanlış kullanım engellenir
+const userId: UserId = createUserId('user-123');
+const postId: PostId = createPostId('post-456');
+
+// postId = userId; // Type error!
+```
+
+## Template Literal Types
+
+```tsx
+type StorageKey = `user:${string}` | `post:${string}`;
+
+function getStorage<T extends StorageKey>(key: T): any {
+  // ...
+}
+
+const userKey: StorageKey = 'user:123'; // OK
+const postKey: StorageKey = 'post:456'; // OK
+const invalidKey: StorageKey = 'data'; // Type error!
+```
+
+## Generic Constraints
+
+```tsx
+interface Entity {
+  id: string;
+}
+
+interface EntityState<T extends Entity> {
+  items: T[];
+  selectedId: string | null;
+}
+
+function createStoreWithEntity<T extends Entity>(config: {
+  name: string;
+  initialState: EntityState<T>;
+}) {
+  return createStore<EntityState<T>>({
+    name: config.name,
+    initialState: config.initialState,
+    actions: (set) => ({
+      setSelected: (id: string) => set({ selectedId: id }),
+      clearSelected: () => set({ selectedId: null }),
+    }),
+  });
+}
+
+// Kullanım
+interface User extends Entity {
+  name: string;
+}
+
+interface Product extends Entity {
+  price: number;
+}
+
+const userStore = createStoreWithEntity<User>({
+  name: 'users',
+  initialState: { items: [], selectedId: null },
+});
+
+const productStore = createStoreWithEntity<Product>({
+  name: 'products',
+  initialState: { items: [], selectedId: null },
+});
+```
+
+## Mapped Types
+
+```tsx
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<K & string>}`]: () => T[K];
+};
+
+interface Settings {
+  theme: string;
+  language: string;
+}
+
+type SettingsGetters = Getters<Settings>;
+// {
+//   getTheme: () => string;
+//   getLanguage: () => string;
+// }
+```
+
+## Conditional Types with Enums
+
+```tsx
+enum Status {
+  Loading = 'loading',
+  Success = 'success',
+  Error = 'error',
+}
+
+type StateByStatus<S extends Status> =
+  S extends Status.Loading ? { loading: true } :
+  S extends Status.Success ? { data: any } :
+  S extends Status.Error ? { error: Error } :
+  never;
+```