react-native-fast-image 8.6.43 → 8.8.0

package/README.md

@@ -112,6 +112,8 @@ If you use Proguard you will need to add these lines to `android/app/proguard-ru
 
 Source for the remote image to load.
 
+When `source` changes, the image that's showing stays until the new one has loaded, as with `<img>` in browsers and React Native's `Image` on iOS. In views that get reused for other content, such as rows in FlashList or recyclerlistview, set `recyclingKey` so a reused row doesn't show the previous row's image.
+
 ---
 
 ### `source.uri?: string`
@@ -147,10 +149,21 @@ Indicates the load order priority of an image. Images with `FastImage.priority.h
 ### `defaultSource?: number`
 
 - An asset loaded with `require(...)`.
+- Shown while the first image loads, and if an image fails to load. When `source` changes, the previous image shows while the new one loads instead (see `source` and `recyclingKey`).
 - Note that like the built-in `Image` implementation, on Android `defaultSource` does not work in debug mode. This is due to the fact that assets are sent from the dev server, but RN's functions only know how to load it from `res`.
 
 ---
 
+### `recyclingKey?: string`
+
+For views that get reused for other content, such as rows in FlashList or recyclerlistview. Set it to something that identifies the content, e.g. the item's id. When it changes, the image is cleared right away (to `defaultSource`, or blank) instead of staying until the new one has loaded. Unlike changing `key`, this keeps the view, which is what list recycling is for.
+
+```jsx
+<FastImage recyclingKey={item.id} source={{ uri: item.imageUrl }} />
+```
+
+---
+
 ### `resizeMode?: enum`
 
 - `FastImage.resizeMode.contain` - Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or less than the corresponding dimension of the view (minus padding).
@@ -213,7 +226,7 @@ If supplied, changes the color of all the non-transparent pixels to the given co
 
 ## Static Methods
 
-### `FastImage.preload: (source[]) => void`
+### `FastImage.preload: (source[]) => Promise<result[]>`
 
 Preload images to display later. e.g.
 
@@ -230,6 +243,13 @@ FastImage.preload([
 ])
 ```
 
+It resolves when all the images have loaded or failed, with a result for each source, in order: `{ uri, ok, width, height, error }`. `width` and `height` are the image's size (as in `onLoad`), which is also a way to find an image's size without showing it. A few sources load at a time (3, or `SDWebImagePrefetcher`'s `maxConcurrentPrefetchCount` on iOS), so a long list doesn't hold up the images the app is showing, and at low priority unless the source sets `priority`. It never rejects:
+
+```js
+const results = await FastImage.preload(sources)
+const failed = results.filter((result) => !result.ok)
+```
+
 ### `FastImage.clearMemoryCache: () => Promise<void>`
 
 Clear all images from memory cache.

package/android/src/main/java/com/dylanvann/fastimage/FastImageRequestListener.java

@@ -19,19 +19,28 @@ public class FastImageRequestListener implements RequestListener<Drawable> {
     static final String REACT_ON_LOAD_END_EVENT = "onFastImageLoadEnd";
     private final String key;
     private final FastImageSource source;
+    // Whether the request shows the previous image as a thumbnail meanwhile.
+    private final boolean thumbnail;
+    // False when loading the image that's showing again at a new size: the
+    // view shows it at its old size if that fails.
+    private final boolean events;
 
-    FastImageRequestListener(String key, FastImageSource source) {
+    FastImageRequestListener(String key, FastImageSource source, boolean thumbnail, boolean events) {
         this.key = key;
         this.source = source;
+        this.thumbnail = thumbnail;
+        this.events = events;
     }
 
     @Override
     public boolean onLoadFailed(@androidx.annotation.Nullable GlideException e, Object model, Target<Drawable> target, boolean isFirstResource) {
+        if (!events) return false;
         FastImageOkHttpProgressGlideModule.forget(key);
         if (!(target instanceof ImageViewTarget)) {
             return false;
         }
         FastImageViewWithUrl view = (FastImageViewWithUrl) ((ImageViewTarget) target).getView();
+        view.onImageFailed(thumbnail);
         FastImageEvents.send(view, REACT_ON_ERROR_EVENT);
         FastImageEvents.send(view, REACT_ON_LOAD_END_EVENT);
         return false;
@@ -43,11 +52,13 @@ public class FastImageRequestListener implements RequestListener<Drawable> {
             return false;
         }
         final FastImageViewWithUrl view = (FastImageViewWithUrl) ((ImageViewTarget) target).getView();
+        view.onImageLoaded();
         if (resource instanceof GifDrawable) {
             // Play the GIF as many times as the file says, as iOS does. Glide
             // loops every GIF forever by default (#651).
             ((GifDrawable) resource).setLoopCount(GifDrawable.LOOP_INTRINSIC);
         }
+        if (!events) return false;
         boolean local = !(model instanceof GlideUrl);
         int[] size = FastImageSourceSize.get(resource, model, local,
                 dataSource == DataSource.RESOURCE_DISK_CACHE);

package/android/src/main/java/com/dylanvann/fastimage/FastImageViewManager.java

@@ -84,6 +84,11 @@ class FastImageViewManager extends SimpleViewManager<FastImageViewWithUrl> imple
         }
     }
 
+    @ReactProp(name = "recyclingKey")
+    public void setRecyclingKey(FastImageViewWithUrl view, @Nullable String recyclingKey) {
+        view.setRecyclingKey(recyclingKey);
+    }
+
     @ReactProp(name = "resizeMode")
     public void setResizeMode(FastImageViewWithUrl view, String resizeMode) {
         final FastImageViewWithUrl.ScaleType scaleType = FastImageViewConverter.getScaleType(resizeMode);

package/android/src/main/java/com/dylanvann/fastimage/FastImageViewModule.java

@@ -1,24 +1,34 @@
 package com.dylanvann.fastimage;
 
 import android.app.Activity;
-import android.util.Log;
+import android.graphics.drawable.Drawable;
 
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 
 import com.bumptech.glide.Glide;
-import com.bumptech.glide.load.model.GlideUrl;
+import com.bumptech.glide.Priority;
+import com.bumptech.glide.load.DataSource;
+import com.bumptech.glide.load.engine.GlideException;
+import com.bumptech.glide.request.RequestListener;
+import com.bumptech.glide.request.RequestOptions;
+import com.bumptech.glide.request.target.Target;
+import com.facebook.react.bridge.Arguments;
 import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
 import com.facebook.react.bridge.ReactContextBaseJavaModule;
 import com.facebook.react.bridge.ReactMethod;
 import com.facebook.react.bridge.ReadableArray;
 import com.facebook.react.bridge.ReadableMap;
-import com.facebook.react.views.imagehelper.ImageSource;
+import com.facebook.react.bridge.UiThreadUtil;
+import com.facebook.react.bridge.WritableArray;
+import com.facebook.react.bridge.WritableMap;
+
+import java.util.ArrayDeque;
 
 class FastImageViewModule extends ReactContextBaseJavaModule {
 
     private static final String REACT_CLASS = "FastImageView";
-    private static final String TAG = "FastImage";
 
     FastImageViewModule(ReactApplicationContext reactContext) {
         super(reactContext);
@@ -30,41 +40,141 @@ class FastImageViewModule extends ReactContextBaseJavaModule {
         return REACT_CLASS;
     }
 
+    // At most this many preloaded sources load at a time, across all preload
+    // calls (the same as SDWebImagePrefetcher's default on iOS), so a long
+    // list doesn't queue hundreds of requests ahead of the images the app is
+    // showing (Glide's executors run requests in order within a priority).
+    private static final int PRELOAD_LIMIT = 3;
+    // Preloads waiting to start, in the order they were added, and the number
+    // loading. Only used on the UI thread (Glide calls its listeners there).
+    private static final ArrayDeque<Runnable> pendingPreloads = new ArrayDeque<>();
+    private static int preloadsInFlight = 0;
+
+    // Starts pending preloads while there's room. A listener calls it again,
+    // sometimes from inside run() (Glide reports a memory-cached image
+    // synchronously from preload()). That's fine: the counters are shared and
+    // updated before each run(), so the inner call starts what fits, and the
+    // outer loop sees the updated counters when it checks again.
+    private static void startPendingPreloads() {
+        while (preloadsInFlight < PRELOAD_LIMIT && !pendingPreloads.isEmpty()) {
+            preloadsInFlight++;
+            pendingPreloads.poll().run();
+        }
+    }
+
+    // Resolves with a result per source, in order, once all have loaded or
+    // failed: { ok, width, height } or { ok: false, error }. Never rejects.
     @ReactMethod
-    public void preload(final ReadableArray sources) {
-        final Activity activity = getCurrentActivity();
-        if (activity == null) return;
-        activity.runOnUiThread(new Runnable() {
+    public void preload(final ReadableArray sources, final Promise promise) {
+        final ReactApplicationContext context = getReactApplicationContext();
+        UiThreadUtil.runOnUiThread(new Runnable() {
             @Override
             public void run() {
-                for (int i = 0; i < sources.size(); i++) {
-                    final ReadableMap source = sources.getMap(i);
-                    // Skip sources without a uri (Glide throws on an empty url).
-                    // preload has no way to report errors, so log them.
+                final int count = sources.size();
+                final WritableMap[] results = new WritableMap[count];
+                // Sources of this call still to finish. It starts at the
+                // number of sources, so the promise can't resolve before
+                // they've all been added.
+                final int[] remaining = {count};
+                final Runnable finishOne = new Runnable() {
+                    @Override
+                    public void run() {
+                        if (--remaining[0] > 0) return;
+                        WritableArray array = Arguments.createArray();
+                        for (WritableMap result : results) array.pushMap(result);
+                        promise.resolve(array);
+                    }
+                };
+                for (int i = 0; i < count; i++) {
+                    final int index = i;
+                    final ReadableMap source = sources.isNull(i) ? null : sources.getMap(i);
+                    // Glide throws on an empty url. Invalid sources fail
+                    // without taking a slot.
                     if (!FastImageViewConverter.hasUri(source)) {
-                        Log.w(TAG, "preload: skipping a source without a uri");
+                        results[i] = failure("Invalid source: no uri");
+                        finishOne.run();
                         continue;
                     }
-                    final FastImageSource imageSource = FastImageViewConverter.getImageSource(activity, source);
-                    // Also skip a uri that can't be resolved (e.g. a relative path),
-                    // which resolves to an empty one. The view reports it as an error.
+                    final FastImageSource imageSource = FastImageViewConverter.getImageSource(context, source);
+                    // A uri that can't be resolved (e.g. a relative path) resolves
+                    // to an empty one.
                     if (imageSource.getUri().toString().isEmpty()) {
-                        Log.w(TAG, "preload: skipping a uri that can't be resolved: " + source.getString("uri"));
+                        results[i] = failure("Invalid source: can't resolve " + source.getString("uri"));
+                        finishOne.run();
                         continue;
                     }
+                    RequestOptions options = FastImageViewConverter.getOptions(context, imageSource, source);
+                    // Low priority unless the source sets one, as on iOS (the
+                    // prefetcher's options), so the images the app shows load
+                    // first.
+                    final RequestOptions preloadOptions = source.hasKey("priority") && !source.isNull("priority")
+                            ? options
+                            : options.priority(Priority.LOW);
+                    pendingPreloads.add(new Runnable() {
+                        @Override
+                        public void run() {
+                            Glide
+                                    .with(context)
+                                    // Load it the way the view does, so local images
+                                    // (file://, content://, asset:/) work too.
+                                    .load(imageSource.getSourceForLoad())
+                                    .apply(preloadOptions)
+                                    .listener(new RequestListener<Drawable>() {
+                                        @Override
+                                        public boolean onLoadFailed(@Nullable GlideException e, Object model, Target<Drawable> target, boolean isFirstResource) {
+                                            results[index] = failure(errorMessage(e));
+                                            preloadsInFlight--;
+                                            finishOne.run();
+                                            startPendingPreloads();
+                                            return false;
+                                        }
 
-                    Glide
-                            .with(activity.getApplicationContext())
-                            // Load it the way the view does, so local images
-                            // (file://, content://, asset:/) work too.
-                            .load(imageSource.getSourceForLoad())
-                            .apply(FastImageViewConverter.getOptions(activity, imageSource, source))
-                            .preload();
+                                        @Override
+                                        public boolean onResourceReady(Drawable resource, Object model, Target<Drawable> target, DataSource dataSource, boolean isFirstResource) {
+                                            // Preloaded at its original size, so this is
+                                            // the image's own size.
+                                            WritableMap result = Arguments.createMap();
+                                            result.putBoolean("ok", true);
+                                            result.putInt("width", resource.getIntrinsicWidth());
+                                            result.putInt("height", resource.getIntrinsicHeight());
+                                            results[index] = result;
+                                            preloadsInFlight--;
+                                            finishOne.run();
+                                            startPendingPreloads();
+                                            return false;
+                                        }
+                                    })
+                                    .preload();
+                        }
+                    });
                 }
+                if (count == 0) {
+                    promise.resolve(Arguments.createArray());
+                    return;
+                }
+                startPendingPreloads();
             }
         });
     }
 
+    private static WritableMap failure(String error) {
+        WritableMap result = Arguments.createMap();
+        result.putBoolean("ok", false);
+        result.putString("error", error);
+        return result;
+    }
+
+    // The first root cause's message, e.g. "Not Found, status code: 404".
+    private static String errorMessage(@Nullable GlideException e) {
+        if (e != null) {
+            for (Throwable cause : e.getRootCauses()) {
+                if (cause.getMessage() != null) return cause.getMessage();
+            }
+            if (e.getMessage() != null) return e.getMessage();
+        }
+        return "Failed to load the image";
+    }
+
     @ReactMethod
     public void clearMemoryCache(final Promise promise) {
         final Activity activity = getCurrentActivity();

package/android/src/main/java/com/dylanvann/fastimage/FastImageViewWithUrl.java

@@ -15,6 +15,8 @@ import com.bumptech.glide.RequestBuilder;
 import com.bumptech.glide.RequestManager;
 import com.bumptech.glide.load.model.GlideUrl;
 import com.bumptech.glide.request.Request;
+import com.bumptech.glide.request.target.DrawableImageViewTarget;
+import com.bumptech.glide.request.target.SizeReadyCallback;
 import com.facebook.react.bridge.ReadableMap;
 import com.facebook.react.bridge.WritableMap;
 import com.facebook.react.bridge.WritableNativeMap;
@@ -67,6 +69,143 @@ class FastImageViewWithUrl extends AppCompatImageView {
         mNeedsReload = true;
     }
 
+    // The request for the image the view shows once it has loaded, and the one
+    // loading. A new source starts with the shown one as a thumbnail, from the
+    // cache only, so the image stays until the new one has loaded instead of
+    // flashing blank (#747). This is Glide's safe way to do that: the previous
+    // bitmap can't be kept in the view itself, since Glide reuses it once its
+    // request is cleared.
+    @Nullable
+    private RequestBuilder<Drawable> mShownRequest;
+    @Nullable
+    private RequestBuilder<Drawable> mLoadingRequest;
+    // Counts loads, to tell whether a posted update is for the current one.
+    private int mLoadCount = 0;
+    // The size Glide loaded the shown image at, and is loading the loading
+    // one at (0 until it has one).
+    private int mShownWidth = 0;
+    private int mShownHeight = 0;
+    private int mLoadingWidth = 0;
+    private int mLoadingHeight = 0;
+    private boolean mResizeReloadPosted = false;
+
+    @Nullable
+    private String mRecyclingKey;
+
+    // When it changes, the next image doesn't replace the current one: the
+    // view clears first (for views reused for other content, like list rows).
+    void setRecyclingKey(@Nullable String recyclingKey) {
+        if (recyclingKey == null ? mRecyclingKey == null : recyclingKey.equals(mRecyclingKey)) return;
+        boolean changed = mRecyclingKey != null;
+        mRecyclingKey = recyclingKey;
+        if (changed) {
+            // No thumbnail of the current image, so Glide clears the view to
+            // defaultSource (or nothing) while the next one loads. Reload even
+            // if the source is the same.
+            mShownRequest = null;
+            mNeedsReload = true;
+        }
+    }
+
+    // The loading image loaded (FastImageRequestListener).
+    void onImageLoaded() {
+        mShownRequest = mLoadingRequest;
+        mShownWidth = mLoadingWidth;
+        mShownHeight = mLoadingHeight;
+        reloadIfResized();
+    }
+
+    // Glide crops or scales the image to the view's size when it loads, so if
+    // the view's size changes after that, load it again at the new size.
+    // Otherwise a view that gets taller shows a zoomed-in slice of it (#983).
+    @Override
+    protected void onSizeChanged(int w, int h, int oldw, int oldh) {
+        super.onSizeChanged(w, h, oldw, oldh);
+        reloadIfResized();
+    }
+
+    private void reloadIfResized() {
+        if (mResizeReloadPosted || !isResized()) return;
+        mResizeReloadPosted = true;
+        // After layout (once per frame), and not from within Glide's callback.
+        post(new Runnable() {
+            @Override
+            public void run() {
+                mResizeReloadPosted = false;
+                if (isResized()) reloadForSize();
+            }
+        });
+    }
+
+    // Whether the image loaded, at a size the view doesn't have now.
+    private boolean isResized() {
+        int width = getWidth() - getPaddingLeft() - getPaddingRight();
+        int height = getHeight() - getPaddingTop() - getPaddingBottom();
+        return requestManager != null && !mNeedsReload
+                && mShownRequest != null && mShownRequest == mLoadingRequest
+                && mShownWidth > 0 && mShownHeight > 0 && width > 0 && height > 0
+                && (width != mShownWidth || height != mShownHeight);
+    }
+
+    // The same image at the view's new size. Meanwhile, and if that fails, the
+    // view shows the image at its old size, from the cache. It's the image
+    // that's already showing, so this sends no events.
+    @SuppressLint("CheckResult")
+    private void reloadForSize() {
+        RequestBuilder<Drawable> shown = mShownRequest;
+        RequestBuilder<Drawable> current = fromCache(shown);
+        mLoadCount++;
+        clearView(requestManager);
+        into(shown, shown.clone()
+                .thumbnail(current)
+                .error(current.clone())
+                .listener(new FastImageRequestListener(null, null, true, false)));
+    }
+
+    // The shown image, from the cache only (never loaded again), at the size
+    // it was loaded at: the key it's in Glide's memory cache under.
+    @SuppressLint("CheckResult")
+    private RequestBuilder<Drawable> fromCache(RequestBuilder<Drawable> shown) {
+        RequestBuilder<Drawable> request = shown.clone().onlyRetrieveFromCache(true);
+        if (mShownWidth > 0 && mShownHeight > 0) request = request.override(mShownWidth, mShownHeight);
+        return request;
+    }
+
+    // Starts loading the request (built by builder), recording the size Glide
+    // loads it at. The size callback is added first, so it has the size by
+    // the time the image loads, even from the memory cache.
+    private void into(RequestBuilder<Drawable> request, RequestBuilder<Drawable> builder) {
+        final int load = mLoadCount;
+        mLoadingRequest = request;
+        mLoadingWidth = 0;
+        mLoadingHeight = 0;
+        DrawableImageViewTarget target = new DrawableImageViewTarget(this);
+        target.getSize(new SizeReadyCallback() {
+            @Override
+            public void onSizeReady(int width, int height) {
+                if (load != mLoadCount) return;
+                mLoadingWidth = width;
+                mLoadingHeight = height;
+            }
+        });
+        builder.into(target);
+    }
+
+    // The loading image failed (FastImageRequestListener). Glide shows
+    // defaultSource then, but not over a thumbnail: show it here, as iOS does.
+    void onImageFailed(boolean hadThumbnail) {
+        mShownRequest = null;
+        if (!hadThumbnail) return;
+        final int load = mLoadCount;
+        // Not from within Glide's callback.
+        post(new Runnable() {
+            @Override
+            public void run() {
+                if (load == mLoadCount) setImageDrawable(mDefaultSource);
+            }
+        });
+    }
+
     @SuppressLint("CheckResult")
     public void onAfterUpdate(
             @Nonnull FastImageViewManager manager,
@@ -77,6 +216,10 @@ class FastImageViewWithUrl extends AppCompatImageView {
         // Only reload for changes that affect the request (source,
         // defaultSource, resizeMode), not for every prop update.
         mNeedsReload = false;
+        mLoadCount++;
+        RequestBuilder<Drawable> shownRequest = mShownRequest;
+        mShownRequest = null;
+        mLoadingRequest = null;
 
         // Nothing to show.
         if (mSource == null && mDefaultSource == null) {
@@ -162,11 +305,17 @@ class FastImageViewWithUrl extends AppCompatImageView {
                             // What into() would apply for the scale type, with
                             // the size capture.
                             .apply(FastImageSourceSize.scaleTypeOptions(getScaleType(), capture));
+            RequestBuilder<Drawable> request = builder.clone();
+
+            boolean thumbnail = shownRequest != null && model != null;
+            if (thumbnail) {
+                builder = builder.thumbnail(fromCache(shownRequest));
+            }
 
             if (key != null)
-                builder.listener(new FastImageRequestListener(key, imageSource));
+                builder.listener(new FastImageRequestListener(key, imageSource, thumbnail, true));
 
-            builder.into(this);
+            into(request, builder);
         }
     }
 

package/dist/index.cjs.js

@@ -129,7 +129,16 @@ const FastImage = FastImageComponent;
 FastImage.resizeMode = resizeMode;
 FastImage.cacheControl = cacheControl;
 FastImage.priority = priority;
-FastImage.preload = (sources) => react_native.NativeModules.FastImageView.preload(sources);
+FastImage.preload = (sources) => Promise.resolve(react_native.NativeModules.FastImageView.preload(sources.map((s) => s || {}))).then((results) => sources.map((source, i) => {
+	var _results$i;
+	return {
+		uri: source ? source.uri : void 0,
+		...(_results$i = results === null || results === void 0 ? void 0 : results[i]) !== null && _results$i !== void 0 ? _results$i : {
+			ok: false,
+			error: "No result"
+		}
+	};
+}));
 FastImage.clearMemoryCache = () => react_native.NativeModules.FastImageView.clearMemoryCache();
 FastImage.clearDiskCache = () => react_native.NativeModules.FastImageView.clearDiskCache();
 const styles = react_native.StyleSheet.create({

package/dist/index.cjs.js.flow

@@ -43,7 +43,17 @@ export type ResizeModes = $Values<ResizeMode>
 export type Priorities = $Values<Priority>
 export type CacheControls = $Values<CacheControl>
 
-export type PreloadFn = (sources: Array<FastImageSource>) => void
+export type PreloadResult = {|
+    uri?: string,
+    ok: boolean,
+    width?: number,
+    height?: number,
+    error?: string,
+|}
+
+export type PreloadFn = (
+    sources: Array<FastImageSource>,
+) => Promise<Array<PreloadResult>>
 export type FastImageSource = {
     uri?: string,
     headers?: Object,
@@ -65,6 +75,7 @@ export type FastImageProps = $ReadOnly<{|
     tintColor?: number | string,
     resizeMode?: ?ResizeModes,
     fallback?: ?boolean,
+    recyclingKey?: ?string,
     testID?: ?string,
 |}>
 

package/dist/index.d.ts

@@ -60,6 +60,15 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
     defaultSource?: ImageRequireSource;
     resizeMode?: ResizeMode;
     fallback?: boolean;
+    /**
+     * When `source` changes, the image showing stays until the new one has
+     * loaded. For views that get reused for other content, such as rows in
+     * FlashList or recyclerlistview, set this to something that identifies the
+     * content (e.g. the item's id): when it changes, the image is cleared
+     * right away instead, so a reused row doesn't show the previous row's
+     * image. Unlike changing `key`, the view is kept.
+     */
+    recyclingKey?: string | null;
     onLoadStart?(): void;
     onProgress?(event: OnProgressEvent): void;
     onLoad?(event: OnLoadEvent): void;
@@ -93,11 +102,18 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      */
     children?: React.ReactNode;
 }
+export interface PreloadResult {
+    uri?: string;
+    ok: boolean;
+    width?: number;
+    height?: number;
+    error?: string;
+}
 export interface FastImageStaticProperties {
     resizeMode: typeof resizeMode;
     priority: typeof priority;
     cacheControl: typeof cacheControl;
-    preload: (sources: Source[]) => void;
+    preload: (sources: Source[]) => Promise<PreloadResult[]>;
     clearMemoryCache: () => Promise<void>;
     clearDiskCache: () => Promise<void>;
 }

package/dist/index.js

@@ -106,7 +106,16 @@ const FastImage = FastImageComponent;
 FastImage.resizeMode = resizeMode;
 FastImage.cacheControl = cacheControl;
 FastImage.priority = priority;
-FastImage.preload = (sources) => NativeModules.FastImageView.preload(sources);
+FastImage.preload = (sources) => Promise.resolve(NativeModules.FastImageView.preload(sources.map((s) => s || {}))).then((results) => sources.map((source, i) => {
+	var _results$i;
+	return {
+		uri: source ? source.uri : void 0,
+		...(_results$i = results === null || results === void 0 ? void 0 : results[i]) !== null && _results$i !== void 0 ? _results$i : {
+			ok: false,
+			error: "No result"
+		}
+	};
+}));
 FastImage.clearMemoryCache = () => NativeModules.FastImageView.clearMemoryCache();
 FastImage.clearDiskCache = () => NativeModules.FastImageView.clearDiskCache();
 const styles = StyleSheet.create({

package/dist/index.js.flow

@@ -43,7 +43,17 @@ export type ResizeModes = $Values<ResizeMode>
 export type Priorities = $Values<Priority>
 export type CacheControls = $Values<CacheControl>
 
-export type PreloadFn = (sources: Array<FastImageSource>) => void
+export type PreloadResult = {|
+    uri?: string,
+    ok: boolean,
+    width?: number,
+    height?: number,
+    error?: string,
+|}
+
+export type PreloadFn = (
+    sources: Array<FastImageSource>,
+) => Promise<Array<PreloadResult>>
 export type FastImageSource = {
     uri?: string,
     headers?: Object,
@@ -65,6 +75,7 @@ export type FastImageProps = $ReadOnly<{|
     tintColor?: number | string,
     resizeMode?: ?ResizeModes,
     fallback?: ?boolean,
+    recyclingKey?: ?string,
     testID?: ?string,
 |}>
 

package/ios/FastImage/FFFastImageSource.h

@@ -21,6 +21,8 @@ typedef NS_ENUM(NSInteger, FFFCacheControl) {
 @property (nonatomic) NSURL* url;
 // priority for image request
 @property (nonatomic) FFFPriority priority;
+// whether the source set a priority (preload is low priority otherwise)
+@property (nonatomic) BOOL hasPriority;
 // headers for the image request
 @property (nonatomic) NSDictionary *headers;
 // cache control mode

package/ios/FastImage/FFFastImageView.h

@@ -19,6 +19,9 @@
 @property (nonatomic, strong) FFFastImageSource *source;
 @property (nonatomic, strong) UIImage *defaultSource;
 @property (nonatomic, strong) UIColor *imageColor;
+// When it changes, the next image doesn't replace the current one: the view
+// clears first (for views reused for other content, like list rows).
+@property (nonatomic, copy) NSString *recyclingKey;
 
 @end
 

package/ios/FastImage/FFFastImageView.m

@@ -20,6 +20,9 @@
 @property(nonatomic, assign) BOOL retriedAfterBackground;
 // Waits for the app to be active again, to restart a load.
 @property(nonatomic, strong) id activeObserver;
+// Whether the view shows an image that loaded (not defaultSource or nothing).
+// A new source then keeps it until the new image has loaded (see reloadImage).
+@property(nonatomic, assign) BOOL showsLoadedImage;
 
 @end
 
@@ -186,6 +189,21 @@ static CFTimeInterval FFFEnteredBackgroundAt = 0;
     }
 }
 
+- (void) setRecyclingKey: (NSString*)recyclingKey {
+    if (_recyclingKey == recyclingKey || [_recyclingKey isEqualToString: recyclingKey]) {
+        return;
+    }
+    BOOL changed = _recyclingKey != nil;
+    _recyclingKey = [recyclingKey copy];
+    if (changed) {
+        // The view shows other content now: don't keep the current image
+        // while the next one loads (reloadImage clears it), even if the
+        // source is the same.
+        self.showsLoadedImage = NO;
+        _needsReload = YES;
+    }
+}
+
 - (void) setDefaultSource: (UIImage*)defaultSource {
     if (_defaultSource != defaultSource) {
         _defaultSource = defaultSource;
@@ -217,6 +235,7 @@ static CFTimeInterval FFFEnteredBackgroundAt = 0;
             if (!image) {
                 // Not decodable: fail like a remote image, showing defaultSource.
                 [self setImage: _defaultSource];
+                self.showsLoadedImage = NO;
                 self.hasErrored = YES;
                 if (self.onFastImageError) {
                     self.onFastImageError(@{});
@@ -234,6 +253,7 @@ static CFTimeInterval FFFEnteredBackgroundAt = 0;
                 });
             }
             self.hasCompleted = YES;
+            self.showsLoadedImage = YES;
             [self sendOnLoad: image];
 
             if (self.onFastImageLoadEnd) {
@@ -270,6 +290,14 @@ static CFTimeInterval FFFEnteredBackgroundAt = 0;
                 break;
         }
 
+        // Keep showing the loaded image until the new one has loaded, instead
+        // of clearing it to defaultSource (or nothing) while it loads, which
+        // flashed (#747). defaultSource shows if the new image fails. As React
+        // Native's Image does; a `key` that changes starts from blank instead.
+        if (self.showsLoadedImage) {
+            options |= SDWebImageDelayPlaceholder;
+        }
+
         if (self.onFastImageLoadStart) {
             self.onFastImageLoadStart(@{});
             self.hasSentOnLoadStart = YES;
@@ -284,6 +312,7 @@ static CFTimeInterval FFFEnteredBackgroundAt = 0;
         [self downloadImage: _source options: options context: context];
     } else if (_defaultSource) {
         [self setImage: _defaultSource];
+        self.showsLoadedImage = NO;
     }
 }
 
@@ -338,6 +367,8 @@ static CFTimeInterval FFFEnteredBackgroundAt = 0;
                     return;
                 }
                 if (error) {
+                    // SDWebImage shows the placeholder (defaultSource or nothing).
+                    weakSelf.showsLoadedImage = NO;
                     weakSelf.hasErrored = YES;
                     if (weakSelf.onFastImageError) {
                         weakSelf.onFastImageError(@{});
@@ -347,6 +378,7 @@ static CFTimeInterval FFFEnteredBackgroundAt = 0;
                     }
                 } else {
                     weakSelf.hasCompleted = YES;
+                    weakSelf.showsLoadedImage = YES;
                     [weakSelf sendOnLoad: image];
                     if (weakSelf.onFastImageLoadEnd) {
                         weakSelf.onFastImageLoadEnd(@{});

package/ios/FastImage/FFFastImageViewManager.m

@@ -1,9 +1,9 @@
 #import "FFFastImageViewManager.h"
 #import "FFFastImageView.h"
-#import <React/RCTLog.h>
 
 #import <SDWebImage/SDImageCache.h>
 #import <SDWebImage/SDWebImageManager.h>
+#import <SDWebImage/SDWebImageError.h>
 #import <SDWebImage/SDWebImagePrefetcher.h>
 
 @implementation FFFastImageViewManager
@@ -17,6 +17,7 @@ RCT_EXPORT_MODULE(FastImageView)
 RCT_EXPORT_VIEW_PROPERTY(source, FFFastImageSource)
 RCT_EXPORT_VIEW_PROPERTY(defaultSource, UIImage)
 RCT_EXPORT_VIEW_PROPERTY(resizeMode, RCTResizeMode)
+RCT_EXPORT_VIEW_PROPERTY(recyclingKey, NSString)
 RCT_EXPORT_VIEW_PROPERTY(onFastImageLoadStart, RCTDirectEventBlock)
 RCT_EXPORT_VIEW_PROPERTY(onFastImageProgress, RCTDirectEventBlock)
 RCT_EXPORT_VIEW_PROPERTY(onFastImageError, RCTDirectEventBlock)
@@ -24,36 +25,119 @@ RCT_EXPORT_VIEW_PROPERTY(onFastImageLoad, RCTDirectEventBlock)
 RCT_EXPORT_VIEW_PROPERTY(onFastImageLoadEnd, RCTDirectEventBlock)
 RCT_REMAP_VIEW_PROPERTY(tintColor, imageColor, UIColor)
 
-RCT_EXPORT_METHOD(preload:(nonnull NSArray<FFFastImageSource *> *)sources)
+// The error's description, with the HTTP status code when there is one.
+static NSString *FFFErrorMessage(NSError *error)
 {
-    SDWebImagePrefetcher *prefetcher = [SDWebImagePrefetcher sharedImagePrefetcher];
-    NSMutableArray *urls = [NSMutableArray arrayWithCapacity:sources.count];
+    NSNumber *statusCode = error.userInfo[SDWebImageErrorDownloadStatusCodeKey];
+    if (statusCode) {
+        return [NSString stringWithFormat:@"%@, status code: %@", error.localizedDescription, statusCode];
+    }
+    return error.localizedDescription ?: @"Failed to load the image";
+}
 
-    [sources enumerateObjectsUsingBlock:^(FFFastImageSource * _Nonnull source, NSUInteger idx, BOOL * _Nonnull stop) {
-        // Skip sources without a url (an empty, missing or null uri). NSArray can't
-        // hold nil, so adding one throws and crashes the app.
-        if (!source.url) {
-            // preload has no way to report errors, so log it.
-            RCTLogWarn(@"FastImage.preload: skipping a source without a valid uri");
-            return;
+// Preloads waiting to start, in the order they were added, and the number
+// loading, across all preload calls. Like SDWebImagePrefetcher, at most
+// maxConcurrentPrefetchCount load at a time, so a long list doesn't queue
+// hundreds of operations ahead of the images the app is showing. Only used on
+// the main queue (SDWebImageManager calls its completion blocks there).
+static NSMutableArray<dispatch_block_t> *FFFPendingPreloads;
+static NSUInteger FFFPreloadsInFlight;
+
+static NSUInteger FFFPreloadLimit(void)
+{
+    NSUInteger limit = [SDWebImagePrefetcher sharedImagePrefetcher].maxConcurrentPrefetchCount;
+    return MAX(limit, (NSUInteger)1);
+}
+
+// Starts pending preloads while there's room. A completion block calls it
+// again, sometimes from inside start() (a memory cache hit completes
+// synchronously on the main queue). That's fine: the counters are shared and
+// updated before each start(), so the inner call starts what fits, and the
+// outer loop sees the updated counters when it checks again.
+static void FFFStartPendingPreloads(void)
+{
+    while (FFFPreloadsInFlight < FFFPreloadLimit() && FFFPendingPreloads.count > 0) {
+        dispatch_block_t start = FFFPendingPreloads.firstObject;
+        [FFFPendingPreloads removeObjectAtIndex:0];
+        FFFPreloadsInFlight++;
+        start();
+    }
+}
+
+// Resolves with a result per source, in order, once all have loaded or failed:
+// { ok, width, height } or { ok: false, error }. Never rejects.
+RCT_EXPORT_METHOD(preload:(nonnull NSArray<FFFastImageSource *> *)sources
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(__unused RCTPromiseRejectBlock)reject)
+{
+    // This runs on the UIManager queue; the queue state is only touched on
+    // the main queue.
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if (!FFFPendingPreloads) {
+            FFFPendingPreloads = [NSMutableArray array];
         }
-        if (source.headers.count == 0) {
-            [urls addObject:source.url];
+        NSMutableArray *results = [NSMutableArray arrayWithCapacity:sources.count];
+        // Sources of this call still to finish. It starts at the number of
+        // sources, so the promise can't resolve before they've all been added.
+        __block NSUInteger remaining = sources.count;
+        void (^finishOne)(void) = ^{
+            if (--remaining == 0) {
+                resolve(results);
+            }
+        };
+        // With the prefetcher's options (low priority), but one source at a
+        // time (not SDWebImagePrefetcher), to get each source's result and to
+        // send its headers with its own request only.
+        SDWebImageOptions prefetcherOptions = [SDWebImagePrefetcher sharedImagePrefetcher].options;
+
+        [sources enumerateObjectsUsingBlock:^(FFFastImageSource * _Nonnull source, NSUInteger idx, BOOL * _Nonnull stop) {
+            if (!source.url) {
+                // An empty, missing or null uri (JS sends null sources as {}).
+                // It fails without taking a slot.
+                [results addObject:@{@"ok": @NO, @"error": @"Invalid source: no uri"}];
+                finishOne();
+                return;
+            }
+            [results addObject:[NSNull null]];
+            // A source's own priority replaces the prefetcher's, as on Android.
+            SDWebImageOptions options = prefetcherOptions;
+            if (source.hasPriority) {
+                options &= ~(SDWebImageLowPriority | SDWebImageHighPriority);
+                if (source.priority == FFFPriorityLow) {
+                    options |= SDWebImageLowPriority;
+                } else if (source.priority == FFFPriorityHigh) {
+                    options |= SDWebImageHighPriority;
+                }
+            }
+            [FFFPendingPreloads addObject:[^{
+                // Once per slot: SDWebImage calls this once with finished set
+                // (a progressive load calls it more, without).
+                __block BOOL done = NO;
+                [[SDWebImageManager sharedManager] loadImageWithURL:source.url
+                                                            options:options
+                                                            context:@{SDWebImageContextDownloadRequestModifier: source.requestModifier}
+                                                           progress:nil
+                                                          completed:^(UIImage *image, NSData *data, NSError *error, SDImageCacheType cacheType, BOOL finished, NSURL *imageURL) {
+                    if (!finished || done) {
+                        return;
+                    }
+                    done = YES;
+                    results[idx] = image
+                        ? @{@"ok": @YES, @"width": @(image.size.width), @"height": @(image.size.height)}
+                        : @{@"ok": @NO, @"error": FFFErrorMessage(error)};
+                    FFFPreloadsInFlight--;
+                    finishOne();
+                    FFFStartPendingPreloads();
+                }];
+            } copy]];
+        }];
+
+        if (sources.count == 0) {
+            resolve(results);
             return;
         }
-        // Send the headers with this source's request only (setting them on
-        // the shared downloader sent them with every later request). The
-        // prefetcher can't take headers per request in SDWebImage 5.11 (its
-        // context is shared by all prefetches), so load it the way the
-        // prefetcher does, with the same options.
-        [[SDWebImageManager sharedManager] loadImageWithURL:source.url
-                                                    options:prefetcher.options
-                                                    context:@{SDWebImageContextDownloadRequestModifier: source.requestModifier}
-                                                   progress:nil
-                                                  completed:^(UIImage *image, NSData *data, NSError *error, SDImageCacheType cacheType, BOOL finished, NSURL *imageURL) {}];
-    }];
-
-    [prefetcher prefetchURLs:urls];
+        FFFStartPendingPreloads();
+    });
 }
 
 RCT_EXPORT_METHOD(clearMemoryCache:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)

package/ios/FastImage/RCTConvert+FFFastImage.m

@@ -45,6 +45,8 @@ RCT_ENUM_CONVERTER(FFFCacheControl, (@{
     }
     
     FFFastImageSource *imageSource = [[FFFastImageSource alloc] initWithURL:uri priority:priority headers:headers cacheControl:cacheControl];
+    id priorityJSON = json[@"priority"];
+    imageSource.hasPriority = priorityJSON && priorityJSON != (id)kCFNull;
     
     return imageSource;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-native-fast-image",
-    "version": "8.6.43",
+    "version": "8.8.0",
     "description": "🚩 FastImage, performant React Native image component.",
     "keywords": [
         "cache",