@umituz/react-native-design-system 4.27.14 → 4.27.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "4.27.14",
+  "version": "4.27.15",
   "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive, safe area, exception, infinite scroll, UUID, image, timezone, offline, onboarding, and loading utilities - TanStack persistence and expo-image-manipulator now lazy loaded",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/core/cache/domain/CleanupStrategy.ts

@@ -0,0 +1,115 @@
+/**
+ * Cleanup Strategy
+ *
+ * Strategy pattern for cache cleanup mechanisms.
+ * Allows switching between interval-based and recursive timeout-based cleanup.
+ */
+
+import type { CleanupType } from './types';
+
+/**
+ * Cleanup strategy interface for cache expiration
+ */
+export interface CleanupStrategy {
+  /**
+   * Start cleanup mechanism
+   * @param callback - Function to call on each cleanup cycle
+   */
+  start(callback: () => void): void;
+
+  /**
+   * Stop cleanup mechanism and release resources
+   */
+  stop(): void;
+
+  /**
+   * Strategy type identifier
+   */
+  readonly type: CleanupType;
+}
+
+/**
+ * Interval-based cleanup strategy
+ * Uses setInterval for periodic cleanup
+ *
+ * @example
+ * ```ts
+ * const strategy = new IntervalCleanupStrategy(60000); // Every minute
+ * strategy.start(() => cache.cleanup());
+ * ```
+ */
+export class IntervalCleanupStrategy implements CleanupStrategy {
+  private interval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(private readonly intervalMs: number) {}
+
+  start(callback: () => void): void {
+    if (this.interval) {
+      return;
+    }
+
+    this.interval = setInterval(callback, this.intervalMs);
+  }
+
+  stop(): void {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+  }
+
+  get type(): 'interval' {
+    return 'interval';
+  }
+}
+
+/**
+ * Timeout-based cleanup strategy
+ * Uses recursive setTimeout for cleanup
+ *
+ * @example
+ * ```ts
+ * const strategy = new TimeoutCleanupStrategy(60000); // Every minute
+ * strategy.start(() => cache.cleanup());
+ * ```
+ */
+export class TimeoutCleanupStrategy implements CleanupStrategy {
+  private timeout: ReturnType<typeof setTimeout> | null = null;
+  private destroyed = false;
+
+  constructor(private readonly timeoutMs: number) {}
+
+  start(callback: () => void): void {
+    if (this.destroyed || this.timeout) {
+      return;
+    }
+
+    const reschedule = () => {
+      if (this.destroyed) {
+        return;
+      }
+
+      this.timeout = setTimeout(() => {
+        callback();
+        if (!this.destroyed) {
+          reschedule();
+        }
+      }, this.timeoutMs);
+    };
+
+    reschedule();
+  }
+
+  stop(): void {
+    this.destroyed = true;
+
+    if (this.timeout) {
+      clearTimeout(this.timeout);
+      this.timeout = null;
+    }
+  }
+
+  get type(): 'timeout' {
+    return 'timeout';
+  }
+}

package/src/core/cache/domain/UnifiedCache.ts

@@ -0,0 +1,196 @@
+/**
+ * Unified Cache
+ *
+ * Generic TTL-based cache with pluggable cleanup strategy.
+ * Merges functionality from SimpleCache and TTLCache.
+ *
+ * @example
+ * ```ts
+ * // With interval cleanup (like TTLCache)
+ * const cache = new UnifiedCache<string>({
+ *   defaultTTL: 60000,
+ *   cleanupStrategy: new IntervalCleanupStrategy(60000)
+ * });
+ *
+ * // With timeout cleanup (like SimpleCache)
+ * const cache = new UnifiedCache<string>({
+ *   defaultTTL: 60000,
+ *   cleanupStrategy: new TimeoutCleanupStrategy(60000)
+ * });
+ * ```
+ */
+
+import type { CacheEntry, CacheConfig } from './types';
+import { CleanupStrategy, IntervalCleanupStrategy } from './CleanupStrategy';
+
+export interface UnifiedCacheConfig extends CacheConfig {
+  cleanupStrategy?: CleanupStrategy;
+  onExpired?: (key: string, count: number) => void;
+}
+
+/**
+ * Unified generic cache with TTL support and pluggable cleanup
+ */
+export class UnifiedCache<T = unknown> {
+  protected cache = new Map<string, CacheEntry<T>>();
+  protected defaultTTL: number;
+  private cleanupStrategy: CleanupStrategy;
+  private isDestroyed = false;
+  private onExpiredCallback?: (key: string, count: number) => void;
+
+  constructor(config: UnifiedCacheConfig = {}) {
+    this.defaultTTL = config.defaultTTL ?? 60000;
+    this.cleanupStrategy = config.cleanupStrategy ?? new IntervalCleanupStrategy(60000);
+    this.onExpiredCallback = config.onExpired;
+
+    this.cleanupStrategy.start(() => this.cleanup());
+  }
+
+  /**
+   * Set value with optional TTL override
+   */
+  set(key: string, value: T, ttl?: number): void {
+    if (this.isDestroyed) {
+      this.warnDestroyed('set');
+      return;
+    }
+
+    const now = Date.now();
+    this.cache.set(key, {
+      value,
+      expires: now + (ttl ?? this.defaultTTL),
+      timestamp: now,
+    });
+  }
+
+  /**
+   * Get value, returns undefined if expired or not found
+   */
+  get(key: string): T | undefined {
+    if (this.isDestroyed) {
+      this.warnDestroyed('get');
+      return undefined;
+    }
+
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return undefined;
+    }
+
+    if (this.isExpired(entry)) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * Check if key exists and is not expired
+   */
+  has(key: string): boolean {
+    if (this.isDestroyed) {
+      return false;
+    }
+
+    return this.get(key) !== undefined;
+  }
+
+  /**
+   * Delete specific key
+   */
+  delete(key: string): boolean {
+    if (this.isDestroyed) {
+      return false;
+    }
+
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all entries
+   */
+  clear(): void {
+    if (this.isDestroyed) {
+      return;
+    }
+
+    this.cache.clear();
+  }
+
+  /**
+   * Get all non-expired keys
+   */
+  keys(): string[] {
+    if (this.isDestroyed) {
+      return [];
+    }
+
+    return Array.from(this.cache.keys()).filter((key) => {
+      const entry = this.cache.get(key);
+      return entry && !this.isExpired(entry);
+    });
+  }
+
+  /**
+   * Get cache size (excluding expired entries)
+   */
+  size(): number {
+    return this.keys().length;
+  }
+
+  /**
+   * Destroy cache and stop cleanup
+   */
+  destroy(): void {
+    if (this.isDestroyed) {
+      return;
+    }
+
+    this.isDestroyed = true;
+    this.cleanupStrategy.stop();
+    this.cache.clear();
+  }
+
+  /**
+   * Cleanup expired entries
+   */
+  protected cleanup(): void {
+    if (this.isDestroyed) {
+      return;
+    }
+
+    const now = Date.now();
+    let cleanedCount = 0;
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expires) {
+        this.cache.delete(key);
+        cleanedCount++;
+      }
+    }
+
+    if (cleanedCount > 0 && this.onExpiredCallback) {
+      this.onExpiredCallback('cleanup', cleanedCount);
+    }
+  }
+
+  /**
+   * Check if entry is expired
+   */
+  private isExpired(entry: CacheEntry<T>): boolean {
+    return Date.now() > entry.expires;
+  }
+
+  /**
+   * Warn about operation on destroyed cache
+   */
+  private warnDestroyed(operation: string): void {
+    if (__DEV__) {
+      console.warn(
+        `[UnifiedCache] Cannot perform "${operation}" on destroyed cache`
+      );
+    }
+  }
+}

package/src/core/cache/domain/types.ts

@@ -0,0 +1,18 @@
+/**
+ * Core Cache Domain Types
+ *
+ * Shared types for cache implementations
+ */
+
+export interface CacheEntry<T> {
+  value: T;
+  expires: number;
+  timestamp: number;
+}
+
+export interface CacheConfig {
+  defaultTTL?: number;
+  cleanupIntervalMs?: number;
+}
+
+export type CleanupType = 'interval' | 'timeout';

package/src/core/cache/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Core Cache Module
+ *
+ * Unified cache implementation with strategy pattern.
+ * Replaces SimpleCache and TTLCache with single implementation.
+ */
+
+export { UnifiedCache } from './domain/UnifiedCache';
+export type { UnifiedCacheConfig } from './domain/UnifiedCache';
+
+export { CleanupStrategy, IntervalCleanupStrategy, TimeoutCleanupStrategy } from './domain/CleanupStrategy';
+export type { CleanupType } from './domain/CleanupStrategy';
+
+export { CacheFactory } from './infrastructure/CacheFactory';
+
+export type { CacheEntry, CacheConfig } from './domain/types';

package/src/core/cache/infrastructure/CacheFactory.ts

@@ -0,0 +1,102 @@
+/**
+ * Cache Factory
+ *
+ * Factory for creating cache instances with common configurations.
+ * Provides convenient methods for different cache types.
+ */
+
+import { UnifiedCache } from '../domain/UnifiedCache';
+import { IntervalCleanupStrategy, TimeoutCleanupStrategy } from '../domain/CleanupStrategy';
+import type { UnifiedCacheConfig } from '../domain/UnifiedCache';
+
+/**
+ * Factory for creating cache instances
+ */
+export class CacheFactory {
+  /**
+   * Create cache with interval-based cleanup (like TTLCache)
+   *
+   * @param defaultTTL - Default time-to-live in milliseconds
+   * @param cleanupInterval - Cleanup interval in milliseconds
+   *
+   * @example
+   * ```ts
+   * const cache = CacheFactory.createIntervalCache(60000, 60000);
+   * ```
+   */
+  static createIntervalCache<T = unknown>(
+    defaultTTL: number = 60000,
+    cleanupInterval: number = 60000
+  ): UnifiedCache<T> {
+    return new UnifiedCache<T>({
+      defaultTTL,
+      cleanupStrategy: new IntervalCleanupStrategy(cleanupInterval),
+    });
+  }
+
+  /**
+   * Create cache with timeout-based cleanup (like SimpleCache)
+   *
+   * @param defaultTTL - Default time-to-live in milliseconds
+   * @param cleanupTimeout - Cleanup timeout in milliseconds
+   *
+   * @example
+   * ```ts
+   * const cache = CacheFactory.createTimeoutCache(60000, 60000);
+   * ```
+   */
+  static createTimeoutCache<T = unknown>(
+    defaultTTL: number = 60000,
+    cleanupTimeout: number = 60000
+  ): UnifiedCache<T> {
+    return new UnifiedCache<T>({
+      defaultTTL,
+      cleanupStrategy: new TimeoutCleanupStrategy(cleanupTimeout),
+    });
+  }
+
+  /**
+   * Create cache with custom configuration
+   *
+   * @example
+   * ```ts
+   * const cache = CacheFactory.createCustomCache({
+   *   defaultTTL: 120000,
+   *   cleanupStrategy: new IntervalCleanupStrategy(30000),
+   *   onExpired: (key, count) => console.log(`Expired ${count} items`)
+   * });
+   * ```
+   */
+  static createCustomCache<T = unknown>(
+    config: UnifiedCacheConfig
+  ): UnifiedCache<T> {
+    return new UnifiedCache<T>(config);
+  }
+
+  /**
+   * Create cache without automatic cleanup (manual cleanup only)
+   *
+   * @param defaultTTL - Default time-to-live in milliseconds
+   *
+   * @example
+   * ```ts
+   * const cache = CacheFactory.createManualCache(60000);
+   * // ... later
+   * cache.cleanup(); // Manual cleanup
+   * ```
+   */
+  static createManualCache<T = unknown>(
+    defaultTTL: number = 60000
+  ): UnifiedCache<T> {
+    return new UnifiedCache<T>({
+      defaultTTL,
+      cleanupStrategy: {
+        start: () => {},
+        stop: () => {},
+        get type(): 'interval' | 'timeout' {
+          return 'interval';
+        },
+      },
+    });
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Core Module
+ *
+ * Shared abstractions and utilities for the design system.
+ * Provides cache, permissions, errors, and repository foundations.
+ */
+
+// Cache
+export { UnifiedCache, CacheFactory } from './cache/domain/UnifiedCache';
+export { CleanupStrategy, IntervalCleanupStrategy, TimeoutCleanupStrategy } from './cache/domain/CleanupStrategy';
+export type { UnifiedCacheConfig } from './cache/domain/UnifiedCache';
+export type { CacheEntry, CacheConfig } from './cache/domain/types';
+
+// Permissions
+export { PermissionHandler } from './permissions/domain/PermissionHandler';
+export type { PermissionMethod, PermissionStatus, PermissionResult, PermissionHandlerConfig, PermissionMethods } from './permissions/domain/types';
+
+// Repositories
+export { createRepositoryKeyFactory } from './repositories/domain/RepositoryKeyFactory';
+export { mergeRepositoryOptions, getCacheOptions, normalizeListParams, createRepositoryLogger } from './repositories/domain/RepositoryUtils';
+export type { RepositoryOptions, ListParams, CreateParams, UpdateParams, QueryKeyFactory } from './repositories/domain/types';

package/src/core/permissions/domain/PermissionHandler.ts

@@ -0,0 +1,139 @@
+/**
+ * Generic Permission Handler
+ *
+ * Generic permission handling using strategy pattern.
+ * Reduces permission method duplication from 4 methods → 1 generic handler.
+ *
+ * @example
+ * ```ts
+ * const handler = new PermissionHandler({
+ *   methods: {
+ *     request: {
+ *       camera: ImagePicker.requestCameraPermissionsAsync,
+ *       mediaLibrary: ImagePicker.requestMediaLibraryPermissionsAsync,
+ *     },
+ *     get: {
+ *       camera: ImagePicker.getCameraPermissionsAsync,
+ *       mediaLibrary: ImagePicker.getMediaLibraryPermissionsAsync,
+ *     },
+ *   },
+ *   statusMapper: mapPermissionStatus,
+ *   defaultStatus: MediaLibraryPermission.DENIED,
+ * });
+ *
+ * // Request permission
+ * const status = await handler.handle('request', 'camera');
+ *
+ * // Check if granted
+ * if (handler.isGranted(status)) {
+ *   // Proceed with operation
+ * }
+ * ```
+ */
+
+import type {
+  PermissionMethod,
+  PermissionStatus,
+  PermissionHandlerConfig,
+  PermissionMethods,
+} from './types';
+
+/**
+ * Generic permission handler with configurable methods and status mapping
+ */
+export class PermissionHandler<TPermission extends PermissionStatus = PermissionStatus> {
+  private methods: PermissionMethods;
+  private statusMapper: (apiStatus: string) => TPermission;
+  private defaultStatus: TPermission;
+
+  constructor(config: PermissionHandlerConfig<TPermission>) {
+    this.methods = config.methods;
+    this.statusMapper = config.statusMapper;
+    this.defaultStatus = config.defaultStatus ?? ('denied' as TPermission);
+  }
+
+  /**
+   * Handle permission request or status check
+   *
+   * @param method - 'request' or 'get'
+   * @param type - Permission type key (e.g., 'camera', 'mediaLibrary')
+   * @returns Permission status
+   */
+  async handle(
+    method: PermissionMethod,
+    type: string
+  ): Promise<TPermission> {
+    const permissionFn = this.methods[method]?.[type];
+
+    if (!permissionFn) {
+      if (__DEV__) {
+        console.warn(
+          `[PermissionHandler] No ${method} method found for permission type: ${type}`
+        );
+      }
+      return this.defaultStatus;
+    }
+
+    try {
+      const result = await permissionFn();
+      return this.statusMapper(result.status);
+    } catch (error) {
+      if (__DEV__) {
+        console.warn(
+          `[PermissionHandler] Failed to ${method} ${type} permission:`,
+          error
+        );
+      }
+      return this.defaultStatus;
+    }
+  }
+
+  /**
+   * Check if permission status is granted
+   *
+   * @param status - Permission status to check
+   * @returns true if permission is granted or limited
+   */
+  isGranted(status: TPermission): boolean {
+    return (
+      status === 'granted' ||
+      status === 'limited' ||
+      (status as string) === 'granted' ||
+      (status as string) === 'limited'
+    );
+  }
+
+  /**
+   * Check if permission status is denied
+   *
+   * @param status - Permission status to check
+   * @returns true if permission is denied
+   */
+  isDenied(status: TPermission): boolean {
+    return !this.isGranted(status);
+  }
+
+  /**
+   * Request permission by type
+   *
+   * @example
+   * ```ts
+   * const status = await handler.request('camera');
+   * ```
+   */
+  async request(type: string): Promise<TPermission> {
+    return this.handle('request', type);
+  }
+
+  /**
+   * Get permission status by type
+   *
+   * @example
+   * ```ts
+   * const status = await handler.getStatus('camera');
+   * ```
+   */
+  async getStatus(type: string): Promise<TPermission> {
+    return this.handle('get', type);
+  }
+}

package/src/core/permissions/domain/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Core Permissions Domain Types
+ *
+ * Generic types for permission handling
+ */
+
+export type PermissionMethod = 'request' | 'get';
+
+/**
+ * Permission status types
+ * Apps can extend this for custom permission types
+ */
+export type PermissionStatus = 'granted' | 'denied' | 'limited' | 'undetermined';
+
+/**
+ * Permission result with metadata
+ */
+export interface PermissionResult {
+  status: PermissionStatus;
+  canAskAgain?: boolean;
+}
+
+/**
+ * Permission handler configuration
+ */
+export interface PermissionHandlerConfig<TPermission extends PermissionStatus = PermissionStatus> {
+  /**
+   * Map permission API methods
+   */
+  methods: PermissionMethods;
+
+  /**
+   * Map API status to domain permission type
+   */
+  statusMapper: (apiStatus: string) => TPermission;
+
+  /**
+   * Default status when permission fails
+   */
+  defaultStatus?: TPermission;
+}
+
+/**
+ * Permission API methods mapping
+ */
+export interface PermissionMethods {
+  request: Record<string, () => Promise<PermissionResult>>;
+  get: Record<string, () => Promise<PermissionResult>>;
+}

package/src/core/permissions/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Core Permissions Module
+ *
+ * Generic permission handling with configurable methods and status mapping.
+ */
+
+export { PermissionHandler } from './domain/PermissionHandler';
+
+export type {
+  PermissionMethod,
+  PermissionStatus,
+  PermissionResult,
+  PermissionHandlerConfig,
+  PermissionMethods,
+} from './domain/types';