rn-remove-image-bg 0.0.31 → 0.0.33

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/lib/web/core/BackgroundRemover.d.ts

@@ -0,0 +1,31 @@
+import type { RemoveBgImageOptions } from './types';
+type ImglyConfig = {
+    publicPath?: string;
+    progress?: (key: string, current: number, total: number) => void;
+    debug?: boolean;
+    output?: {
+        format?: 'image/png' | 'image/jpeg' | 'image/webp';
+        quality?: number;
+        type?: 'foreground' | 'background' | 'mask';
+    };
+};
+type ImglyRemoveBackground = (image: string | Blob | ArrayBuffer, config?: ImglyConfig) => Promise<Blob>;
+declare global {
+    interface Window {
+        imglyRemoveBackground?: ImglyRemoveBackground;
+    }
+}
+export declare const BackgroundRemover: {
+    /**
+     * Checks if the background removal library is loaded.
+     */
+    isAvailable(): boolean;
+    /**
+     * Removes background from an image.
+     * Returns a Blob of the processed image (PNG with transparency).
+     *
+     * Requires @imgly/background-removal to be loaded via CDN script tag.
+     */
+    remove(uri: string, options: RemoveBgImageOptions): Promise<Blob>;
+};
+export {};

package/lib/web/core/BackgroundRemover.js

@@ -0,0 +1,64 @@
+import { mapErrorToBackgroundRemovalError, BackgroundRemovalError } from '../errors/WebErrorAdapter';
+import { normalizeUri } from '../utils/uriHelper';
+/**
+ * Gets the @imgly removeBackground function from window.
+ * This must be loaded via CDN script tag before use.
+ */
+function getImglyRemoveBackground() {
+    if (typeof window === 'undefined') {
+        throw new BackgroundRemovalError('Background removal is only available in browser environment.', 'ENVIRONMENT_ERROR');
+    }
+    if (!window.imglyRemoveBackground) {
+        throw new BackgroundRemovalError('Background removal library not loaded. Please add the following script to your HTML:\n' +
+            '<script type="module">\n' +
+            '  import { removeBackground } from "https://cdn.jsdelivr.net/npm/@imgly/background-removal@1.7.0/+esm";\n' +
+            '  window.imglyRemoveBackground = removeBackground;\n' +
+            '</script>', 'LIBRARY_NOT_LOADED');
+    }
+    return window.imglyRemoveBackground;
+}
+export const BackgroundRemover = {
+    /**
+     * Checks if the background removal library is loaded.
+     */
+    isAvailable() {
+        return typeof window !== 'undefined' && typeof window.imglyRemoveBackground === 'function';
+    },
+    /**
+     * Removes background from an image.
+     * Returns a Blob of the processed image (PNG with transparency).
+     *
+     * Requires @imgly/background-removal to be loaded via CDN script tag.
+     */
+    async remove(uri, options) {
+        try {
+            const imglyRemove = getImglyRemoveBackground();
+            const normalizedUri = await normalizeUri(uri);
+            const config = {
+                // Pass publicPath if provided (for self-hosted assets)
+                publicPath: options.publicPath,
+                // Map progress callback
+                progress: (_key, current, total) => {
+                    if (options.onProgress && total > 0) {
+                        const p = Math.min(100, Math.round((current / total) * 100));
+                        options.onProgress(p);
+                    }
+                },
+                // Enable debug logging if requested
+                debug: options.debug ?? false,
+                // Explicit output configuration for transparent PNG
+                output: {
+                    format: 'image/png',
+                    quality: 1.0,
+                    type: 'foreground', // Extract foreground with transparency
+                },
+            };
+            // Execute removal
+            const blob = await imglyRemove(normalizedUri, config);
+            return blob;
+        }
+        catch (error) {
+            throw mapErrorToBackgroundRemovalError(error);
+        }
+    }
+};

package/lib/web/core/CacheManager.d.ts

@@ -0,0 +1,16 @@
+import type { RemoveBgImageOptions } from './types';
+export declare class CacheManager {
+    private cache;
+    private readonly MAX_SIZE;
+    constructor();
+    /**
+     * Generates a unique cache key based on input URI and processing options
+     */
+    private generateKey;
+    get(uri: string, options: RemoveBgImageOptions): string | null;
+    set(uri: string, options: RemoveBgImageOptions, dataUrl: string): void;
+    clear(): void;
+    size(): number;
+    private evictOldest;
+}
+export declare const cacheManager: CacheManager;

package/lib/web/core/CacheManager.js

@@ -0,0 +1,57 @@
+export class CacheManager {
+    cache;
+    MAX_SIZE = 50; // Limit to 50 items to avoid memory leaks
+    constructor() {
+        this.cache = new Map();
+    }
+    /**
+     * Generates a unique cache key based on input URI and processing options
+     */
+    generateKey(uri, options) {
+        // We include relevant options that affect output
+        const { format = 'PNG', quality = 100, maxDimension = 0 } = options;
+        return `${uri}|${format}|${quality}|${maxDimension}`;
+    }
+    get(uri, options) {
+        const key = this.generateKey(uri, options);
+        const entry = this.cache.get(key);
+        if (entry) {
+            entry.timestamp = Date.now(); // Update usage timestamp (simple LRU)
+            return entry.dataUrl;
+        }
+        return null;
+    }
+    set(uri, options, dataUrl) {
+        const key = this.generateKey(uri, options);
+        // Evict if full
+        if (this.cache.size >= this.MAX_SIZE) {
+            this.evictOldest();
+        }
+        this.cache.set(key, {
+            dataUrl,
+            timestamp: Date.now()
+        });
+    }
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size;
+    }
+    evictOldest() {
+        // Find oldest entry
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.timestamp < oldestTime) {
+                oldestTime = entry.timestamp;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+        }
+    }
+}
+// Singleton instance
+export const cacheManager = new CacheManager();

package/lib/web/core/types.d.ts

@@ -0,0 +1,47 @@
+export type OutputFormat = 'PNG' | 'WEBP';
+export interface RemoveBgImageOptions {
+    /**
+     * Output format of the processed image.
+     * Default: 'PNG'
+     */
+    format?: OutputFormat;
+    /**
+     * Quality of the output image (0-100). Only applies to WEBP/JPEG.
+     * Default: 100
+     */
+    quality?: number;
+    /**
+     * Callback to track download and processing progress (0-100).
+     */
+    onProgress?: (progress: number) => void;
+    /**
+     * Enable debug logging.
+     * Default: false
+     */
+    debug?: boolean;
+    /**
+     * Maximum dimension for the output image. Use this to resize large images before processing.
+     */
+    maxDimension?: number;
+    /**
+     * Public path to serve the model assets from.
+     * If not provided, it will attempt to fetch from @imgly CDN.
+     * Important for Metro bundler compatibility if not using CDN.
+     */
+    publicPath?: string;
+    /**
+     * Whether to use the cache for this request.
+     * Default: true
+     */
+    useCache?: boolean;
+}
+export interface CompressImageOptions {
+    maxSizeKB?: number;
+    width?: number;
+    height?: number;
+    quality?: number;
+    format?: 'webp' | 'png' | 'jpeg';
+}
+export interface GenerateThumbhashOptions {
+    size?: number;
+}

package/lib/web/core/types.js

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

package/lib/web/errors/WebErrorAdapter.d.ts

@@ -0,0 +1,8 @@
+export declare class BackgroundRemovalError extends Error {
+    code: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Maps library errors to standardized BackgroundRemovalError
+ */
+export declare function mapErrorToBackgroundRemovalError(error: unknown): BackgroundRemovalError;

package/lib/web/errors/WebErrorAdapter.js

@@ -0,0 +1,29 @@
+export class BackgroundRemovalError extends Error {
+    code;
+    constructor(message, code = 'UNKNOWN_ERROR') {
+        super(message);
+        this.name = 'BackgroundRemovalError';
+        this.code = code;
+    }
+}
+/**
+ * Maps library errors to standardized BackgroundRemovalError
+ */
+export function mapErrorToBackgroundRemovalError(error) {
+    if (error instanceof BackgroundRemovalError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    // Model loading errors
+    if (message.includes('fetch') || message.includes('network') || message.includes('Failed to load resource')) {
+        return new BackgroundRemovalError(`Failed to download AI model. Please check your internet connection. (Details: ${message})`, 'MODEL_DOWNLOAD_ERROR');
+    }
+    // WASM errors
+    if (message.includes('wasm') || message.includes('WebAssembly')) {
+        return new BackgroundRemovalError(`WebAssembly failed to initialize. Your browser might not support it. (Details: ${message})`, 'WASM_INIT_ERROR');
+    }
+    // Processing errors
+    if (message.includes('memory') || message.includes('allocation')) {
+        return new BackgroundRemovalError('Out of memory. Try using a smaller maxDimension or closing other tabs.', 'MEMORY_ERROR');
+    }
+    return new BackgroundRemovalError(message);
+}

package/lib/web/utils/CompressImage.d.ts

@@ -0,0 +1,2 @@
+import type { CompressImageOptions } from '../core/types';
+export declare function compressImage(uri: string, options: CompressImageOptions): Promise<string>;