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

package/src/resolveImageSource.ts

@@ -0,0 +1,83 @@
+import { Image as RNImage } from 'react-native';
+
+/**
+ * What the pipeline can load: a URL string, or the id a `require()`d image
+ * asset evaluates to.
+ *
+ * As a string, `url` is passed to the native loader as-is. Accepted forms:
+ *
+ * - `https://` / `http://` — fetched over the network and cached on disk.
+ * - `file://` URLs and plain absolute paths (`/var/…/photo.jpg`) — read from
+ *   the file system. The result is cached in memory only; there is nothing
+ *   to gain from copying a local file into the disk cache.
+ * - Android also accepts `content://` URIs and, from a release build's
+ *   resources, a bare drawable name — which is what `require()` resolves to
+ *   there. iOS resolves `require()` to a `file://` URL into the app bundle.
+ *
+ * A `require('./photo.png')` is resolved with `Image.resolveAssetSource`, so
+ * it works the same in debug (streamed from Metro) and release (bundled).
+ */
+export type ImageSource = string | number;
+
+/**
+ * Turns an {@linkcode ImageSource} into the URL string the native pipeline
+ * loads: strings pass through unchanged, a `require()`d asset is resolved via
+ * `Image.resolveAssetSource` (the scale-matched variant, like `<Image>`).
+ *
+ * The components and hooks call this for you; use it when calling
+ * `NitroImagePipeline.loadImage`/`preLoadImage` directly with a `require()`.
+ * @throws If `source` is a number that is not a registered asset.
+ * @example
+ * ```ts
+ * const image = await NitroImagePipeline.loadImage(
+ *   resolveImageUrl(require('./photo.png')),
+ *   { blur: 4 },
+ * );
+ * ```
+ */
+export function resolveImageUrl(source: ImageSource): string {
+  if (typeof source === 'string') {
+    return source;
+  }
+  const resolved = RNImage.resolveAssetSource(source);
+  if (resolved == null) {
+    throw new Error(`Not a registered image asset: require() id ${source}`);
+  }
+  return resolved.uri;
+}
+
+/**
+ * A URL no loader can resolve, standing in for a `require()` id that is not
+ * a registered asset. Its scheme has no fetcher on either platform, so the
+ * request fails at load time — the same way a missing file does — instead of
+ * throwing from a component's render.
+ */
+export const UNREGISTERED_ASSET_URL = 'unregistered-asset://';
+
+/**
+ * {@linkcode resolveImageUrl} for code that runs during render: an
+ * unregistered `require()` id yields {@linkcode UNREGISTERED_ASSET_URL} (and
+ * a warning in development) rather than throwing.
+ */
+export function resolveImageUrlOrFallback(source: ImageSource): string {
+  try {
+    return resolveImageUrl(source);
+  } catch (error) {
+    if (__DEV__) {
+      console.warn(
+        `[react-native-nitro-image-pipeline] ${(error as Error).message}`,
+      );
+    }
+    return UNREGISTERED_ASSET_URL;
+  }
+}
+
+/**
+ * A stable, per-source `recyclingKey` for `<NativeNitroImage>`: the URL
+ * itself for strings, and a tag derived from the asset id for a `require()`
+ * (resolving it would cost an asset-registry lookup per render for nothing
+ * more than a distinct key).
+ */
+export function recyclingKeyFor(source: ImageSource): string {
+  return typeof source === 'string' ? source : `asset:${source}`;
+}

package/src/specs/nitro-image-toolkit.nitro.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';
@@ -65,11 +65,67 @@ 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';
 }> {
+  /**
+   * Loads `url` through the pipeline. Besides `http(s)://`, `url` may be a
+   * `file://` URL or a plain absolute path (read from the file system, cached
+   * in memory only), a `data:` URL, or — on Android — a `content://` URI or
+   * the bare resource name a `require()` resolves to in a release build. Use
+   * `resolveImageUrl(require('./photo.png'))` to pass a bundled asset.
+   */
   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;
+  /**
+   * Warms the disk cache with the download for `url`, without decoding it.
+   * Local sources (`file://`, paths, resources) have no download to warm it
+   * with and are a no-op.
+   */
   preLoadImage(url: string): Promise<void>;
   preLoadImages(urls: string[]): Promise<void>;
   /**

package/src/useImage.ts

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState } from 'react';
 import type { Image } from 'react-native-nitro-image';
 
 import { NitroImagePipeline } from './NitroImagePipeline';
+import { type ImageSource, resolveImageUrl } from './resolveImageSource';
 import type {
   CacheOption,
   CornerRadii,
@@ -26,11 +27,12 @@ type Result =
     };
 
 /**
- * A hook to asynchronously load an image from the
- * given {@linkcode AsyncImageSource} into memory.
+ * A hook to asynchronously load an image from `url` through the pipeline
+ * into memory.
  * @example
  * ```ts
- * const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
+ * const { image, error } = useImage({ url: 'https://example.com/photo.jpg' });
+ * const { image: logo } = useImage({ url: require('./logo.png') });
  * ```
  */
 export function useImage({
@@ -41,7 +43,11 @@ export function useImage({
   cache,
   enabled = true,
 }: {
-  url: string;
+  /**
+   * The image to load: a URL string (`https://`, `file://`, an absolute path)
+   * or a `require()`d asset — see {@linkcode ImageSource}.
+   */
+  url: ImageSource;
   /**
    * Gaussian blur strength, as the standard deviation (sigma) of the blur in
    * source-image pixels (of the resized bitmap when `resize` is set). Matches
@@ -103,17 +109,22 @@ export function useImage({
     if (enabled) {
       (async () => {
         try {
-          const result = await NitroImagePipeline.loadImage(url, {
-            blur,
-            cornerRadius: isUniformRadius
-              ? uniformRadius
-              : { topLeft, topRight, bottomLeft, bottomRight },
-            resize:
-              resizeWidth > 0 && resizeHeight > 0
-                ? { width: resizeWidth, height: resizeHeight }
-                : undefined,
-            cache,
-          });
+          // Resolved inside the try so an unregistered `require()` id
+          // surfaces as the error state instead of throwing from the effect.
+          const result = await NitroImagePipeline.loadImage(
+            resolveImageUrl(url),
+            {
+              blur,
+              cornerRadius: isUniformRadius
+                ? uniformRadius
+                : { topLeft, topRight, bottomLeft, bottomRight },
+              resize:
+                resizeWidth > 0 && resizeHeight > 0
+                  ? { width: resizeWidth, height: resizeHeight }
+                  : undefined,
+              cache,
+            },
+          );
 
           if (!cancelled) {
             setImage({ image: result, error: undefined });

package/src/usePipelineImageLoader.ts

@@ -0,0 +1,90 @@
+import { useMemo } from 'react';
+import type { ImageLoader } from 'react-native-nitro-image';
+
+import { NitroImagePipeline } from './NitroImagePipeline';
+import {
+  type ImageSource,
+  resolveImageUrlOrFallback,
+} from './resolveImageSource';
+import type {
+  CornerRadii,
+  ViewOptions,
+} from './specs/nitro-image-toolkit.nitro';
+
+/**
+ * Creates (and memoizes) an {@linkcode ImageLoader} for `source` — a URL
+ * string or a `require()`d asset, see {@linkcode ImageSource} — 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(
+  source: ImageSource,
+  options?: ViewOptions,
+): ImageLoader {
+  // 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(() => {
+    // Runs during render, so an unregistered `require()` id must not throw:
+    // it becomes a URL the native loader fails on at load time instead.
+    const url = resolveImageUrlOrFallback(source);
+    const cornerRadiusOption: number | CornerRadii | undefined = isUniformRadius
+      ? uniformRadius
+      : hasCornerObject
+        ? { topLeft, topRight, bottomLeft, bottomRight }
+        : undefined;
+    const stableOptions: ViewOptions = {
+      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;
+  }, [
+    source,
+    blur,
+    cache,
+    isUniformRadius,
+    uniformRadius,
+    hasCornerObject,
+    topLeft,
+    topRight,
+    bottomLeft,
+    bottomRight,
+    resizeWidth,
+    resizeHeight,
+  ]);
+}