rn-remove-image-bg 0.0.10

package/src/__tests__/cache.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// Mock expo-file-system before importing cache
+vi.mock('expo-file-system/legacy', () => ({
+  cacheDirectory: '/mock/cache/',
+  getInfoAsync: vi.fn().mockResolvedValue({ exists: false }),
+  makeDirectoryAsync: vi.fn().mockResolvedValue(undefined),
+  readAsStringAsync: vi.fn().mockResolvedValue('{}'),
+  writeAsStringAsync: vi.fn().mockResolvedValue(undefined),
+  deleteAsync: vi.fn().mockResolvedValue(undefined),
+}));
+
+// Import after mocking
+import { bgRemovalCache } from '../cache';
+
+describe('BackgroundRemovalCache', () => {
+  beforeEach(async () => {
+    // Clear cache before each test
+    await bgRemovalCache.clear();
+  });
+
+  describe('hashOptions', () => {
+    it('should hash options to JSON string', () => {
+      const hash = bgRemovalCache.hashOptions({
+        format: 'PNG',
+        maxDimension: 1024,
+        quality: 100,
+      });
+
+      expect(hash).toBe('{"format":"PNG","maxDimension":1024,"quality":100}');
+    });
+
+    it('should produce consistent hash regardless of key order', () => {
+      const hash1 = bgRemovalCache.hashOptions({ a: 1, b: 2 });
+      const hash2 = bgRemovalCache.hashOptions({ b: 2, a: 1 });
+
+      expect(hash1).toBe(hash2);
+    });
+
+    it('should exclude functions from hash', () => {
+      const hash = bgRemovalCache.hashOptions({
+        value: 1,
+        callback: () => {},
+      });
+
+      expect(hash).toBe('{"value":1}');
+    });
+  });
+
+  describe('size', () => {
+    it('should return 0 for empty cache', () => {
+      expect(bgRemovalCache.size).toBe(0);
+    });
+  });
+
+  describe('set and get', () => {
+    it('should store and retrieve cached results', async () => {
+      const path = 'file:///test/image.jpg';
+      const optionsHash = bgRemovalCache.hashOptions({ format: 'PNG' });
+      const resultPath = 'file:///cache/result.png';
+
+      bgRemovalCache.set(path, optionsHash, resultPath);
+
+      expect(bgRemovalCache.size).toBe(1);
+    });
+  });
+
+  describe('clear', () => {
+    it('should clear all cache entries', async () => {
+      bgRemovalCache.set('path1', 'hash1', 'result1');
+      bgRemovalCache.set('path2', 'hash2', 'result2');
+
+      expect(bgRemovalCache.size).toBe(2);
+
+      await bgRemovalCache.clear();
+
+      expect(bgRemovalCache.size).toBe(0);
+    });
+  });
+
+  describe('getCacheDirectory', () => {
+    it('should return the cache directory path', () => {
+      const dir = bgRemovalCache.getCacheDirectory();
+      expect(dir).toContain('bg-removal');
+    });
+  });
+
+  describe('configure', () => {
+    it('should allow updating cache configuration', () => {
+      bgRemovalCache.configure({
+        maxEntries: 100,
+        maxAgeMinutes: 60,
+        persistToDisk: true,
+      });
+
+      // Configuration applied - no error thrown
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('prune', () => {
+    it('should return 0 when no entries are expired', () => {
+      bgRemovalCache.set('path', 'hash', 'result');
+
+      const removed = bgRemovalCache.prune();
+
+      expect(removed).toBe(0);
+    });
+  });
+});

package/src/__tests__/errors.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import { BackgroundRemovalError, wrapNativeError } from '../errors';
+
+describe('BackgroundRemovalError', () => {
+  describe('constructor', () => {
+    it('should create an error with message and code', () => {
+      const error = new BackgroundRemovalError('Test message', 'INVALID_PATH');
+
+      expect(error.message).toBe('Test message');
+      expect(error.code).toBe('INVALID_PATH');
+      expect(error.name).toBe('BackgroundRemovalError');
+      expect(error.originalError).toBeUndefined();
+    });
+
+    it('should preserve original error', () => {
+      const originalError = new Error('Original error');
+      const error = new BackgroundRemovalError(
+        'Wrapped',
+        'UNKNOWN',
+        originalError
+      );
+
+      expect(error.originalError).toBe(originalError);
+    });
+  });
+
+  describe('toUserMessage', () => {
+    it('should return user-friendly message for INVALID_PATH', () => {
+      const error = new BackgroundRemovalError('test', 'INVALID_PATH');
+      expect(error.toUserMessage()).toBe('The image path provided is invalid.');
+    });
+
+    it('should return user-friendly message for FILE_NOT_FOUND', () => {
+      const error = new BackgroundRemovalError('test', 'FILE_NOT_FOUND');
+      expect(error.toUserMessage()).toBe('The image file could not be found.');
+    });
+
+    it('should return user-friendly message for DECODE_FAILED', () => {
+      const error = new BackgroundRemovalError('test', 'DECODE_FAILED');
+      expect(error.toUserMessage()).toBe(
+        'The image could not be read. Please ensure it is a valid image file.'
+      );
+    });
+
+    it('should return user-friendly message for ML_PROCESSING_FAILED', () => {
+      const error = new BackgroundRemovalError('test', 'ML_PROCESSING_FAILED');
+      expect(error.toUserMessage()).toBe(
+        'Background removal failed. Please try with a different image.'
+      );
+    });
+
+    it('should return user-friendly message for SAVE_FAILED', () => {
+      const error = new BackgroundRemovalError('test', 'SAVE_FAILED');
+      expect(error.toUserMessage()).toBe('Could not save the processed image.');
+    });
+
+    it('should return user-friendly message for INVALID_OPTIONS', () => {
+      const error = new BackgroundRemovalError('test', 'INVALID_OPTIONS');
+      expect(error.toUserMessage()).toBe(
+        'Invalid options provided for background removal.'
+      );
+    });
+
+    it('should return default message for UNKNOWN', () => {
+      const error = new BackgroundRemovalError('test', 'UNKNOWN');
+      expect(error.toUserMessage()).toBe(
+        'An unexpected error occurred during background removal.'
+      );
+    });
+  });
+});
+
+describe('wrapNativeError', () => {
+  it('should return same error if already BackgroundRemovalError', () => {
+    const error = new BackgroundRemovalError('test', 'INVALID_PATH');
+    const wrapped = wrapNativeError(error);
+
+    expect(wrapped).toBe(error);
+  });
+
+  it('should wrap string error', () => {
+    const wrapped = wrapNativeError('Something went wrong');
+
+    expect(wrapped).toBeInstanceOf(BackgroundRemovalError);
+    expect(wrapped.message).toBe('Something went wrong');
+    expect(wrapped.code).toBe('UNKNOWN');
+  });
+
+  it('should detect FILE_NOT_FOUND from message', () => {
+    const error = new Error('File does not exist at path');
+    const wrapped = wrapNativeError(error);
+
+    expect(wrapped.code).toBe('FILE_NOT_FOUND');
+    expect(wrapped.originalError).toBe(error);
+  });
+
+  it('should detect DECODE_FAILED from message', () => {
+    const error = new Error('Could not decode image');
+    const wrapped = wrapNativeError(error);
+
+    expect(wrapped.code).toBe('DECODE_FAILED');
+  });
+
+  it('should detect ML_PROCESSING_FAILED from message', () => {
+    const error = new Error('Failed to generate mask');
+    const wrapped = wrapNativeError(error);
+
+    expect(wrapped.code).toBe('ML_PROCESSING_FAILED');
+  });
+
+  it('should detect SAVE_FAILED from message', () => {
+    const error = new Error('Could not save output file');
+    const wrapped = wrapNativeError(error);
+
+    expect(wrapped.code).toBe('SAVE_FAILED');
+  });
+});

package/src/cache.ts

@@ -0,0 +1,305 @@
+import * as FileSystem from 'expo-file-system/legacy';
+
+/**
+ * Cache entry for processed images
+ */
+interface CacheEntry {
+  /** Original file path */
+  originalPath: string;
+  /** Result file path */
+  resultPath: string;
+  /** Timestamp when cached */
+  timestamp: number;
+  /** Options hash to differentiate processing configs */
+  optionsHash: string;
+}
+
+/**
+ * Disk cache manifest structure
+ */
+interface CacheManifest {
+  version: number;
+  entries: Record<string, CacheEntry>;
+}
+
+/**
+ * Configuration for the background removal cache
+ */
+export interface CacheConfig {
+  /** Maximum number of entries in memory (default: 50) */
+  maxEntries?: number;
+  /** Maximum age of cache entries in minutes (default: 30) */
+  maxAgeMinutes?: number;
+  /** Enable disk persistence (default: false) */
+  persistToDisk?: boolean;
+  /** Custom cache directory (default: FileSystem.cacheDirectory + 'bg-removal/') */
+  cacheDirectory?: string;
+}
+
+const MANIFEST_FILENAME = 'cache-manifest.json';
+const CACHE_VERSION = 1;
+
+/**
+ * LRU cache for background removal results with optional disk persistence
+ */
+class BackgroundRemovalCache {
+  private cache = new Map<string, CacheEntry>();
+  private _maxEntries: number;
+  private _maxAgeMs: number;
+  private persistToDisk: boolean;
+  private cacheDirectory: string;
+  private initialized = false;
+
+  constructor(config: CacheConfig = {}) {
+    this._maxEntries = config.maxEntries ?? 50;
+    this._maxAgeMs = (config.maxAgeMinutes ?? 30) * 60 * 1000;
+    this.persistToDisk = config.persistToDisk ?? false;
+    this.cacheDirectory =
+      config.cacheDirectory ?? `${FileSystem.cacheDirectory}bg-removal/`;
+  }
+
+  /**
+   * Configure cache settings
+   */
+  configure(config: CacheConfig): void {
+    if (config.maxEntries !== undefined) {
+      this._maxEntries = config.maxEntries;
+    }
+    if (config.maxAgeMinutes !== undefined) {
+      this._maxAgeMs = config.maxAgeMinutes * 60 * 1000;
+    }
+    if (config.persistToDisk !== undefined) {
+      this.persistToDisk = config.persistToDisk;
+    }
+    if (config.cacheDirectory !== undefined) {
+      this.cacheDirectory = config.cacheDirectory;
+    }
+  }
+
+  /**
+   * Initialize disk cache (load manifest if exists)
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized || !this.persistToDisk) return;
+
+    try {
+      // Ensure cache directory exists
+      const dirInfo = await FileSystem.getInfoAsync(this.cacheDirectory);
+      if (!dirInfo.exists) {
+        await FileSystem.makeDirectoryAsync(this.cacheDirectory, {
+          intermediates: true,
+        });
+      }
+
+      // Load manifest if exists
+      const manifestPath = `${this.cacheDirectory}${MANIFEST_FILENAME}`;
+      const manifestInfo = await FileSystem.getInfoAsync(manifestPath);
+
+      if (manifestInfo.exists) {
+        const manifestJson = await FileSystem.readAsStringAsync(manifestPath);
+        const manifest: CacheManifest = JSON.parse(manifestJson);
+
+        if (manifest.version === CACHE_VERSION) {
+          // Validate and load entries
+          for (const [key, entry] of Object.entries(manifest.entries)) {
+            const fileInfo = await FileSystem.getInfoAsync(entry.resultPath);
+            if (fileInfo.exists) {
+              this.cache.set(key, entry);
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.warn(
+        '[rn-remove-image-bg] Failed to load cache manifest:',
+        error
+      );
+    }
+
+    this.initialized = true;
+  }
+
+  /**
+   * Save cache manifest to disk
+   */
+  private async saveManifest(): Promise<void> {
+    if (!this.persistToDisk) return;
+
+    try {
+      const manifest: CacheManifest = {
+        version: CACHE_VERSION,
+        entries: Object.fromEntries(this.cache.entries()),
+      };
+
+      const manifestPath = `${this.cacheDirectory}${MANIFEST_FILENAME}`;
+      await FileSystem.writeAsStringAsync(
+        manifestPath,
+        JSON.stringify(manifest, null, 2)
+      );
+    } catch (error) {
+      console.warn(
+        '[rn-remove-image-bg] Failed to save cache manifest:',
+        error
+      );
+    }
+  }
+
+  /**
+   * Generate a cache key from path and options
+   */
+  private generateKey(path: string, optionsHash: string): string {
+    return `${path}::${optionsHash}`;
+  }
+
+  /**
+   * Hash options object to string for cache key
+   */
+  hashOptions(options: Record<string, unknown>): string {
+    const sorted = Object.keys(options)
+      .sort()
+      .reduce(
+        (acc, key) => {
+          const value = options[key];
+          // Exclude functions from hash
+          if (typeof value !== 'function') {
+            acc[key] = value;
+          }
+          return acc;
+        },
+        {} as Record<string, unknown>
+      );
+    return JSON.stringify(sorted);
+  }
+
+  /**
+   * Get cached result if valid
+   */
+  async get(path: string, optionsHash: string): Promise<string | null> {
+    await this.initialize();
+
+    const key = this.generateKey(path, optionsHash);
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if expired
+    if (Date.now() - entry.timestamp > this._maxAgeMs) {
+      this.cache.delete(key);
+      this.saveManifest();
+      return null;
+    }
+
+    // Verify result file still exists
+    try {
+      const info = await FileSystem.getInfoAsync(entry.resultPath);
+      if (!info.exists) {
+        this.cache.delete(key);
+        this.saveManifest();
+        return null;
+      }
+    } catch {
+      this.cache.delete(key);
+      this.saveManifest();
+      return null;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    return entry.resultPath;
+  }
+
+  /**
+   * Store result in cache
+   */
+  set(path: string, optionsHash: string, resultPath: string): void {
+    const key = this.generateKey(path, optionsHash);
+
+    // Evict oldest entries if at capacity
+    while (this.cache.size >= this._maxEntries) {
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey) {
+        this.cache.delete(oldestKey);
+      }
+    }
+
+    this.cache.set(key, {
+      originalPath: path,
+      resultPath,
+      timestamp: Date.now(),
+      optionsHash,
+    });
+
+    this.saveManifest();
+  }
+
+  /**
+   * Clear all cached entries
+   * @param deleteFiles - Also delete cached files from disk (default: false)
+   */
+  async clear(deleteFiles = false): Promise<void> {
+    if (deleteFiles && this.persistToDisk) {
+      try {
+        // Delete all cached result files
+        for (const entry of this.cache.values()) {
+          try {
+            await FileSystem.deleteAsync(entry.resultPath, {
+              idempotent: true,
+            });
+          } catch {
+            // Ignore individual file deletion errors
+          }
+        }
+
+        // Delete manifest
+        const manifestPath = `${this.cacheDirectory}${MANIFEST_FILENAME}`;
+        await FileSystem.deleteAsync(manifestPath, { idempotent: true });
+      } catch (error) {
+        console.warn('[rn-remove-image-bg] Error clearing cache files:', error);
+      }
+    }
+
+    this.cache.clear();
+  }
+
+  /**
+   * Get current cache size
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Remove expired entries
+   */
+  prune(): number {
+    const now = Date.now();
+    let removed = 0;
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (now - entry.timestamp > this._maxAgeMs) {
+        this.cache.delete(key);
+        removed++;
+      }
+    }
+
+    if (removed > 0) {
+      this.saveManifest();
+    }
+
+    return removed;
+  }
+
+  /**
+   * Get cache directory path
+   */
+  getCacheDirectory(): string {
+    return this.cacheDirectory;
+  }
+}
+
+// Export singleton instance
+export const bgRemovalCache = new BackgroundRemovalCache();

package/src/errors.ts

@@ -0,0 +1,93 @@
+/**
+ * Error codes for background removal operations
+ */
+export type BackgroundRemovalErrorCode =
+  | 'INVALID_PATH'
+  | 'FILE_NOT_FOUND'
+  | 'DECODE_FAILED'
+  | 'ML_PROCESSING_FAILED'
+  | 'SAVE_FAILED'
+  | 'INVALID_OPTIONS'
+  | 'UNKNOWN';
+
+/**
+ * Custom error class for background removal operations
+ */
+export class BackgroundRemovalError extends Error {
+  readonly code: BackgroundRemovalErrorCode;
+  readonly originalError?: Error;
+
+  constructor(
+    message: string,
+    code: BackgroundRemovalErrorCode,
+    originalError?: Error
+  ) {
+    super(message);
+    this.name = 'BackgroundRemovalError';
+    this.code = code;
+    this.originalError = originalError;
+
+    // Maintain proper stack trace in V8 environments
+    if ('captureStackTrace' in Error) {
+      (Error as any).captureStackTrace(this, BackgroundRemovalError);
+    }
+  }
+
+  /**
+   * Create a user-friendly error message
+   */
+  toUserMessage(): string {
+    switch (this.code) {
+      case 'INVALID_PATH':
+        return 'The image path provided is invalid.';
+      case 'FILE_NOT_FOUND':
+        return 'The image file could not be found.';
+      case 'DECODE_FAILED':
+        return 'The image could not be read. Please ensure it is a valid image file.';
+      case 'ML_PROCESSING_FAILED':
+        return 'Background removal failed. Please try with a different image.';
+      case 'SAVE_FAILED':
+        return 'Could not save the processed image.';
+      case 'INVALID_OPTIONS':
+        return 'Invalid options provided for background removal.';
+      default:
+        return 'An unexpected error occurred during background removal.';
+    }
+  }
+}
+
+/**
+ * Helper to wrap native errors with proper typing
+ */
+export function wrapNativeError(error: unknown): BackgroundRemovalError {
+  if (error instanceof BackgroundRemovalError) {
+    return error;
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  const originalError = error instanceof Error ? error : undefined;
+
+  // Try to determine error code from message
+  if (message.includes('does not exist') || message.includes('not found')) {
+    return new BackgroundRemovalError(message, 'FILE_NOT_FOUND', originalError);
+  }
+  if (message.includes('decode') || message.includes('load image')) {
+    return new BackgroundRemovalError(message, 'DECODE_FAILED', originalError);
+  }
+  if (
+    message.includes('mask') ||
+    message.includes('segment') ||
+    message.includes('ML')
+  ) {
+    return new BackgroundRemovalError(
+      message,
+      'ML_PROCESSING_FAILED',
+      originalError
+    );
+  }
+  if (message.includes('save') || message.includes('write')) {
+    return new BackgroundRemovalError(message, 'SAVE_FAILED', originalError);
+  }
+
+  return new BackgroundRemovalError(message, 'UNKNOWN', originalError);
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+import {
+  compressImage,
+  generateThumbhash,
+  removeBgImage,
+  removeBackground,
+  clearCache,
+  getCacheSize,
+  onLowMemory,
+  configureCache,
+  getCacheDirectory,
+} from './ImageProcessing';
+import type {
+  CompressImageOptions,
+  GenerateThumbhashOptions,
+  RemoveBgImageOptions,
+  OutputFormat,
+} from './ImageProcessing';
+import {
+  BackgroundRemovalError,
+  type BackgroundRemovalErrorCode,
+} from './errors';
+import type { CacheConfig } from './cache';
+
+export {
+  // Functions
+  compressImage,
+  generateThumbhash,
+  removeBgImage,
+  removeBackground,
+  clearCache,
+  getCacheSize,
+  // Memory management
+  onLowMemory,
+  configureCache,
+  getCacheDirectory,
+  // Errors
+  BackgroundRemovalError,
+};
+
+export type {
+  // Options types
+  CompressImageOptions,
+  GenerateThumbhashOptions,
+  RemoveBgImageOptions,
+  OutputFormat,
+  BackgroundRemovalErrorCode,
+  // Cache types
+  CacheConfig,
+};

package/src/specs/Example.nitro.ts

@@ -0,0 +1 @@
+// TODO: Export specs that extend HybridObject<...> here