rn-remove-image-bg 0.0.10

package/lib/__tests__/cache.test.js

@@ -0,0 +1,87 @@
+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/lib/__tests__/errors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/errors.test.js

@@ -0,0 +1,82 @@
+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/lib/cache.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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;
+}
+/**
+ * LRU cache for background removal results with optional disk persistence
+ */
+declare class BackgroundRemovalCache {
+    private cache;
+    private _maxEntries;
+    private _maxAgeMs;
+    private persistToDisk;
+    private cacheDirectory;
+    private initialized;
+    constructor(config?: CacheConfig);
+    /**
+     * Configure cache settings
+     */
+    configure(config: CacheConfig): void;
+    /**
+     * Initialize disk cache (load manifest if exists)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Save cache manifest to disk
+     */
+    private saveManifest;
+    /**
+     * Generate a cache key from path and options
+     */
+    private generateKey;
+    /**
+     * Hash options object to string for cache key
+     */
+    hashOptions(options: Record<string, unknown>): string;
+    /**
+     * Get cached result if valid
+     */
+    get(path: string, optionsHash: string): Promise<string | null>;
+    /**
+     * Store result in cache
+     */
+    set(path: string, optionsHash: string, resultPath: string): void;
+    /**
+     * Clear all cached entries
+     * @param deleteFiles - Also delete cached files from disk (default: false)
+     */
+    clear(deleteFiles?: boolean): Promise<void>;
+    /**
+     * Get current cache size
+     */
+    get size(): number;
+    /**
+     * Remove expired entries
+     */
+    prune(): number;
+    /**
+     * Get cache directory path
+     */
+    getCacheDirectory(): string;
+}
+export declare const bgRemovalCache: BackgroundRemovalCache;
+export {};

package/lib/cache.js

@@ -0,0 +1,228 @@
+import * as FileSystem from 'expo-file-system/legacy';
+const MANIFEST_FILENAME = 'cache-manifest.json';
+const CACHE_VERSION = 1;
+/**
+ * LRU cache for background removal results with optional disk persistence
+ */
+class BackgroundRemovalCache {
+    cache = new Map();
+    _maxEntries;
+    _maxAgeMs;
+    persistToDisk;
+    cacheDirectory;
+    initialized = false;
+    constructor(config = {}) {
+        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) {
+        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() {
+        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 = 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
+     */
+    async saveManifest() {
+        if (!this.persistToDisk)
+            return;
+        try {
+            const manifest = {
+                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
+     */
+    generateKey(path, optionsHash) {
+        return `${path}::${optionsHash}`;
+    }
+    /**
+     * Hash options object to string for cache key
+     */
+    hashOptions(options) {
+        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;
+        }, {});
+        return JSON.stringify(sorted);
+    }
+    /**
+     * Get cached result if valid
+     */
+    async get(path, optionsHash) {
+        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, optionsHash, resultPath) {
+        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) {
+        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() {
+        return this.cache.size;
+    }
+    /**
+     * Remove expired entries
+     */
+    prune() {
+        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() {
+        return this.cacheDirectory;
+    }
+}
+// Export singleton instance
+export const bgRemovalCache = new BackgroundRemovalCache();

package/lib/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare class BackgroundRemovalError extends Error {
+    readonly code: BackgroundRemovalErrorCode;
+    readonly originalError?: Error;
+    constructor(message: string, code: BackgroundRemovalErrorCode, originalError?: Error);
+    /**
+     * Create a user-friendly error message
+     */
+    toUserMessage(): string;
+}
+/**
+ * Helper to wrap native errors with proper typing
+ */
+export declare function wrapNativeError(error: unknown): BackgroundRemovalError;

package/lib/errors.js

@@ -0,0 +1,64 @@
+/**
+ * Custom error class for background removal operations
+ */
+export class BackgroundRemovalError extends Error {
+    code;
+    originalError;
+    constructor(message, code, originalError) {
+        super(message);
+        this.name = 'BackgroundRemovalError';
+        this.code = code;
+        this.originalError = originalError;
+        // Maintain proper stack trace in V8 environments
+        if ('captureStackTrace' in Error) {
+            Error.captureStackTrace(this, BackgroundRemovalError);
+        }
+    }
+    /**
+     * Create a user-friendly error message
+     */
+    toUserMessage() {
+        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) {
+    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/lib/index.d.ts

@@ -0,0 +1,6 @@
+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 { compressImage, generateThumbhash, removeBgImage, removeBackground, clearCache, getCacheSize, onLowMemory, configureCache, getCacheDirectory, BackgroundRemovalError, };
+export type { CompressImageOptions, GenerateThumbhashOptions, RemoveBgImageOptions, OutputFormat, BackgroundRemovalErrorCode, CacheConfig, };

package/lib/index.js

@@ -0,0 +1,9 @@
+import { compressImage, generateThumbhash, removeBgImage, removeBackground, clearCache, getCacheSize, onLowMemory, configureCache, getCacheDirectory, } from './ImageProcessing';
+import { BackgroundRemovalError, } from './errors';
+export { 
+// Functions
+compressImage, generateThumbhash, removeBgImage, removeBackground, clearCache, getCacheSize, 
+// Memory management
+onLowMemory, configureCache, getCacheDirectory, 
+// Errors
+BackgroundRemovalError, };

package/lib/specs/Example.nitro.js

@@ -0,0 +1,2 @@
+"use strict";
+// TODO: Export specs that extend HybridObject<...> here

package/lib/specs/ImageBackgroundRemover.nitro.d.ts

@@ -0,0 +1,41 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+/**
+ * Output format for processed images
+ */
+export type OutputFormat = 'PNG' | 'WEBP';
+/**
+ * Native options for background removal
+ */
+export interface NativeRemoveBackgroundOptions {
+    /**
+     * Maximum dimension (width or height) for processing
+     * Larger images will be downsampled for better performance
+     * Default: 2048
+     */
+    maxDimension: number;
+    /**
+     * Output image format
+     * PNG: Lossless, larger file size
+     * WEBP: Smaller file size, good quality
+     * Default: PNG
+     */
+    format: OutputFormat;
+    /**
+     * Quality for WEBP format (0-100)
+     * Ignored for PNG format
+     * Default: 100
+     */
+    quality: number;
+}
+export interface ImageBackgroundRemover extends HybridObject<{
+    ios: 'swift';
+    android: 'kotlin';
+}> {
+    /**
+     * Remove background from an image
+     * @param imagePath - File path or file:// URI to the source image
+     * @param options - Processing options
+     * @returns Promise resolving to the output file path
+     */
+    removeBackground(imagePath: string, options: NativeRemoveBackgroundOptions): Promise<string>;
+}

package/lib/specs/ImageBackgroundRemover.nitro.js

@@ -0,0 +1 @@
+export {};

package/nitro.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://nitro.margelo.com/nitro.schema.json",
+  "cxxNamespace": ["rnremoveimagebg"],
+  "ios": {
+    "iosModuleName": "NitroRnRemoveImageBg"
+  },
+  "android": {
+    "androidNamespace": ["rnremoveimagebg"],
+    "androidCxxLibName": "NitroRnRemoveImageBg"
+  },
+  "autolinking": {
+    "ImageBackgroundRemover": {
+      "kotlin": "HybridImageBackgroundRemover"
+    }
+  },
+  "ignorePaths": ["**/node_modules"]
+}

package/nitrogen/generated/.gitattributes

@@ -0,0 +1 @@
+** linguist-generated=true