@umituz/react-native-filesystem 1.0.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@umituz/react-native-filesystem",
+  "version": "1.0.0",
+  "description": "Domain-Driven Design filesystem utilities for React Native apps with build-time module loading and runtime file operations",
+  "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'"
+  },
+  "keywords": [
+    "react-native",
+    "filesystem",
+    "file-system",
+    "expo-file-system",
+    "module-loader",
+    "require-context",
+    "ddd",
+    "domain-driven-design",
+    "type-safe"
+  ],
+  "author": "Ümit UZ <umit@umituz.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:umituz/react-native-filesystem.git"
+  },
+  "peerDependencies": {
+    "expo-file-system": "~17.0.0",
+    "react": ">=18.2.0",
+    "react-native": ">=0.74.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.45",
+    "@types/react-native": "^0.73.0",
+    "expo-file-system": "~17.0.0",
+    "react": "^18.2.0",
+    "react-native": "^0.74.0",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}
+

package/src/domain/entities/File.ts

@@ -0,0 +1,134 @@
+/**
+ * Filesystem Domain - File Entities
+ *
+ * This file defines core types and interfaces for runtime file operations.
+ * Uses expo-file-system for reading, writing, and managing files on device.
+ *
+ * @domain filesystem
+ * @layer domain/entities
+ */
+
+/**
+ * File information interface
+ */
+export interface FileInfo {
+  uri: string;
+  name: string;
+  size: number;
+  exists: boolean;
+  isDirectory: boolean;
+  modificationTime: number;
+}
+
+/**
+ * File encoding types (compatible with expo-file-system)
+ */
+export type FileEncoding = 'utf8' | 'base64';
+
+/**
+ * Directory type (compatible with expo-file-system)
+ */
+export type DirectoryType = 'documentDirectory' | 'cacheDirectory';
+
+/**
+ * File operation result
+ */
+export interface FileOperationResult {
+  success: boolean;
+  uri?: string;
+  error?: string;
+}
+
+/**
+ * Download progress info
+ */
+export interface DownloadProgress {
+  totalBytesWritten: number;
+  totalBytesExpectedToWrite: number;
+  progress: number; // 0 to 1
+}
+
+/**
+ * File constants
+ */
+export const FILE_CONSTANTS = {
+  MAX_FILE_NAME_LENGTH: 255,
+  DEFAULT_ENCODING: 'utf8' as FileEncoding,
+  TEMP_FILE_PREFIX: 'tmp_',
+} as const;
+
+/**
+ * File utilities
+ */
+export class FileUtils {
+  /**
+   * Generate unique filename with timestamp
+   */
+  static generateUniqueFilename(originalName: string): string {
+    const timestamp = Date.now();
+    const randomStr = Math.random().toString(36).substring(7);
+    const extension = FileUtils.getFileExtension(originalName);
+    const baseName = originalName.replace(extension, '').substring(0, 50);
+    return `${baseName}_${timestamp}_${randomStr}${extension}`;
+  }
+
+  /**
+   * Get file extension from filename
+   */
+  static getFileExtension(filename: string): string {
+    const match = filename.match(/\.[^.]+$/);
+    return match ? match[0] : '';
+  }
+
+  /**
+   * Get filename without extension
+   */
+  static getFilenameWithoutExtension(filename: string): string {
+    return filename.replace(/\.[^.]+$/, '');
+  }
+
+  /**
+   * Sanitize filename (remove invalid characters)
+   */
+  static sanitizeFilename(filename: string): string {
+    return filename
+      .replace(/[^a-zA-Z0-9._-]/g, '_')
+      .substring(0, FILE_CONSTANTS.MAX_FILE_NAME_LENGTH);
+  }
+
+  /**
+   * Format file size to human-readable string
+   */
+  static formatFileSize(bytes: number): string {
+    if (bytes === 0) return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${(bytes / Math.pow(k, i)).toFixed(2)} ${sizes[i]}`;
+  }
+
+  /**
+   * Parse download progress percentage
+   */
+  static calculateProgress(written: number, total: number): number {
+    if (total === 0) return 0;
+    return Math.min(Math.max(written / total, 0), 1);
+  }
+
+  /**
+   * Check if path is absolute
+   */
+  static isAbsolutePath(path: string): boolean {
+    return path.startsWith('/') || path.startsWith('file://');
+  }
+
+  /**
+   * Join path segments
+   */
+  static joinPaths(...segments: string[]): string {
+    return segments
+      .filter(Boolean)
+      .join('/')
+      .replace(/\/+/g, '/');
+  }
+}

package/src/domain/entities/ModuleContext.ts

@@ -0,0 +1,29 @@
+/**
+ * Module Context Entity
+ *
+ * Type definitions for Metro bundler's require.context feature
+ * Used for automatic file discovery and module loading
+ */
+
+/**
+ * Metro bundler require.context return type
+ */
+export interface RequireContext {
+  keys(): string[];
+  (id: string): any;
+  <T>(id: string): T;
+  resolve(id: string): string;
+  id: string;
+}
+
+/**
+ * Module collection type
+ * Key: module name (without extension)
+ * Value: module content
+ */
+export type ModuleCollection = Record<string, any>;
+
+/**
+ * File extension type for filtering
+ */
+export type FileExtension = '.json' | '.js' | '.ts' | '.tsx';

package/src/index.ts

@@ -0,0 +1,178 @@
+/**
+ * Filesystem Domain - Barrel Export
+ *
+ * CENTRAL PLACE FOR ALL FILE OPERATIONS
+ *
+ * Provides two main capabilities:
+ * 1. Build-time module loading (require.context)
+ * 2. Runtime file operations (expo-file-system)
+ *
+ * @domain filesystem
+ * @enabled true (All apps - Infrastructure domain)
+ *
+ * ARCHITECTURE:
+ * - Domain Layer: Entities (ModuleContext for build-time, File for runtime)
+ * - Infrastructure Layer: Utils (module loading) + Services (file operations)
+ *
+ * ============================================================================
+ * BUILD-TIME MODULE LOADING (require.context)
+ * ============================================================================
+ *
+ * FEATURES:
+ * - Auto-discover JSON files in directory
+ * - Load all modules with single function call
+ * - Type-safe module loading
+ * - Metro bundler compatible (React Native)
+ * - Zero runtime dependencies
+ * - Build-time resolution (fast)
+ *
+ * USAGE - Build-time Module Loading:
+ *
+ * Basic Example:
+ * ```typescript
+ * import { loadJsonModules } from '@domains/filesystem';
+ *
+ * // Auto-load all JSON files in current directory
+ * const translationContext = require.context('./', false, /\.json$/);
+ * const translations = loadJsonModules(translationContext);
+ *
+ * export default translations;
+ * // Result: { common: {...}, errors: {...}, settings: {...} }
+ * ```
+ *
+ * Custom Transform Example:
+ * ```typescript
+ * import { loadModulesWithTransform } from '@domains/filesystem';
+ *
+ * const context = require.context('./', false, /\.json$/);
+ * const modules = loadModulesWithTransform(context, name => name.toUpperCase());
+ * // Result: { COMMON: {...}, ERRORS: {...} }
+ * ```
+ *
+ * Get Names Example:
+ * ```typescript
+ * import { getModuleNames } from '@domains/filesystem';
+ *
+ * const context = require.context('./', false, /\.json$/);
+ * const names = getModuleNames(context);
+ * // Result: ['common', 'errors', 'settings']
+ * ```
+ *
+ * ============================================================================
+ * RUNTIME FILE OPERATIONS (expo-file-system)
+ * ============================================================================
+ *
+ * FEATURES:
+ * - Read/write files on device
+ * - Download files from URLs
+ * - Directory management
+ * - Cache management
+ * - File copying/moving
+ *
+ * USAGE - Runtime File Operations:
+ *
+ * Read/Write Files:
+ * ```typescript
+ * import { FileSystemService } from '@domains/filesystem';
+ *
+ * // Write file
+ * const result = await FileSystemService.writeFile(
+ *   FileSystemService.generateFilePath('data.json'),
+ *   JSON.stringify({ key: 'value' })
+ * );
+ *
+ * // Read file
+ * const content = await FileSystemService.readFile(result.uri);
+ * ```
+ *
+ * Download Files:
+ * ```typescript
+ * import { FileSystemService } from '@domains/filesystem';
+ *
+ * const result = await FileSystemService.downloadFile(
+ *   'https://example.com/file.pdf'
+ * );
+ * if (result.success) {
+ *   console.log('Downloaded to:', result.uri);
+ * }
+ * ```
+ *
+ * Directory Operations:
+ * ```typescript
+ * import { FileSystemService, FileUtils } from '@domains/filesystem';
+ *
+ * // Get document directory
+ * const docDir = FileSystemService.getDocumentDirectory();
+ *
+ * // List files
+ * const files = await FileSystemService.listDirectory(docDir);
+ *
+ * // Clear cache
+ * await FileSystemService.clearCache();
+ * ```
+ *
+ * File Utilities:
+ * ```typescript
+ * import { FileUtils } from '@domains/filesystem';
+ *
+ * // Format file size
+ * const size = FileUtils.formatFileSize(1024000); // "1.00 MB"
+ *
+ * // Generate unique filename
+ * const filename = FileUtils.generateUniqueFilename('photo.jpg');
+ *
+ * // Sanitize filename
+ * const safe = FileUtils.sanitizeFilename('my file!@#.txt'); // "my_file___.txt"
+ * ```
+ *
+ * BENEFITS:
+ * - Centralized file operations (no duplication)
+ * - Type-safe with TypeScript
+ * - Works across all 100+ apps
+ * - Used by other domains (media, etc.)
+ * - Clean, maintainable code
+ *
+ * @see https://docs.expo.dev/versions/latest/sdk/filesystem/
+ */
+
+// ============================================================================
+// BUILD-TIME MODULE LOADING
+// ============================================================================
+
+// Domain Layer - Module Context Entities
+export type {
+  RequireContext,
+  ModuleCollection,
+  FileExtension,
+} from './domain/entities/ModuleContext';
+
+// Infrastructure Layer - Module Loading Utils
+export {
+  loadJsonModules,
+  loadModulesWithTransform,
+  getModuleNames,
+} from './infrastructure/utils/moduleLoader';
+
+// ============================================================================
+// RUNTIME FILE OPERATIONS
+// ============================================================================
+
+// Domain Layer - File Entities
+export type {
+  FileInfo,
+  FileOperationResult,
+  DownloadProgress,
+} from './domain/entities/File';
+
+export type {
+  FileEncoding,
+  DirectoryType,
+} from './domain/entities/File';
+
+export {
+  FILE_CONSTANTS,
+  FileUtils,
+} from './domain/entities/File';
+
+// Infrastructure Layer - FileSystem Service
+export { FileSystemService } from './infrastructure/services/FileSystemService';

package/src/infrastructure/services/FileSystemService.ts

@@ -0,0 +1,265 @@
+/**
+ * Filesystem Domain - FileSystem Service
+ *
+ * Service for runtime file operations using expo-file-system.
+ * Provides abstraction layer for file read/write/delete operations on device.
+ *
+ * @domain filesystem
+ * @layer infrastructure/services
+ */
+
+import * as FileSystem from 'expo-file-system';
+import type { FileInfo, FileOperationResult, DirectoryType, FileEncoding } from '../../domain/entities/File';
+import { FileUtils } from '../../domain/entities/File';
+
+/**
+ * FileSystem service for device file operations
+ *
+ * CENTRAL PLACE FOR ALL FILE OPERATIONS
+ * - Reading/writing files
+ * - Directory management
+ * - File downloads
+ * - Cache management
+ *
+ * Used by other domains (media, etc.) for file operations
+ */
+export class FileSystemService {
+  /**
+   * Get file information
+   */
+  static async getFileInfo(uri: string): Promise<FileInfo | null> {
+    try {
+      const info = await FileSystem.getInfoAsync(uri);
+
+      if (!info.exists) {
+        return null;
+      }
+
+      return {
+        uri,
+        name: uri.split('/').pop() || '',
+        size: info.size || 0,
+        exists: info.exists,
+        isDirectory: info.isDirectory || false,
+        modificationTime: info.modificationTime || 0,
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Read file as string
+   */
+  static async readFile(uri: string, encoding: FileEncoding = 'utf8'): Promise<string | null> {
+    try {
+      const content = await FileSystem.readAsStringAsync(uri, { encoding });
+      return content;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Write string to file
+   */
+  static async writeFile(uri: string, content: string, encoding: FileEncoding = 'utf8'): Promise<FileOperationResult> {
+    try {
+      await FileSystem.writeAsStringAsync(uri, content, { encoding });
+      return { success: true, uri };
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Delete file or directory
+   */
+  static async deleteFile(uri: string): Promise<boolean> {
+    try {
+      await FileSystem.deleteAsync(uri, { idempotent: true });
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Copy file
+   */
+  static async copyFile(sourceUri: string, destinationUri: string): Promise<FileOperationResult> {
+    try {
+      await FileSystem.copyAsync({
+        from: sourceUri,
+        to: destinationUri,
+      });
+      return { success: true, uri: destinationUri };
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Move file
+   */
+  static async moveFile(sourceUri: string, destinationUri: string): Promise<FileOperationResult> {
+    try {
+      await FileSystem.moveAsync({
+        from: sourceUri,
+        to: destinationUri,
+      });
+      return { success: true, uri: destinationUri };
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : 'Unknown error' };
+    }
+  }
+
+  /**
+   * Create directory
+   */
+  static async createDirectory(uri: string): Promise<boolean> {
+    try {
+      await FileSystem.makeDirectoryAsync(uri, { intermediates: true });
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * List directory contents
+   */
+  static async listDirectory(uri: string): Promise<string[]> {
+    try {
+      const files = await FileSystem.readDirectoryAsync(uri);
+      return files;
+    } catch (error) {
+      return [];
+    }
+  }
+
+  /**
+   * Check if file exists
+   */
+  static async exists(uri: string): Promise<boolean> {
+    try {
+      const info = await FileSystem.getInfoAsync(uri);
+      return info.exists;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Get directory path by type
+   */
+  static getDirectoryPath(type: DirectoryType): string {
+    switch (type) {
+      case 'documentDirectory':
+        return FileSystem.documentDirectory || '';
+      case 'cacheDirectory':
+        return FileSystem.cacheDirectory || '';
+      default:
+        return '';
+    }
+  }
+
+  /**
+   * Get document directory path
+   */
+  static getDocumentDirectory(): string {
+    return FileSystemService.getDirectoryPath('documentDirectory');
+  }
+
+  /**
+   * Get cache directory path
+   */
+  static getCacheDirectory(): string {
+    return FileSystemService.getDirectoryPath('cacheDirectory');
+  }
+
+  /**
+   * Generate unique file path in specified directory
+   */
+  static generateFilePath(filename: string, directory: DirectoryType = 'documentDirectory'): string {
+    const dirPath = FileSystemService.getDirectoryPath(directory);
+    const uniqueFilename = FileUtils.generateUniqueFilename(filename);
+    return FileUtils.joinPaths(dirPath, uniqueFilename);
+  }
+
+  /**
+   * Download file from URL
+   */
+  static async downloadFile(url: string, destinationUri?: string): Promise<FileOperationResult> {
+    try {
+      const destination = destinationUri || FileSystemService.generateFilePath('download');
+      const result = await FileSystem.downloadAsync(url, destination);
+      return { success: true, uri: result.uri };
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : 'Download failed' };
+    }
+  }
+
+  /**
+   * Get file size
+   */
+  static async getFileSize(uri: string): Promise<number> {
+    const info = await FileSystemService.getFileInfo(uri);
+    return info?.size || 0;
+  }
+
+  /**
+   * Clear cache directory
+   */
+  static async clearCache(): Promise<boolean> {
+    try {
+      const cacheDir = FileSystemService.getCacheDirectory();
+      if (!cacheDir) return false;
+
+      const files = await FileSystemService.listDirectory(cacheDir);
+      await Promise.all(
+        files.map(file => FileSystemService.deleteFile(FileUtils.joinPaths(cacheDir, file)))
+      );
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Get total size of directory
+   */
+  static async getDirectorySize(uri: string): Promise<number> {
+    try {
+      const files = await FileSystemService.listDirectory(uri);
+      const sizes = await Promise.all(
+        files.map(async file => {
+          const filePath = FileUtils.joinPaths(uri, file);
+          const info = await FileSystemService.getFileInfo(filePath);
+          return info?.size || 0;
+        })
+      );
+      return sizes.reduce((total, size) => total + size, 0);
+    } catch (error) {
+      return 0;
+    }
+  }
+
+  /**
+   * Copy file to cache directory
+   */
+  static async copyToCache(sourceUri: string, filename?: string): Promise<FileOperationResult> {
+    const name = filename || sourceUri.split('/').pop() || 'file';
+    const destinationUri = FileSystemService.generateFilePath(name, 'cacheDirectory');
+    return FileSystemService.copyFile(sourceUri, destinationUri);
+  }
+
+  /**
+   * Copy file to document directory
+   */
+  static async copyToDocuments(sourceUri: string, filename?: string): Promise<FileOperationResult> {
+    const name = filename || sourceUri.split('/').pop() || 'file';
+    const destinationUri = FileSystemService.generateFilePath(name, 'documentDirectory');
+    return FileSystemService.copyFile(sourceUri, destinationUri);
+  }
+}

package/src/infrastructure/utils/moduleLoader.ts

@@ -0,0 +1,99 @@
+/**
+ * Module Loader Utilities
+ *
+ * Provides automatic module loading using Metro bundler's require.context
+ * Used for auto-discovering and importing files at build time
+ *
+ * USAGE:
+ * ```typescript
+ * // Auto-load all JSON files in current directory
+ * const context = require.context('./', false, /\.json$/);
+ * const modules = loadJsonModules(context);
+ * ```
+ */
+
+import type { RequireContext, ModuleCollection } from '../../domain/entities/ModuleContext';
+
+/**
+ * Load JSON modules from a require.context
+ *
+ * @param context - Metro bundler require.context result
+ * @returns Object with module names as keys and content as values
+ *
+ * @example
+ * ```typescript
+ * const translationContext = require.context('./', false, /\.json$/);
+ * const translations = loadJsonModules(translationContext);
+ * // Result: { common: {...}, errors: {...}, settings: {...} }
+ * ```
+ */
+export function loadJsonModules(context: RequireContext): ModuleCollection {
+  const modules: ModuleCollection = {};
+
+  context.keys().forEach((key: string) => {
+    // Extract module name from path
+    // './animation.json' -> 'animation'
+    // './common.json' -> 'common'
+    const moduleName = key
+      .replace('./', '')
+      .replace(/\.(json|js|ts|tsx)$/, '');
+
+    // Load module content
+    modules[moduleName] = context(key);
+  });
+
+  return modules;
+}
+
+/**
+ * Load modules with custom name transformation
+ *
+ * @param context - Metro bundler require.context result
+ * @param transformName - Function to transform module name
+ * @returns Object with transformed names as keys
+ *
+ * @example
+ * ```typescript
+ * const context = require.context('./', false, /\.json$/);
+ * const modules = loadModulesWithTransform(context, name => name.toUpperCase());
+ * // Result: { COMMON: {...}, ERRORS: {...} }
+ * ```
+ */
+export function loadModulesWithTransform(
+  context: RequireContext,
+  transformName: (name: string) => string
+): ModuleCollection {
+  const modules: ModuleCollection = {};
+
+  context.keys().forEach((key: string) => {
+    const baseName = key
+      .replace('./', '')
+      .replace(/\.(json|js|ts|tsx)$/, '');
+
+    const transformedName = transformName(baseName);
+    modules[transformedName] = context(key);
+  });
+
+  return modules;
+}
+
+/**
+ * Get list of module names from context
+ *
+ * @param context - Metro bundler require.context result
+ * @returns Array of module names (without extensions)
+ *
+ * @example
+ * ```typescript
+ * const context = require.context('./', false, /\.json$/);
+ * const names = getModuleNames(context);
+ * // Result: ['animation', 'common', 'errors', 'settings']
+ * ```
+ */
+export function getModuleNames(context: RequireContext): string[] {
+  return context.keys().map((key: string) =>
+    key
+      .replace('./', '')
+      .replace(/\.(json|js|ts|tsx)$/, '')
+  );
+}