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

package/README.md

@@ -306,6 +306,20 @@ 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.
@@ -320,12 +334,23 @@ The pipeline is set up so RAM scales with what you display, not with what you do
   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.
+- **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
 

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

@@ -157,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

@@ -228,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.2",
+  "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>;
 }