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

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)`
 
@@ -300,10 +306,52 @@ RenderScript's true Gaussian, downscaling first when sigma exceeds the single-pa
 ~10.6px and compensating the radius so the result is unchanged. Both clamp at the edges, so blurred
 images keep their borders instead of fading out.
 
+### `setMemoryCacheLimit(bytes)`
+
+Caps the in-memory cache of decoded bitmaps at `bytes`, evicting least-recently-used entries
+immediately if the cache is currently larger. Pass `0` to disable in-memory caching entirely — the
+disk cache keeps working. Synchronous; throws on negative or non-finite values.
+
+```ts
+// Keep at most 32 MB of decoded bitmaps in RAM
+NitroImagePipeline.setMemoryCacheLimit(32 * 1024 * 1024);
+
+// Or opt out of decoded-bitmap caching altogether
+NitroImagePipeline.setMemoryCacheLimit(0);
+```
+
 ### `clearCache()`
 
 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 and tunable** (defaults: 128 MB on iOS, 25% of the app's memory
+  class on Android). It 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. Lower the cap with [`setMemoryCacheLimit`](#setmemorycachelimitbytes), use `cache: 'disk'`
+  or `cache: 'none'` on images you won't show again soon, and `clearCache()` to drop everything.
+- **Coming from a setup with no decoded-image cache** (e.g. loading files you downloaded
+  yourself)? Steady-state RAM will read higher here *by design*: after screens unmount, the cache
+  keeps their bitmaps around for instant re-display. For the old memory profile with the
+  pipeline's features intact, pass `cache: 'disk'` on your requests or call
+  `setMemoryCacheLimit(0)` once — RAM then holds only the images currently referenced, and
+  re-displays decode from the disk cache (cheap, since decodes are subsampled to the target size).
+- **Android + `Image.dispose()`:** only call `dispose()` on images loaded with `cache: 'disk'` /
+  `cache: 'none'` (or with the memory cache disabled). With the memory cache on, the returned
+  image shares its bitmap with the cache, and disposing recycles a bitmap the cache may serve
+  again. Without `dispose()`, images are freed by the JS garbage collector — their bitmap size is
+  reported to it, so unreferenced images do get collected under pressure.
+
 ## 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
   }
@@ -150,6 +157,18 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
         }
       }
 
+  override fun setMemoryCacheLimit(bytes: Double) {
+    require(bytes >= 0 && bytes.isFinite()) {
+      "Memory cache limit must be a non-negative, finite number of bytes (got $bytes)"
+    }
+    imageLoader.memoryCache?.apply {
+      maxSize = bytes.toLong()
+      // Setting maxSize only affects future inserts; evict down to it now so
+      // the call frees memory immediately.
+      trimToSize(bytes.toLong())
+    }
+  }
+
   override fun clearCache(): Promise<Unit> = Promise.async {
     imageLoader.memoryCache?.clear()
     // DiskCache.clear() does file I/O; keep it off the JS thread but await

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)
@@ -189,6 +228,22 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
         }
     }
 
+    func setMemoryCacheLimit(bytes: Double) throws {
+        guard bytes >= 0, bytes.isFinite else {
+            throw RuntimeError.error(
+                withMessage: "Memory cache limit must be a non-negative, finite number of bytes (got \(bytes))"
+            )
+        }
+        guard let cache = pipeline.configuration.imageCache as? ImageCache else { return }
+        // Double(Int.max) rounds up to 2^63, so Int(_:) of the clamped value
+        // would trap; branch instead of min-ing.
+        let limit = bytes >= Double(Int.max) ? Int.max : Int(bytes)
+        cache.costLimit = limit
+        // Setting the limit only affects future inserts; evict down to it now
+        // so the call frees memory immediately.
+        cache.trim(toCost: limit)
+    }
+
     func clearCache() throws -> Promise<Void> {
         return Promise.async {
             self.pipeline.cache.removeAll()

package/lib/typescript/src/specs/nitro-image-toolkit.nitro.d.ts

@@ -73,6 +73,16 @@ export interface NitroImagePipeline extends HybridObject<{
      * {@linkcode Options.blur}.
      */
     gaussianBlur(image: Image, radius: number): Promise<Image>;
+    /**
+     * Caps the in-memory cache of decoded bitmaps at `bytes`, evicting
+     * least-recently-used entries immediately if it is currently larger. Pass
+     * `0` to disable in-memory caching entirely (the disk cache still works).
+     *
+     * Defaults: 128 MB on iOS, 25% of the app's memory class on Android. The
+     * cache trades RAM for instant re-display; lower it (or use
+     * `cache: 'disk'` per request) in memory-constrained apps.
+     */
+    setMemoryCacheLimit(bytes: number): void;
     clearCache(): Promise<void>;
 }
 //# sourceMappingURL=nitro-image-toolkit.nitro.d.ts.map

package/lib/typescript/src/specs/nitro-image-toolkit.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nitro-image-toolkit.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/nitro-image-toolkit.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,OAAO,GAAG;IACpB;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,CAAC;AAEF,MAAM,WAAW,kBAAmB,SAAQ,YAAY,CAAC;IACvD,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,QAAQ,CAAC;CACnB,CAAC;IACA,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAG3D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}
+{"version":3,"file":"nitro-image-toolkit.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/nitro-image-toolkit.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,OAAO,GAAG;IACpB;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,CAAC;AAEF,MAAM,WAAW,kBAAmB,SAAQ,YAAY,CAAC;IACvD,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,QAAQ,CAAC;CACnB,CAAC;IACA,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAG3D;;;;;;;;OAQG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}

package/nitrogen/generated/android/c++/JHybridNitroImagePipelineSpec.cpp

@@ -142,6 +142,10 @@ namespace margelo::nitro::nitroimagepipeline {
       return __promise;
     }();
   }
+  void JHybridNitroImagePipelineSpec::setMemoryCacheLimit(double bytes) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(double /* bytes */)>("setMemoryCacheLimit");
+    method(_javaPart, bytes);
+  }
   std::shared_ptr<Promise<void>> JHybridNitroImagePipelineSpec::clearCache() {
     static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<JPromise::javaobject>()>("clearCache");
     auto __result = method(_javaPart);

package/nitrogen/generated/android/c++/JHybridNitroImagePipelineSpec.hpp

@@ -58,6 +58,7 @@ namespace margelo::nitro::nitroimagepipeline {
     std::shared_ptr<Promise<void>> preLoadImage(const std::string& url) override;
     std::shared_ptr<Promise<void>> preLoadImages(const std::vector<std::string>& urls) override;
     std::shared_ptr<Promise<std::shared_ptr<margelo::nitro::image::HybridImageSpec>>> gaussianBlur(const std::shared_ptr<margelo::nitro::image::HybridImageSpec>& image, double radius) override;
+    void setMemoryCacheLimit(double bytes) override;
     std::shared_ptr<Promise<void>> clearCache() override;
 
   private:

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nitroimagepipeline/HybridNitroImagePipelineSpec.kt

@@ -47,6 +47,10 @@ abstract class HybridNitroImagePipelineSpec: HybridObject() {
   @Keep
   abstract fun gaussianBlur(image: com.margelo.nitro.image.HybridImageSpec, radius: Double): Promise<com.margelo.nitro.image.HybridImageSpec>
   
+  @DoNotStrip
+  @Keep
+  abstract fun setMemoryCacheLimit(bytes: Double): Unit
+  
   @DoNotStrip
   @Keep
   abstract fun clearCache(): Promise<Unit>

package/nitrogen/generated/ios/NitroImagePipeline-Swift-Cxx-Bridge.hpp

@@ -297,5 +297,14 @@ namespace margelo::nitro::nitroimagepipeline::bridge::swift {
   inline Result_std__shared_ptr_Promise_void___ create_Result_std__shared_ptr_Promise_void___(const std::exception_ptr& error) noexcept {
     return Result<std::shared_ptr<Promise<void>>>::withError(error);
   }
+  
+  // pragma MARK: Result<void>
+  using Result_void_ = Result<void>;
+  inline Result_void_ create_Result_void_() noexcept {
+    return Result<void>::withValue();
+  }
+  inline Result_void_ create_Result_void_(const std::exception_ptr& error) noexcept {
+    return Result<void>::withError(error);
+  }
 
 } // namespace margelo::nitro::nitroimagepipeline::bridge::swift

package/nitrogen/generated/ios/c++/HybridNitroImagePipelineSpecSwift.hpp

@@ -117,6 +117,12 @@ namespace margelo::nitro::nitroimagepipeline {
       auto __value = std::move(__result.value());
       return __value;
     }
+    inline void setMemoryCacheLimit(double bytes) override {
+      auto __result = _swiftPart.setMemoryCacheLimit(std::forward<decltype(bytes)>(bytes));
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+    }
     inline std::shared_ptr<Promise<void>> clearCache() override {
       auto __result = _swiftPart.clearCache();
       if (__result.hasError()) [[unlikely]] {

package/nitrogen/generated/ios/swift/HybridNitroImagePipelineSpec.swift

@@ -18,6 +18,7 @@ public protocol HybridNitroImagePipelineSpec_protocol: HybridObject {
   func preLoadImage(url: String) throws -> Promise<Void>
   func preLoadImages(urls: [String]) throws -> Promise<Void>
   func gaussianBlur(image: (any HybridImageSpec), radius: Double) throws -> Promise<(any HybridImageSpec)>
+  func setMemoryCacheLimit(bytes: Double) throws -> Void
   func clearCache() throws -> Promise<Void>
 }
 

package/nitrogen/generated/ios/swift/HybridNitroImagePipelineSpec_cxx.swift

@@ -211,6 +211,17 @@ open class HybridNitroImagePipelineSpec_cxx {
     }
   }
   
+  @inline(__always)
+  public final func setMemoryCacheLimit(bytes: Double) -> bridge.Result_void_ {
+    do {
+      try self.__implementation.setMemoryCacheLimit(bytes: bytes)
+      return bridge.create_Result_void_()
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_void_(__exceptionPtr)
+    }
+  }
+  
   @inline(__always)
   public final func clearCache() -> bridge.Result_std__shared_ptr_Promise_void___ {
     do {

package/nitrogen/generated/shared/c++/HybridNitroImagePipelineSpec.cpp

@@ -18,6 +18,7 @@ namespace margelo::nitro::nitroimagepipeline {
       prototype.registerHybridMethod("preLoadImage", &HybridNitroImagePipelineSpec::preLoadImage);
       prototype.registerHybridMethod("preLoadImages", &HybridNitroImagePipelineSpec::preLoadImages);
       prototype.registerHybridMethod("gaussianBlur", &HybridNitroImagePipelineSpec::gaussianBlur);
+      prototype.registerHybridMethod("setMemoryCacheLimit", &HybridNitroImagePipelineSpec::setMemoryCacheLimit);
       prototype.registerHybridMethod("clearCache", &HybridNitroImagePipelineSpec::clearCache);
     });
   }

package/nitrogen/generated/shared/c++/HybridNitroImagePipelineSpec.hpp

@@ -61,6 +61,7 @@ namespace margelo::nitro::nitroimagepipeline {
       virtual std::shared_ptr<Promise<void>> preLoadImage(const std::string& url) = 0;
       virtual std::shared_ptr<Promise<void>> preLoadImages(const std::vector<std::string>& urls) = 0;
       virtual std::shared_ptr<Promise<std::shared_ptr<margelo::nitro::image::HybridImageSpec>>> gaussianBlur(const std::shared_ptr<margelo::nitro::image::HybridImageSpec>& image, double radius) = 0;
+      virtual void setMemoryCacheLimit(double bytes) = 0;
       virtual std::shared_ptr<Promise<void>> clearCache() = 0;
 
     protected:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-image-pipeline",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "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",

package/src/specs/nitro-image-toolkit.nitro.ts

@@ -80,5 +80,16 @@ export interface NitroImagePipeline extends HybridObject<{
   gaussianBlur(image: Image, radius: number): Promise<Image>;
   // Future: brightness, saturation, tint, etc.
 
+  /**
+   * Caps the in-memory cache of decoded bitmaps at `bytes`, evicting
+   * least-recently-used entries immediately if it is currently larger. Pass
+   * `0` to disable in-memory caching entirely (the disk cache still works).
+   *
+   * Defaults: 128 MB on iOS, 25% of the app's memory class on Android. The
+   * cache trades RAM for instant re-display; lower it (or use
+   * `cache: 'disk'` per request) in memory-constrained apps.
+   */
+  setMemoryCacheLimit(bytes: number): void;
+
   clearCache(): Promise<void>;
 }