react-native-nitro-image-pipeline 1.3.1 → 1.3.2

package/README.md

@@ -259,11 +259,17 @@ omitted.
 
 ### `preLoadImage(url)`
 
-Prefetches a single image into the cache. Returns `Promise<void>`.
+Prefetches a single image into the **disk cache**, without decoding it. Returns `Promise<void>`.
+
+Prefetching only pays the network and disk I/O cost up front — no bitmap is decoded or held in
+memory, so prefetching a long list of URLs doesn't balloon RAM. The image is decoded (at the
+`resize` target size, when one is given) the first time `loadImage`/`useImage`/`<PipelineImage>`
+actually displays it.
 
 ### `preLoadImages(urls)`
 
-Prefetches multiple images into the cache. Returns `Promise<void>`.
+Prefetches multiple images into the disk cache — same behavior as `preLoadImage`, for a batch.
+Returns `Promise<void>`.
 
 ### `gaussianBlur(image, radius)`
 
@@ -304,6 +310,23 @@ images keep their borders instead of fading out.
 
 Removes all cached images from memory and disk. Returns `Promise<void>` that resolves once both caches are cleared.
 
+## Memory usage
+
+The pipeline is set up so RAM scales with what you display, not with what you download:
+
+- **Pass `resize` (or just use `<PipelineImage>`, which derives it from layout).** With a target
+  size known, both platforms decode the source *near that size* instead of at full resolution —
+  iOS via a downsampled thumbnail decode, Android via Coil's subsampling. Without `resize`, a
+  48 MP photo decompresses to ~190 MB of bitmap no matter how small you display it.
+- **Prefetching stores bytes, not bitmaps.** `preLoadImage(s)` writes the download to the disk
+  cache and skips decoding entirely.
+- **The in-memory cache is capped** (128 MB on iOS, 25% of the app's memory class on Android),
+  holds decoded bitmaps for instant re-display, and evicts least-recently-used entries — also in
+  response to memory warnings and backgrounding. Memory profilers attribute this cache to the app;
+  a plateau at the cap is expected and evictable, not a leak. Use `cache: 'disk'` or
+  `cache: 'none'` on images you know you won't show again soon, and `clearCache()` to drop
+  everything.
+
 ## Upgrading from 0.3.x
 
 `blur` and `gaussianBlur(image, radius)` changed meaning in 1.0. They used to hand the number

package/android/src/main/java/com/margelo/nitro/nitroimagepipeline/HybridNitroImagePipeline.kt

@@ -3,8 +3,11 @@ package com.margelo.nitro.nitroimagepipeline
 import android.content.Context
 import androidx.core.graphics.drawable.toBitmap
 import coil3.BitmapImage
+import coil3.ColorImage
 import coil3.DrawableImage
 import coil3.ImageLoader
+import coil3.decode.DecodeResult
+import coil3.decode.Decoder
 import coil3.disk.DiskCache
 import coil3.memory.MemoryCache
 import coil3.network.okhttp.OkHttpNetworkFetcherFactory
@@ -117,21 +120,25 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
     }
   }
 
+  // Preloading warms the disk cache only: the memory cache is skipped and the
+  // decode step is replaced with a no-op (Coil's documented preload pattern),
+  // so prefetching N URLs costs network + disk I/O instead of N full-resolution
+  // bitmaps on the heap. The image is decoded — subsampled to the requested
+  // size — only when a loadImage actually displays it.
+  private fun preloadRequest(url: String): ImageRequest =
+      ImageRequest.Builder(context)
+          .data(url)
+          .memoryCachePolicy(CachePolicy.DISABLED)
+          .decoderFactory { _, _, _ -> Decoder { DecodeResult(ColorImage(), false) } }
+          .build()
+
   override fun preLoadImage(url: String): Promise<Unit> = Promise.async {
-    val request = ImageRequest.Builder(context).data(url).build()
-    imageLoader.execute(request)
+    imageLoader.execute(preloadRequest(url))
   }
 
   override fun preLoadImages(urls: Array<String>): Promise<Unit> = Promise.async {
     coroutineScope {
-      urls
-          .map { url ->
-            async {
-              val request = ImageRequest.Builder(context).data(url).build()
-              imageLoader.execute(request)
-            }
-          }
-          .awaitAll()
+      urls.map { url -> async { imageLoader.execute(preloadRequest(url)) } }.awaitAll()
     }
     Unit
   }

package/ios/HybridNitroImagePipeline.swift

@@ -95,10 +95,28 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
         // the original download, so they survive memory eviction and
         // restarts without dropping the original for other variants.
         configuration.dataCachePolicy = .storeAll
+        // A private, capped memory cache. The default (ImageCache.shared)
+        // sizes itself at 15% of physical RAM — up to 768 MB of decoded
+        // bitmaps on modern devices before anything is evicted, which shows
+        // up as "high RAM usage" even though it is all evictable cache.
+        // 128 MB still holds ~10 full-screen bitmaps or hundreds of list
+        // thumbnails, and the LRU cache keeps trimming itself on memory
+        // warnings and when the app enters the background.
+        configuration.imageCache = ImageCache(
+            costLimit: min(ImageCache.defaultCostLimit, 128 * 1024 * 1024)
+        )
         return ImagePipeline(configuration: configuration)
     }()
 
-    private static let sharedPrefetcher = ImagePrefetcher(pipeline: sharedPipeline)
+    // `.diskCache` stores the downloaded data without decoding it, so
+    // prefetching N URLs costs network + disk I/O instead of N decoded
+    // full-resolution bitmaps parked in the memory cache (the default
+    // `.memoryCache` destination). The image is decoded — at the requested
+    // target size — only when a loadImage actually displays it.
+    private static let sharedPrefetcher = ImagePrefetcher(
+        pipeline: sharedPipeline,
+        destination: .diskCache
+    )
 
     private var pipeline: ImagePipeline { Self.sharedPipeline }
     private var prefetcher: ImagePrefetcher { Self.sharedPrefetcher }
@@ -133,13 +151,21 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
         }
     }
 
+    /// The target size in pixels, or `nil` when no (valid) resize was requested.
+    private static func resizeSize(for options: Options?) -> CGSize? {
+        guard let resize = options?.resize, resize.width > 0, resize.height > 0 else {
+            return nil
+        }
+        return CGSize(width: resize.width, height: resize.height)
+    }
+
     private static func processors(for options: Options?) -> [any ImageProcessing] {
         var processors: [any ImageProcessing] = []
         // Resize first: blur sigma and corner radii are defined in pixels
         // of the bitmap they run on, so they must see the final size.
-        if let resize = options?.resize, resize.width > 0, resize.height > 0 {
+        if let size = resizeSize(for: options) {
             processors.append(ImageProcessors.Resize(
-                size: CGSize(width: resize.width, height: resize.height),
+                size: size,
                 unit: .pixels,
                 contentMode: .aspectFill,
                 crop: true,
@@ -161,11 +187,24 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
                 throw RuntimeError.error(withMessage: "Invalid URL: \(url)")
             }
 
-            let imgRequest = ImageRequest(
+            var imgRequest = ImageRequest(
                 url: imageUrl,
                 processors: Self.processors(for: options),
                 options: Self.cacheOptions(for: options?.cache)
             )
+            // With a target size known, decode near it (aspect-fill, so the
+            // decoded image always covers the target) instead of at full
+            // resolution — a 48 MP photo displayed as a 300 pt card would
+            // otherwise decompress to ~190 MB before Resize shrinks it.
+            // Matches Android, where the request's size() drives subsampling;
+            // the exact size and crop still come from the Resize processor.
+            if let size = Self.resizeSize(for: options) {
+                imgRequest.thumbnail = ImageRequest.ThumbnailOptions(
+                    size: size,
+                    unit: .pixels,
+                    contentMode: .aspectFill
+                )
+            }
 
             let image = try await self.pipeline.image(for: imgRequest)
             return HybridImage(uiImage: image)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-image-pipeline",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "High-performance image loading, caching, and processing for React Native, built with Nitro Modules",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",