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

package/lib/module/NativePipelineImage.js

@@ -0,0 +1,67 @@
+"use strict";
+
+import { forwardRef } from 'react';
+import { NativeNitroImage } from 'react-native-nitro-image';
+import { cornerRadiusForStyle } from './resizeForStyle';
+import { usePipelineImageLoader } from './usePipelineImageLoader';
+
+/**
+ * The instance `<NativePipelineImage>` exposes through its `ref` — the
+ * underlying `NativeNitroImage` host view, with the usual native-view
+ * methods (`measure`, …).
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The fully native-driven variant of `PipelineImage`: after the first render
+ * there is **zero JS work per image**. The native view starts the request
+ * when it attaches to the window — at its own laid-out size, so nothing
+ * waits for an `onLayout` round trip — and cancels it (releasing the bitmap)
+ * when it detaches, which makes off-screen list cells free. Loads go through
+ * the same pipeline and caches as `useImage`/`preLoadImage`.
+ *
+ * Compared to `PipelineImage`:
+ * - No `onLoad`/`onError` callbacks — the loaded `Image` never crosses into
+ *   JS. Use `PipelineImage` (or `useImage`) when you need them.
+ * - The bitmap is loaded once at the size the view first has; if the view is
+ *   resized later, the bitmap scales with it instead of reloading.
+ * @example
+ * ```tsx
+ * <NativePipelineImage
+ *   url="https://example.com/photo.jpg"
+ *   style={{ width: 300, height: 200, borderRadius: 24 }}
+ *   blur={4}
+ * />
+ * ```
+ */
+export const NativePipelineImage = /*#__PURE__*/forwardRef(function NativePipelineImage({
+  url,
+  blur,
+  cornerRadius,
+  cache,
+  resize,
+  style,
+  ...viewProps
+}, ref) {
+  // Same precedence as PipelineImage: an explicit prop wins over style.
+  const effectiveCornerRadius = cornerRadius ?? cornerRadiusForStyle(style);
+  const loader = usePipelineImageLoader(url, {
+    blur,
+    cornerRadius: effectiveCornerRadius,
+    cache,
+    resize
+  });
+  return /*#__PURE__*/_jsx(NativeNitroImage
+  // Before the spread so a caller-provided recyclingKey wins.
+  , {
+    recyclingKey: url,
+    ...viewProps,
+    ref: ref,
+    style: style,
+    image: loader
+  });
+});
+
+// Reanimated and DevTools read the display name; the forwardRef wrapper
+// would otherwise report as anonymous.
+NativePipelineImage.displayName = 'NativePipelineImage';
+//# sourceMappingURL=NativePipelineImage.js.map

package/lib/module/NativePipelineImage.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["forwardRef","NativeNitroImage","cornerRadiusForStyle","usePipelineImageLoader","jsx","_jsx","NativePipelineImage","url","blur","cornerRadius","cache","resize","style","viewProps","ref","effectiveCornerRadius","loader","recyclingKey","image","displayName"],"sourceRoot":"../../src","sources":["NativePipelineImage.tsx"],"mappings":";;AAAA,SAA4BA,UAAU,QAAQ,OAAO;AAErD,SAASC,gBAAgB,QAAQ,0BAA0B;AAE3D,SAASC,oBAAoB,QAAQ,kBAAkB;AAMvD,SAASC,sBAAsB,QAAQ,0BAA0B;;AAKjE;AACA;AACA;AACA;AACA;AAJA,SAAAC,GAAA,IAAAC,IAAA;AAmCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,mBAAmB,gBAAGN,UAAU,CAG3C,SAASM,mBAAmBA,CAC5B;EAAEC,GAAG;EAAEC,IAAI;EAAEC,YAAY;EAAEC,KAAK;EAAEC,MAAM;EAAEC,KAAK;EAAE,GAAGC;AAAU,CAAC,EAC/DC,GAAG,EACH;EACA;EACA,MAAMC,qBAAqB,GAAGN,YAAY,IAAIP,oBAAoB,CAACU,KAAK,CAAC;EACzE,MAAMI,MAAM,GAAGb,sBAAsB,CAACI,GAAG,EAAE;IACzCC,IAAI;IACJC,YAAY,EAAEM,qBAAqB;IACnCL,KAAK;IACLC;EACF,CAAC,CAAC;EAEF,oBACEN,IAAA,CAACJ;EACC;EAAA;IACAgB,YAAY,EAAEV,GAAI;IAAA,GACdM,SAAS;IACbC,GAAG,EAAEA,GAAI;IACTF,KAAK,EAAEA,KAAM;IACbM,KAAK,EAAEF;EAAO,CACf,CAAC;AAEN,CAAC,CAAC;;AAEF;AACA;AACAV,mBAAmB,CAACa,WAAW,GAAG,qBAAqB","ignoreList":[]}

package/lib/module/index.js

@@ -1,7 +1,9 @@
 "use strict";
 
+export { NativePipelineImage } from './NativePipelineImage';
 export { NitroImagePipeline } from './NitroImagePipeline';
 export { PipelineImage } from './PipelineImage';
 export { cornerRadiusForStyle, resizeForLayout, resizeForStyle } from './resizeForStyle';
 export { useImage } from './useImage';
+export { usePipelineImageLoader } from './usePipelineImageLoader';
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["NitroImagePipeline","PipelineImage","cornerRadiusForStyle","resizeForLayout","resizeForStyle","useImage"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SAASA,kBAAkB,QAAQ,sBAAsB;AACzD,SACEC,aAAa,QAGR,iBAAiB;AACxB,SACEC,oBAAoB,EACpBC,eAAe,EACfC,cAAc,QACT,kBAAkB;AAOzB,SAASC,QAAQ,QAAQ,YAAY","ignoreList":[]}
+{"version":3,"names":["NativePipelineImage","NitroImagePipeline","PipelineImage","cornerRadiusForStyle","resizeForLayout","resizeForStyle","useImage","usePipelineImageLoader"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SACEA,mBAAmB,QAGd,uBAAuB;AAC9B,SAASC,kBAAkB,QAAQ,sBAAsB;AACzD,SACEC,aAAa,QAGR,iBAAiB;AACxB,SACEC,oBAAoB,EACpBC,eAAe,EACfC,cAAc,QACT,kBAAkB;AAQzB,SAASC,QAAQ,QAAQ,YAAY;AACrC,SAASC,sBAAsB,QAAQ,0BAA0B","ignoreList":[]}

package/lib/module/usePipelineImageLoader.js

@@ -0,0 +1,65 @@
+"use strict";
+
+import { useMemo } from 'react';
+import { NitroImagePipeline } from './NitroImagePipeline';
+/**
+ * Creates (and memoizes) an {@linkcode ImageLoader} for `url` to pass to
+ * `<NativeNitroImage image={...} />`. The view drives it entirely natively:
+ * the request starts when the view attaches — at the view's laid-out size,
+ * with no JS round trips — and is cancelled when it detaches. See
+ * {@linkcode NitroImagePipeline.createImageLoader}.
+ *
+ * `blur`/`cornerRadius` are in **points** (unlike `useImage`, where they are
+ * bitmap pixels); the screen scale is applied natively. Inline object
+ * literals are fine — options are compared by value, not identity.
+ */
+export function usePipelineImageLoader(url, options) {
+  // Split the options into primitives (like useImage does) so an inline
+  // literal — a new identity every render — doesn't recreate the loader;
+  // recreating it would re-trigger the native load.
+  const blur = options?.blur;
+  const cache = options?.cache;
+  const cornerRadius = options?.cornerRadius;
+  const isUniformRadius = typeof cornerRadius === 'number';
+  const uniformRadius = isUniformRadius ? cornerRadius : 0;
+  const hasCornerObject = !isUniformRadius && cornerRadius !== undefined;
+  const {
+    topLeft = 0,
+    topRight = 0,
+    bottomLeft = 0,
+    bottomRight = 0
+  } = isUniformRadius || cornerRadius === undefined ? {} : cornerRadius;
+  const resizeWidth = options?.resize?.width;
+  const resizeHeight = options?.resize?.height;
+  return useMemo(() => {
+    const cornerRadiusOption = isUniformRadius ? uniformRadius : hasCornerObject ? {
+      topLeft,
+      topRight,
+      bottomLeft,
+      bottomRight
+    } : undefined;
+    const stableOptions = {
+      blur,
+      cache,
+      cornerRadius: cornerRadiusOption,
+      resize: resizeWidth !== undefined && resizeHeight !== undefined ? {
+        width: resizeWidth,
+        height: resizeHeight
+      } : undefined
+    };
+    const loader = NitroImagePipeline.createImageLoader(url, stableOptions);
+    // `NativeNitroImage` needs a way to tell two loader instances apart when
+    // diffing its `image` prop; tag the loader with what it will load (the
+    // same convention react-native-nitro-image's own loaders use).
+    Object.defineProperty(loader, '__source', {
+      enumerable: true,
+      configurable: true,
+      value: {
+        url,
+        options: stableOptions
+      }
+    });
+    return loader;
+  }, [url, blur, cache, isUniformRadius, uniformRadius, hasCornerObject, topLeft, topRight, bottomLeft, bottomRight, resizeWidth, resizeHeight]);
+}
+//# sourceMappingURL=usePipelineImageLoader.js.map

package/lib/module/usePipelineImageLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useMemo","NitroImagePipeline","usePipelineImageLoader","url","options","blur","cache","cornerRadius","isUniformRadius","uniformRadius","hasCornerObject","undefined","topLeft","topRight","bottomLeft","bottomRight","resizeWidth","resize","width","resizeHeight","height","cornerRadiusOption","stableOptions","loader","createImageLoader","Object","defineProperty","enumerable","configurable","value"],"sourceRoot":"../../src","sources":["usePipelineImageLoader.ts"],"mappings":";;AAAA,SAASA,OAAO,QAAQ,OAAO;AAG/B,SAASC,kBAAkB,QAAQ,sBAAsB;AAMzD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,sBAAsBA,CACpCC,GAAW,EACXC,OAAqB,EACR;EACb;EACA;EACA;EACA,MAAMC,IAAI,GAAGD,OAAO,EAAEC,IAAI;EAC1B,MAAMC,KAAK,GAAGF,OAAO,EAAEE,KAAK;EAC5B,MAAMC,YAAY,GAAGH,OAAO,EAAEG,YAAY;EAC1C,MAAMC,eAAe,GAAG,OAAOD,YAAY,KAAK,QAAQ;EACxD,MAAME,aAAa,GAAGD,eAAe,GAAGD,YAAY,GAAG,CAAC;EACxD,MAAMG,eAAe,GAAG,CAACF,eAAe,IAAID,YAAY,KAAKI,SAAS;EACtE,MAAM;IACJC,OAAO,GAAG,CAAC;IACXC,QAAQ,GAAG,CAAC;IACZC,UAAU,GAAG,CAAC;IACdC,WAAW,GAAG;EAChB,CAAC,GAAGP,eAAe,IAAID,YAAY,KAAKI,SAAS,GAAG,CAAC,CAAC,GAAGJ,YAAY;EACrE,MAAMS,WAAW,GAAGZ,OAAO,EAAEa,MAAM,EAAEC,KAAK;EAC1C,MAAMC,YAAY,GAAGf,OAAO,EAAEa,MAAM,EAAEG,MAAM;EAE5C,OAAOpB,OAAO,CAAC,MAAM;IACnB,MAAMqB,kBAAoD,GAAGb,eAAe,GACxEC,aAAa,GACbC,eAAe,GACb;MAAEE,OAAO;MAAEC,QAAQ;MAAEC,UAAU;MAAEC;IAAY,CAAC,GAC9CJ,SAAS;IACf,MAAMW,aAA0B,GAAG;MACjCjB,IAAI;MACJC,KAAK;MACLC,YAAY,EAAEc,kBAAkB;MAChCJ,MAAM,EACJD,WAAW,KAAKL,SAAS,IAAIQ,YAAY,KAAKR,SAAS,GACnD;QAAEO,KAAK,EAAEF,WAAW;QAAEI,MAAM,EAAED;MAAa,CAAC,GAC5CR;IACR,CAAC;IACD,MAAMY,MAAM,GAAGtB,kBAAkB,CAACuB,iBAAiB,CAACrB,GAAG,EAAEmB,aAAa,CAAC;IACvE;IACA;IACA;IACAG,MAAM,CAACC,cAAc,CAACH,MAAM,EAAE,UAAU,EAAE;MACxCI,UAAU,EAAE,IAAI;MAChBC,YAAY,EAAE,IAAI;MAClBC,KAAK,EAAE;QAAE1B,GAAG;QAAEC,OAAO,EAAEkB;MAAc;IACvC,CAAC,CAAC;IACF,OAAOC,MAAM;EACf,CAAC,EAAE,CACDpB,GAAG,EACHE,IAAI,EACJC,KAAK,EACLE,eAAe,EACfC,aAAa,EACbC,eAAe,EACfE,OAAO,EACPC,QAAQ,EACRC,UAAU,EACVC,WAAW,EACXC,WAAW,EACXG,YAAY,CACb,CAAC;AACJ","ignoreList":[]}

package/lib/typescript/src/NativePipelineImage.d.ts

@@ -0,0 +1,66 @@
+import { type ComponentRef } from 'react';
+import type { HostComponent } from 'react-native';
+import { NativeNitroImage } from 'react-native-nitro-image';
+import type { CacheOption, CornerRadii, ResizeOptions } from './specs/nitro-image-toolkit.nitro';
+type ReactProps<T> = T extends HostComponent<infer P> ? P : never;
+type NativeImageProps = ReactProps<typeof NativeNitroImage>;
+/**
+ * The instance `<NativePipelineImage>` exposes through its `ref` — the
+ * underlying `NativeNitroImage` host view, with the usual native-view
+ * methods (`measure`, …).
+ */
+export type NativePipelineImageRef = ComponentRef<typeof NativeNitroImage>;
+export interface NativePipelineImageProps extends Omit<NativeImageProps, 'image'> {
+    /** URL of the image to load through the pipeline. */
+    url: string;
+    /**
+     * Gaussian blur sigma in **points** (density-independent), like
+     * `PipelineImage`. Applied natively with the screen scale.
+     * @default 0
+     */
+    blur?: number;
+    /**
+     * Corner radius in **points** — a single number or per-corner radii.
+     * When omitted, it's derived from `style`'s `borderRadius`-family
+     * properties instead — set this prop to override that.
+     * @default undefined (derived from `style`, or square corners if unset there)
+     */
+    cornerRadius?: number | CornerRadii;
+    cache?: CacheOption;
+    /**
+     * Target bitmap size in **pixels**, overriding the size the native side
+     * measures from the view. Rarely needed.
+     * @default undefined (measure the view natively)
+     */
+    resize?: ResizeOptions;
+}
+/**
+ * The fully native-driven variant of `PipelineImage`: after the first render
+ * there is **zero JS work per image**. The native view starts the request
+ * when it attaches to the window — at its own laid-out size, so nothing
+ * waits for an `onLayout` round trip — and cancels it (releasing the bitmap)
+ * when it detaches, which makes off-screen list cells free. Loads go through
+ * the same pipeline and caches as `useImage`/`preLoadImage`.
+ *
+ * Compared to `PipelineImage`:
+ * - No `onLoad`/`onError` callbacks — the loaded `Image` never crosses into
+ *   JS. Use `PipelineImage` (or `useImage`) when you need them.
+ * - The bitmap is loaded once at the size the view first has; if the view is
+ *   resized later, the bitmap scales with it instead of reloading.
+ * @example
+ * ```tsx
+ * <NativePipelineImage
+ *   url="https://example.com/photo.jpg"
+ *   style={{ width: 300, height: 200, borderRadius: 24 }}
+ *   blur={4}
+ * />
+ * ```
+ */
+export declare const NativePipelineImage: import("react").ForwardRefExoticComponent<NativePipelineImageProps & import("react").RefAttributes<import("react").Component<{
+    hybridRef?: import("react-native-nitro-modules").NitroViewWrappedCallback<((ref: import("react-native-nitro-modules").HybridView<import("react-native-nitro-image/lib/typescript/specs/ImageView.nitro").NativeNitroImageViewProps, import("react-native-nitro-image/lib/typescript/specs/ImageView.nitro").NativeNitroImageViewMethods>) => void) | undefined> | undefined;
+    image?: import("react-native-nitro-image").Image | import("react-native-nitro-image").ImageLoader;
+    resizeMode?: import("react-native-nitro-image/lib/typescript/specs/ImageView.nitro").ResizeMode;
+    recyclingKey?: string;
+} & import("react-native").ViewProps, {}, any> & import("react-native").ReactNativeElement>>;
+export {};
+//# sourceMappingURL=NativePipelineImage.d.ts.map

package/lib/typescript/src/NativePipelineImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativePipelineImage.d.ts","sourceRoot":"","sources":["../../../src/NativePipelineImage.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAc,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACd,MAAM,mCAAmC,CAAC;AAG3C,KAAK,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAClE,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,YAAY,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE3E,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,gBAAgB,EAChB,OAAO,CACR;IACC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB;;;;;4FA0B9B,CAAC"}

package/lib/typescript/src/index.d.ts

@@ -1,6 +1,8 @@
+export { NativePipelineImage, type NativePipelineImageProps, type NativePipelineImageRef, } from './NativePipelineImage';
 export { NitroImagePipeline } from './NitroImagePipeline';
 export { PipelineImage, type PipelineImageProps, type PipelineImageRef, } from './PipelineImage';
 export { cornerRadiusForStyle, resizeForLayout, resizeForStyle, } from './resizeForStyle';
-export type { CacheOption, CornerRadii, Options, ResizeOptions, } from './specs/nitro-image-toolkit.nitro';
+export type { CacheOption, CornerRadii, Options, ResizeOptions, ViewOptions, } from './specs/nitro-image-toolkit.nitro';
 export { useImage } from './useImage';
+export { usePipelineImageLoader } from './usePipelineImageLoader';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,WAAW,EACX,WAAW,EACX,OAAO,EACP,aAAa,GACd,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,WAAW,EACX,WAAW,EACX,OAAO,EACP,aAAa,EACb,WAAW,GACZ,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC"}

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

@@ -1,4 +1,4 @@
-import type { Image } from 'react-native-nitro-image';
+import type { Image, ImageLoader } from 'react-native-nitro-image';
 import type { HybridObject } from 'react-native-nitro-modules';
 export type CacheOption = 'memory' | 'disk' | 'none';
 /**
@@ -60,11 +60,54 @@ export type Options = {
      */
     resize?: ResizeOptions;
 };
+/**
+ * Options for {@linkcode NitroImagePipeline.createImageLoader}. Unlike
+ * {@linkcode Options} (used by `loadImage`, where values are bitmap pixels),
+ * `blur` and `cornerRadius` here are in **points** (density-independent):
+ * the loader runs inside a view and converts to pixels natively with the
+ * screen scale. The one exception is {@linkcode resize}, which stays an
+ * explicit **pixel** size like everywhere else in the library.
+ */
+export type ViewOptions = {
+    /**
+     * Gaussian blur sigma in **points**. Multiplied by the screen scale
+     * natively, so the same value looks the same on every device.
+     * @default 0 (no blur)
+     */
+    blur?: number;
+    cache?: CacheOption;
+    /**
+     * Corner radius in **points**, uniform or per-corner. Converted to pixels
+     * with the screen scale and baked into the bitmap at the display size.
+     * @default 0 (square corners)
+     */
+    cornerRadius?: number | CornerRadii;
+    /**
+     * Target bitmap size in **pixels**, overriding the size measured from the
+     * view. Rarely needed — without it the loader resizes to the view's
+     * laid-out size × screen scale, which is what you want in a UI.
+     * @default undefined (measure the view)
+     */
+    resize?: ResizeOptions;
+};
 export interface NitroImagePipeline extends HybridObject<{
     ios: 'swift';
     android: 'kotlin';
 }> {
     loadImage(url: string, options?: Options): Promise<Image>;
+    /**
+     * Creates an {@linkcode ImageLoader} for `url` that a `<NativeNitroImage>`
+     * view drives entirely natively: the request starts when the view attaches
+     * to the window — at the view's own laid-out size, with no JS round trips —
+     * and is cancelled (and the bitmap released) when it detaches, so
+     * off-screen list cells stop costing memory. Loads go through the same
+     * pipeline and caches as {@linkcode loadImage}/{@linkcode preLoadImage}.
+     *
+     * `options` are in **points** (see {@linkcode ViewOptions}); the loader
+     * applies the screen scale natively. If the view has no size yet when it
+     * attaches, the load waits for its first layout.
+     */
+    createImageLoader(url: string, options?: ViewOptions): ImageLoader;
     preLoadImage(url: string): Promise<void>;
     preLoadImages(urls: string[]): Promise<void>;
     /**
@@ -73,6 +116,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,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACnE,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;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;;;;OAKG;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;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACnE,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/lib/typescript/src/usePipelineImageLoader.d.ts

@@ -0,0 +1,15 @@
+import type { ImageLoader } from 'react-native-nitro-image';
+import type { ViewOptions } from './specs/nitro-image-toolkit.nitro';
+/**
+ * Creates (and memoizes) an {@linkcode ImageLoader} for `url` to pass to
+ * `<NativeNitroImage image={...} />`. The view drives it entirely natively:
+ * the request starts when the view attaches — at the view's laid-out size,
+ * with no JS round trips — and is cancelled when it detaches. See
+ * {@linkcode NitroImagePipeline.createImageLoader}.
+ *
+ * `blur`/`cornerRadius` are in **points** (unlike `useImage`, where they are
+ * bitmap pixels); the screen scale is applied natively. Inline object
+ * literals are fine — options are compared by value, not identity.
+ */
+export declare function usePipelineImageLoader(url: string, options?: ViewOptions): ImageLoader;
+//# sourceMappingURL=usePipelineImageLoader.d.ts.map

package/lib/typescript/src/usePipelineImageLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePipelineImageLoader.d.ts","sourceRoot":"","sources":["../../../src/usePipelineImageLoader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,KAAK,EAEV,WAAW,EACZ,MAAM,mCAAmC,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,WAAW,GACpB,WAAW,CA0Db"}

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

@@ -9,6 +9,8 @@
 
 // Forward declaration of `HybridImageSpec` to properly resolve imports.
 namespace margelo::nitro::image { class HybridImageSpec; }
+// Forward declaration of `HybridImageLoaderSpec` to properly resolve imports.
+namespace margelo::nitro::image { class HybridImageLoaderSpec; }
 // Forward declaration of `Options` to properly resolve imports.
 namespace margelo::nitro::nitroimagepipeline { struct Options; }
 // Forward declaration of `CacheOption` to properly resolve imports.
@@ -17,12 +19,16 @@ namespace margelo::nitro::nitroimagepipeline { enum class CacheOption; }
 namespace margelo::nitro::nitroimagepipeline { struct CornerRadii; }
 // Forward declaration of `ResizeOptions` to properly resolve imports.
 namespace margelo::nitro::nitroimagepipeline { struct ResizeOptions; }
+// Forward declaration of `ViewOptions` to properly resolve imports.
+namespace margelo::nitro::nitroimagepipeline { struct ViewOptions; }
 
 #include <memory>
 #include <NitroImage/HybridImageSpec.hpp>
 #include <NitroModules/Promise.hpp>
 #include <NitroModules/JPromise.hpp>
 #include <NitroImage/JHybridImageSpec.hpp>
+#include <NitroImage/HybridImageLoaderSpec.hpp>
+#include <NitroImage/JHybridImageLoaderSpec.hpp>
 #include <NitroModules/JUnit.hpp>
 #include <string>
 #include "Options.hpp"
@@ -36,6 +42,8 @@ namespace margelo::nitro::nitroimagepipeline { struct ResizeOptions; }
 #include "JCornerRadii.hpp"
 #include "ResizeOptions.hpp"
 #include "JResizeOptions.hpp"
+#include "ViewOptions.hpp"
+#include "JViewOptions.hpp"
 #include <vector>
 
 namespace margelo::nitro::nitroimagepipeline {
@@ -87,6 +95,11 @@ namespace margelo::nitro::nitroimagepipeline {
       return __promise;
     }();
   }
+  std::shared_ptr<margelo::nitro::image::HybridImageLoaderSpec> JHybridNitroImagePipelineSpec::createImageLoader(const std::string& url, const std::optional<ViewOptions>& options) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<margelo::nitro::image::JHybridImageLoaderSpec::JavaPart>(jni::alias_ref<jni::JString> /* url */, jni::alias_ref<JViewOptions> /* options */)>("createImageLoader");
+    auto __result = method(_javaPart, jni::make_jstring(url), options.has_value() ? JViewOptions::fromCpp(options.value()) : nullptr);
+    return __result->getJHybridImageLoaderSpec();
+  }
   std::shared_ptr<Promise<void>> JHybridNitroImagePipelineSpec::preLoadImage(const std::string& url) {
     static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<JPromise::javaobject>(jni::alias_ref<jni::JString> /* url */)>("preLoadImage");
     auto __result = method(_javaPart, jni::make_jstring(url));
@@ -142,6 +155,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

@@ -55,9 +55,11 @@ namespace margelo::nitro::nitroimagepipeline {
   public:
     // Methods
     std::shared_ptr<Promise<std::shared_ptr<margelo::nitro::image::HybridImageSpec>>> loadImage(const std::string& url, const std::optional<Options>& options) override;
+    std::shared_ptr<margelo::nitro::image::HybridImageLoaderSpec> createImageLoader(const std::string& url, const std::optional<ViewOptions>& options) override;
     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/c++/JViewOptions.hpp

@@ -0,0 +1,77 @@
+///
+/// JViewOptions.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#include <fbjni/fbjni.h>
+#include "ViewOptions.hpp"
+
+#include "CacheOption.hpp"
+#include "CornerRadii.hpp"
+#include "JCacheOption.hpp"
+#include "JCornerRadii.hpp"
+#include "JResizeOptions.hpp"
+#include "JVariant_Double_CornerRadii.hpp"
+#include "ResizeOptions.hpp"
+#include <optional>
+#include <variant>
+
+namespace margelo::nitro::nitroimagepipeline {
+
+  using namespace facebook;
+
+  /**
+   * The C++ JNI bridge between the C++ struct "ViewOptions" and the Kotlin data class "ViewOptions".
+   */
+  struct JViewOptions final: public jni::JavaClass<JViewOptions> {
+  public:
+    static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/nitroimagepipeline/ViewOptions;";
+
+  public:
+    /**
+     * Convert this Java/Kotlin-based struct to the C++ struct ViewOptions by copying all values to C++.
+     */
+    [[maybe_unused]]
+    [[nodiscard]]
+    ViewOptions toCpp() const {
+      static const auto clazz = javaClassStatic();
+      static const auto fieldBlur = clazz->getField<jni::JDouble>("blur");
+      jni::local_ref<jni::JDouble> blur = this->getFieldValue(fieldBlur);
+      static const auto fieldCache = clazz->getField<JCacheOption>("cache");
+      jni::local_ref<JCacheOption> cache = this->getFieldValue(fieldCache);
+      static const auto fieldCornerRadius = clazz->getField<JVariant_Double_CornerRadii>("cornerRadius");
+      jni::local_ref<JVariant_Double_CornerRadii> cornerRadius = this->getFieldValue(fieldCornerRadius);
+      static const auto fieldResize = clazz->getField<JResizeOptions>("resize");
+      jni::local_ref<JResizeOptions> resize = this->getFieldValue(fieldResize);
+      return ViewOptions(
+        blur != nullptr ? std::make_optional(blur->value()) : std::nullopt,
+        cache != nullptr ? std::make_optional(cache->toCpp()) : std::nullopt,
+        cornerRadius != nullptr ? std::make_optional(cornerRadius->toCpp()) : std::nullopt,
+        resize != nullptr ? std::make_optional(resize->toCpp()) : std::nullopt
+      );
+    }
+
+  public:
+    /**
+     * Create a Java/Kotlin-based struct by copying all values from the given C++ struct to Java.
+     */
+    [[maybe_unused]]
+    static jni::local_ref<JViewOptions::javaobject> fromCpp(const ViewOptions& value) {
+      using JSignature = JViewOptions(jni::alias_ref<jni::JDouble>, jni::alias_ref<JCacheOption>, jni::alias_ref<JVariant_Double_CornerRadii>, jni::alias_ref<JResizeOptions>);
+      static const auto clazz = javaClassStatic();
+      static const auto create = clazz->getStaticMethod<JSignature>("fromCpp");
+      return create(
+        clazz,
+        value.blur.has_value() ? jni::JDouble::valueOf(value.blur.value()) : nullptr,
+        value.cache.has_value() ? JCacheOption::fromCpp(value.cache.value()) : nullptr,
+        value.cornerRadius.has_value() ? JVariant_Double_CornerRadii::fromCpp(value.cornerRadius.value()) : nullptr,
+        value.resize.has_value() ? JResizeOptions::fromCpp(value.resize.value()) : nullptr
+      );
+    }
+  };
+
+} // namespace margelo::nitro::nitroimagepipeline

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

@@ -13,6 +13,7 @@ import com.facebook.proguard.annotations.DoNotStrip
 import dalvik.annotation.optimization.FastNative
 import com.margelo.nitro.image.HybridImageSpec
 import com.margelo.nitro.core.Promise
+import com.margelo.nitro.image.HybridImageLoaderSpec
 import com.margelo.nitro.core.HybridObject
 
 /**
@@ -35,6 +36,10 @@ abstract class HybridNitroImagePipelineSpec: HybridObject() {
   @Keep
   abstract fun loadImage(url: String, options: Options?): Promise<com.margelo.nitro.image.HybridImageSpec>
   
+  @DoNotStrip
+  @Keep
+  abstract fun createImageLoader(url: String, options: ViewOptions?): com.margelo.nitro.image.HybridImageLoaderSpec
+  
   @DoNotStrip
   @Keep
   abstract fun preLoadImage(url: String): Promise<Unit>
@@ -47,6 +52,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/android/kotlin/com/margelo/nitro/nitroimagepipeline/ViewOptions.kt

@@ -0,0 +1,66 @@
+///
+/// ViewOptions.kt
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+package com.margelo.nitro.nitroimagepipeline
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+import java.util.Objects
+
+
+/**
+ * Represents the JavaScript object/struct "ViewOptions".
+ */
+@DoNotStrip
+@Keep
+data class ViewOptions(
+  @DoNotStrip
+  @Keep
+  val blur: Double?,
+  @DoNotStrip
+  @Keep
+  val cache: CacheOption?,
+  @DoNotStrip
+  @Keep
+  val cornerRadius: Variant_Double_CornerRadii?,
+  @DoNotStrip
+  @Keep
+  val resize: ResizeOptions?
+) {
+  /* primary constructor */
+
+  override fun equals(other: Any?): Boolean {
+    if (this === other) return true
+    if (other !is ViewOptions) return false
+    return Objects.deepEquals(this.blur, other.blur)
+      && Objects.deepEquals(this.cache, other.cache)
+      && Objects.deepEquals(this.cornerRadius, other.cornerRadius)
+      && Objects.deepEquals(this.resize, other.resize)
+  }
+
+  override fun hashCode(): Int {
+    return arrayOf<Any?>(
+      blur,
+      cache,
+      cornerRadius,
+      resize
+    ).contentDeepHashCode()
+  }
+
+  companion object {
+    /**
+     * Constructor called from C++
+     */
+    @DoNotStrip
+    @Keep
+    @Suppress("unused")
+    @JvmStatic
+    private fun fromCpp(blur: Double?, cache: CacheOption?, cornerRadius: Variant_Double_CornerRadii?, resize: ResizeOptions?): ViewOptions {
+      return ViewOptions(blur, cache, cornerRadius, resize)
+    }
+  }
+}

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

@@ -41,6 +41,16 @@ namespace margelo::nitro::nitroimagepipeline::bridge::swift {
     };
   }
   
+  // pragma MARK: std::shared_ptr<margelo::nitro::image::HybridImageLoaderSpec>
+  std::shared_ptr<margelo::nitro::image::HybridImageLoaderSpec> create_std__shared_ptr_margelo__nitro__image__HybridImageLoaderSpec_(void* NON_NULL swiftUnsafePointer) noexcept {
+    // Implemented in NitroImage
+    return margelo::nitro::image::bridge::swift::create_std__shared_ptr_HybridImageLoaderSpec_(swiftUnsafePointer);
+  }
+  void* NON_NULL get_std__shared_ptr_margelo__nitro__image__HybridImageLoaderSpec_(std__shared_ptr_margelo__nitro__image__HybridImageLoaderSpec_ cppType) {
+    // Implemented in NitroImage
+    return margelo::nitro::image::bridge::swift::get_std__shared_ptr_HybridImageLoaderSpec_(cppType);
+  }
+  
   // pragma MARK: std::function<void()>
   Func_void create_Func_void(void* NON_NULL swiftClosureWrapper) noexcept {
     auto swiftClosure = NitroImagePipeline::Func_void::fromUnsafe(swiftClosureWrapper);