react-native-fast-image 8.22.0 → 8.24.0

package/README.md

@@ -105,6 +105,25 @@ When `source` changes, the image that's showing stays until the new one has load
 
 Remote url to load the image from. e.g. `'https://facebook.github.io/react/img/logo_og.png'`.
 
+#### Photo library images (iOS)
+
+A photo library url (`ph://<localIdentifier>`, as camera roll libraries give) loads when the app has SDWebImagePhotosPlugin. Add it to the app's `ios/Podfile` and run `pod install`:
+
+```ruby
+pod 'SDWebImagePhotosPlugin'
+```
+
+With Expo, add it with [expo-build-properties](https://docs.expo.dev/versions/latest/sdk/build-properties/):
+
+```json
+[
+    "expo-build-properties",
+    { "ios": { "extraPods": [{ "name": "SDWebImagePhotosPlugin" }] } }
+]
+```
+
+The app needs access to the photo library, which it has if it got the url from there. A photo library image is decoded at about the view's size, since photos are large and usually shown small; `onLoad` still reports the photo's own size. `FastImage.preload` of a `ph://` source loads the full-size photo (there's no view to size it for), which doesn't make a view's smaller copy load faster, so preloading photo library images usually isn't worth it. Without the plugin, a `ph://` source fails with `onError`, saying so. `assets-library://` urls aren't supported. On Android, photo pickers give `content://` urls, which load as they are.
+
 ---
 
 ### `source.headers?: object`
@@ -239,7 +258,7 @@ iOS only. Decodes a large image at about the size it's shown at, instead of at f
 
 Use it when you show images much larger than their views and can't get them at the right size, e.g. user uploads or other people's URLs in a list. If you control the images, serve them at the size they're shown instead (resized on your server or by an image CDN), which also saves bandwidth.
 
-Decoding a smaller copy can take a little longer, so use it where the memory matters. Needs SDWebImage 5.19.7 or later. On Android images are already decoded at about the view's size.
+Decoding a smaller copy can take a little longer, so use it where the memory matters. Needs SDWebImage 5.19.7 or later. Photo library images are always decoded this way. On Android images are already decoded at about the view's size.
 
 ---
 
@@ -486,6 +505,16 @@ On Android, if your app has its own `AppGlideModule` (see [Are you using Glide a
 
 Images with `cache: 'web'` are kept in their own HTTP cache instead, up to 50 MB on each platform, which these limits don't change.
 
+## Web
+
+With [react-native-web](https://necolas.github.io/react-native-web/), FastImage shows images with the web's `Image`. Bundlers pick the web version through the package's `browser` field, or the `.web.js` files next to the native ones.
+
+Support is minimal:
+
+- Props that work: `source` (a `uri`, or a `require()`d image), `defaultSource`, `resizeMode`, `tintColor`, `blurRadius`, `style`, children, `onLoadStart`, `onLoad`, `onError`, `onLoadEnd`, and View props such as `testID`, accessibility props, `onLayout` and `pointerEvents`.
+- Ignored: `source.headers` (a browser can't send them for an image), `source.priority`, `source.cache`, `source.cacheKey`, `source.memoryCache`, `recyclingKey`, `loop`, `imageRendering`, `paused`, `transition`, `downsample`, `fallback` and `onProgress`.
+- `FastImage.preload` loads the images into the browser's cache and resolves with a result per source. `clearMemoryCache`, `clearDiskCache` and `configureCache` resolve without doing anything (the browser manages its cache), and `getCachePath` and `writeToCache` resolve with `{ ok: false, error: 'Not supported on the web' }`.
+
 ## Troubleshooting
 
 If you have any problems using this library try the steps in [troubleshooting](docs/troubleshooting.md) and see if they fix it.

package/dist/constants.d.ts

@@ -0,0 +1,16 @@
+export declare const resizeMode: {
+    readonly contain: 'contain';
+    readonly cover: 'cover';
+    readonly stretch: 'stretch';
+    readonly center: 'center';
+};
+export declare const priority: {
+    readonly low: 'low';
+    readonly normal: 'normal';
+    readonly high: 'high';
+};
+export declare const cacheControl: {
+    readonly immutable: 'immutable';
+    readonly web: 'web';
+    readonly cacheOnly: 'cacheOnly';
+};

package/dist/index.cjs.js

@@ -27,7 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let react = require("react");
 react = __toESM(react);
 let react_native = require("react-native");
-//#region src/index.tsx
+//#region src/constants.ts
 const resizeMode = {
 	contain: "contain",
 	cover: "cover",
@@ -44,6 +44,8 @@ const cacheControl = {
 	web: "web",
 	cacheOnly: "cacheOnly"
 };
+//#endregion
+//#region src/index.tsx
 const resolveDefaultSource = (defaultSource) => {
 	if (!defaultSource) return null;
 	if (react_native.Platform.OS === "android") {

package/dist/index.cjs.web.js

@@ -0,0 +1,193 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let react = require("react");
+react = __toESM(react);
+let react_native = require("react-native");
+//#region src/constants.ts
+const resizeMode = {
+	contain: "contain",
+	cover: "cover",
+	stretch: "stretch",
+	center: "center"
+};
+const priority = {
+	low: "low",
+	normal: "normal",
+	high: "high"
+};
+const cacheControl = {
+	immutable: "immutable",
+	web: "web",
+	cacheOnly: "cacheOnly"
+};
+//#endregion
+//#region src/index.web.tsx
+const notSupported = {
+	ok: false,
+	error: "Not supported on the web"
+};
+function FastImageBase({ source, defaultSource, tintColor, blurRadius, onLoadStart, onLoad, onError, onLoadEnd, style, children, resizeMode: mode = "cover", forwardedRef, onLayout, pointerEvents, fallback: _fallback, recyclingKey: _recyclingKey, loop: _loop, imageRendering: _imageRendering, paused: _paused, transition: _transition, downsample: _downsample, onProgress: _onProgress, ...props }) {
+	const result = (0, react.useRef)(void 0);
+	const sent = (0, react.useRef)(Promise.resolve());
+	const image = (0, react.useRef)(null);
+	const uri = typeof source === "object" && source ? source.uri : void 0;
+	const webSource = typeof source === "number" ? source : uri ? { uri } : void 0;
+	return /* @__PURE__ */ react.default.createElement(react_native.View, {
+		style: [styles.container, style],
+		onLayout,
+		pointerEvents,
+		ref: forwardedRef
+	}, /* @__PURE__ */ react.default.createElement(react_native.Image, {
+		...props,
+		style: styles.image,
+		source: webSource,
+		defaultSource,
+		resizeMode: mode,
+		tintColor,
+		blurRadius,
+		ref: image,
+		onLoadStart,
+		onLoad: (event) => {
+			var _event$nativeEvent;
+			sent.current = loadedSize(event === null || event === void 0 || (_event$nativeEvent = event.nativeEvent) === null || _event$nativeEvent === void 0 ? void 0 : _event$nativeEvent.target, image.current, uri).then(({ width, height }) => {
+				result.current = {
+					ok: true,
+					width,
+					height
+				};
+				onLoad === null || onLoad === void 0 || onLoad({ nativeEvent: {
+					width,
+					height
+				} });
+			});
+		},
+		onError: (event) => {
+			var _event$nativeEvent$er, _event$nativeEvent2;
+			const error = String((_event$nativeEvent$er = event === null || event === void 0 || (_event$nativeEvent2 = event.nativeEvent) === null || _event$nativeEvent2 === void 0 ? void 0 : _event$nativeEvent2.error) !== null && _event$nativeEvent$er !== void 0 ? _event$nativeEvent$er : "Failed to load the image");
+			result.current = {
+				ok: false,
+				error
+			};
+			sent.current = Promise.resolve();
+			onError === null || onError === void 0 || onError({ nativeEvent: { error } });
+		},
+		onLoadEnd: () => {
+			sent.current.then(() => {
+				var _result$current;
+				onLoadEnd === null || onLoadEnd === void 0 || onLoadEnd((_result$current = result.current) !== null && _result$current !== void 0 ? _result$current : {
+					ok: false,
+					error: "Failed to load the image"
+				});
+				result.current = void 0;
+			});
+		}
+	}), children);
+}
+const FastImageMemo = (0, react.memo)(FastImageBase);
+const FastImageComponent = (0, react.forwardRef)((props, ref) => /* @__PURE__ */ react.default.createElement(FastImageMemo, {
+	forwardedRef: ref,
+	...props
+}));
+FastImageComponent.displayName = "FastImage";
+async function loadedSize(loaded, view, uri) {
+	var _view$querySelector;
+	if (loaded === null || loaded === void 0 ? void 0 : loaded.naturalWidth) return {
+		width: loaded.naturalWidth,
+		height: loaded.naturalHeight
+	};
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	const shown = view === null || view === void 0 || (_view$querySelector = view.querySelector) === null || _view$querySelector === void 0 ? void 0 : _view$querySelector.call(view, "img");
+	if (shown === null || shown === void 0 ? void 0 : shown.naturalWidth) return {
+		width: shown.naturalWidth,
+		height: shown.naturalHeight
+	};
+	const src = uri !== null && uri !== void 0 ? uri : shown === null || shown === void 0 ? void 0 : shown.src;
+	return src ? getSize(src) : {
+		width: 0,
+		height: 0
+	};
+}
+function getSize(uri) {
+	return new Promise((resolve) => {
+		react_native.Image.getSize(uri, (width, height) => resolve({
+			width,
+			height
+		}), () => resolve({
+			width: 0,
+			height: 0
+		}));
+	});
+}
+const FastImage = FastImageComponent;
+FastImage.resizeMode = resizeMode;
+FastImage.cacheControl = cacheControl;
+FastImage.priority = priority;
+FastImage.preload = (sources) => Promise.all(sources.map((source) => {
+	const uri = source ? source.uri : void 0;
+	if (typeof uri !== "string" || !uri) return Promise.resolve({
+		ok: false,
+		error: "Invalid source: no uri",
+		uri
+	});
+	return react_native.Image.prefetch(uri).then(() => getSize(uri).then((size) => ({
+		ok: true,
+		uri,
+		...size
+	})), () => ({
+		ok: false,
+		error: "Failed to load the image",
+		uri
+	}));
+}));
+FastImage.clearMemoryCache = () => Promise.resolve();
+FastImage.clearDiskCache = () => Promise.resolve();
+FastImage.configureCache = () => Promise.resolve({});
+FastImage.writeToCache = () => Promise.resolve(notSupported);
+FastImage.getCachePath = () => Promise.resolve(notSupported);
+const styles = react_native.StyleSheet.create({
+	container: { overflow: "hidden" },
+	image: {
+		position: "absolute",
+		top: 0,
+		left: 0,
+		width: "100%",
+		height: "100%"
+	}
+});
+const FastImageWithRef = FastImageComponent;
+const FastImageBackground = (0, react.forwardRef)(({ style, imageStyle, imageRef, children, ...props }, ref) => /* @__PURE__ */ react.default.createElement(react_native.View, {
+	style,
+	ref
+}, /* @__PURE__ */ react.default.createElement(FastImageWithRef, {
+	...props,
+	style: [react_native.StyleSheet.absoluteFill, imageStyle],
+	ref: imageRef
+}), children));
+FastImageBackground.displayName = "FastImageBackground";
+//#endregion
+exports.FastImageBackground = FastImageBackground;
+exports.default = FastImage;

package/dist/index.cjs.web.js.flow

@@ -0,0 +1,154 @@
+// @flow
+
+import type { ViewProps } from 'react-native/Libraries/Components/View/ViewPropTypes'
+import type { SyntheticEvent } from 'react-native/Libraries/Types/CoreEventTypes'
+
+export type OnLoadEvent = SyntheticEvent<
+    $ReadOnly<{
+        width: number,
+        height: number,
+        // The view's React tag. Missing on Android with the legacy architecture.
+        // TODO: make it required once the New Architecture is the minimum.
+        target?: number,
+    }>,
+>
+
+export type OnErrorEvent = SyntheticEvent<
+    $ReadOnly<{|
+        error: string,
+    |}>,
+>
+
+export type OnProgressEvent = SyntheticEvent<
+    $ReadOnly<{|
+        loaded: number,
+        total: number,
+        // loaded / total, from 0 to 1.
+        progress: number,
+    |}>,
+>
+
+export type ResizeMode = $ReadOnly<{|
+    contain: 'contain',
+    cover: 'cover',
+    stretch: 'stretch',
+    center: 'center',
+|}>
+
+export type Priority = $ReadOnly<{|
+    low: 'low',
+    normal: 'normal',
+    high: 'high',
+|}>
+
+export type CacheControl = $ReadOnly<{|
+    immutable: 'immutable',
+    web: 'web',
+    cacheOnly: 'cacheOnly',
+|}>
+
+export type ResizeModes = $Values<ResizeMode>
+export type Priorities = $Values<Priority>
+export type CacheControls = $Values<CacheControl>
+
+export type LoadResult =
+    | {| ok: true, width: number, height: number |}
+    | {| ok: false, error: string |}
+
+export type CacheLimits = {|
+    maxDiskSize?: ?number,
+    maxDiskAge?: ?number,
+    maxMemorySize?: ?number,
+|}
+
+export type CacheState = {|
+    maxDiskSize?: number,
+    maxDiskAge?: number,
+    maxMemorySize?: number,
+    diskSize?: number,
+|}
+
+export type CachePathResult =
+    | {| ok: true, path: string |}
+    | {| ok: false, error: string |}
+
+export type Transition = $ReadOnly<{|
+    duration?: ?number,
+    betweenImages?: ?boolean,
+    skipOnCacheHit?: ?('none' | 'memory' | 'all'),
+|}>
+
+export type PreloadSuccess = {|
+    uri: string,
+    ok: true,
+    width: number,
+    height: number,
+|}
+
+export type PreloadFailure = {|
+    uri?: string,
+    ok: false,
+    error: string,
+|}
+
+export type PreloadResult = PreloadSuccess | PreloadFailure
+
+export type PreloadFn = (
+    sources: Array<FastImageSource>,
+) => Promise<Array<PreloadResult>>
+export type FastImageSource = {
+    uri?: string,
+    headers?: Object,
+    priority?: Priorities,
+    cache?: CacheControls,
+    cacheKey?: string,
+    memoryCache?: boolean,
+}
+
+export type FastImageProps = $ReadOnly<{|
+    ...ViewProps,
+    onError?: ?(event: OnErrorEvent) => void,
+    onLoad?: ?(event: OnLoadEvent) => void,
+    onLoadEnd?: ?(result: LoadResult) => void,
+    onLoadStart?: ?() => void,
+    onProgress?: ?(event: OnProgressEvent) => void,
+
+    source?: ?(FastImageSource | number),
+    defaultSource?: ?number,
+
+    tintColor?: number | string,
+    resizeMode?: ?ResizeModes,
+    fallback?: ?boolean,
+    recyclingKey?: ?string,
+    loop?: ?(boolean | number),
+    imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
+    paused?: ?boolean,
+    transition?: ?(boolean | number | Transition),
+    downsample?: ?boolean,
+    blurRadius?: ?number,
+    testID?: ?string,
+|}>
+
+export type FastImageBackgroundProps = $ReadOnly<{|
+    ...FastImageProps,
+    imageStyle?: $PropertyType<ViewProps, 'style'>,
+    imageRef?: React$Ref<any>,
+    children?: React$Node,
+|}>
+
+declare export var FastImageBackground: React$ComponentType<FastImageBackgroundProps>
+
+declare export default class FastImage extends React$Component<FastImageProps> {
+    static resizeMode: ResizeMode;
+    static priority: Priority;
+    static cacheControl: CacheControl;
+    static preload: PreloadFn;
+    static clearMemoryCache: () => Promise<void>;
+    static clearDiskCache: () => Promise<void>;
+    static getCachePath: (source: FastImageSource) => Promise<CachePathResult>;
+    static configureCache: (limits?: CacheLimits) => Promise<CacheState>;
+    static writeToCache: (
+        source: FastImageSource,
+        file: string,
+    ) => Promise<CachePathResult>;
+}

package/dist/index.d.ts

@@ -1,25 +1,10 @@
 import React from 'react';
 import { LayoutChangeEvent, StyleProp, ViewStyle, ImageRequireSource, AccessibilityProps, ViewProps } from 'react-native';
+import { cacheControl, priority, resizeMode } from './constants';
 type ColorValue = NonNullable<ViewStyle['backgroundColor']>;
 export type ResizeMode = 'contain' | 'cover' | 'stretch' | 'center';
-declare const resizeMode: {
-    readonly contain: 'contain';
-    readonly cover: 'cover';
-    readonly stretch: 'stretch';
-    readonly center: 'center';
-};
 export type Priority = 'low' | 'normal' | 'high';
-declare const priority: {
-    readonly low: 'low';
-    readonly normal: 'normal';
-    readonly high: 'high';
-};
 export type Cache = 'immutable' | 'web' | 'cacheOnly';
-declare const cacheControl: {
-    readonly immutable: 'immutable';
-    readonly web: 'web';
-    readonly cacheOnly: 'cacheOnly';
-};
 export type Source = {
     uri?: string;
     headers?: {

package/dist/index.js

@@ -1,6 +1,6 @@
 import React, { forwardRef, memo, useRef } from "react";
 import { Image, NativeModules, Platform, StyleSheet, View, requireNativeComponent } from "react-native";
-//#region src/index.tsx
+//#region src/constants.ts
 const resizeMode = {
 	contain: "contain",
 	cover: "cover",
@@ -17,6 +17,8 @@ const cacheControl = {
 	web: "web",
 	cacheOnly: "cacheOnly"
 };
+//#endregion
+//#region src/index.tsx
 const resolveDefaultSource = (defaultSource) => {
 	if (!defaultSource) return null;
 	if (Platform.OS === "android") {

package/dist/index.web.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import type { FastImageBackgroundProps, FastImageProps, FastImageStaticProperties } from './index';
+export type * from './index';
+declare const FastImage: React.ComponentType<FastImageProps> & FastImageStaticProperties;
+export declare const FastImageBackground: React.ComponentType<FastImageBackgroundProps>;
+export default FastImage;

package/dist/index.web.js

@@ -0,0 +1,165 @@
+import React, { forwardRef, memo, useRef } from "react";
+import { Image, StyleSheet, View } from "react-native";
+//#region src/constants.ts
+const resizeMode = {
+	contain: "contain",
+	cover: "cover",
+	stretch: "stretch",
+	center: "center"
+};
+const priority = {
+	low: "low",
+	normal: "normal",
+	high: "high"
+};
+const cacheControl = {
+	immutable: "immutable",
+	web: "web",
+	cacheOnly: "cacheOnly"
+};
+//#endregion
+//#region src/index.web.tsx
+const notSupported = {
+	ok: false,
+	error: "Not supported on the web"
+};
+function FastImageBase({ source, defaultSource, tintColor, blurRadius, onLoadStart, onLoad, onError, onLoadEnd, style, children, resizeMode: mode = "cover", forwardedRef, onLayout, pointerEvents, fallback: _fallback, recyclingKey: _recyclingKey, loop: _loop, imageRendering: _imageRendering, paused: _paused, transition: _transition, downsample: _downsample, onProgress: _onProgress, ...props }) {
+	const result = useRef(void 0);
+	const sent = useRef(Promise.resolve());
+	const image = useRef(null);
+	const uri = typeof source === "object" && source ? source.uri : void 0;
+	const webSource = typeof source === "number" ? source : uri ? { uri } : void 0;
+	return /* @__PURE__ */ React.createElement(View, {
+		style: [styles.container, style],
+		onLayout,
+		pointerEvents,
+		ref: forwardedRef
+	}, /* @__PURE__ */ React.createElement(Image, {
+		...props,
+		style: styles.image,
+		source: webSource,
+		defaultSource,
+		resizeMode: mode,
+		tintColor,
+		blurRadius,
+		ref: image,
+		onLoadStart,
+		onLoad: (event) => {
+			var _event$nativeEvent;
+			sent.current = loadedSize(event === null || event === void 0 || (_event$nativeEvent = event.nativeEvent) === null || _event$nativeEvent === void 0 ? void 0 : _event$nativeEvent.target, image.current, uri).then(({ width, height }) => {
+				result.current = {
+					ok: true,
+					width,
+					height
+				};
+				onLoad === null || onLoad === void 0 || onLoad({ nativeEvent: {
+					width,
+					height
+				} });
+			});
+		},
+		onError: (event) => {
+			var _event$nativeEvent$er, _event$nativeEvent2;
+			const error = String((_event$nativeEvent$er = event === null || event === void 0 || (_event$nativeEvent2 = event.nativeEvent) === null || _event$nativeEvent2 === void 0 ? void 0 : _event$nativeEvent2.error) !== null && _event$nativeEvent$er !== void 0 ? _event$nativeEvent$er : "Failed to load the image");
+			result.current = {
+				ok: false,
+				error
+			};
+			sent.current = Promise.resolve();
+			onError === null || onError === void 0 || onError({ nativeEvent: { error } });
+		},
+		onLoadEnd: () => {
+			sent.current.then(() => {
+				var _result$current;
+				onLoadEnd === null || onLoadEnd === void 0 || onLoadEnd((_result$current = result.current) !== null && _result$current !== void 0 ? _result$current : {
+					ok: false,
+					error: "Failed to load the image"
+				});
+				result.current = void 0;
+			});
+		}
+	}), children);
+}
+const FastImageMemo = memo(FastImageBase);
+const FastImageComponent = forwardRef((props, ref) => /* @__PURE__ */ React.createElement(FastImageMemo, {
+	forwardedRef: ref,
+	...props
+}));
+FastImageComponent.displayName = "FastImage";
+async function loadedSize(loaded, view, uri) {
+	var _view$querySelector;
+	if (loaded === null || loaded === void 0 ? void 0 : loaded.naturalWidth) return {
+		width: loaded.naturalWidth,
+		height: loaded.naturalHeight
+	};
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	const shown = view === null || view === void 0 || (_view$querySelector = view.querySelector) === null || _view$querySelector === void 0 ? void 0 : _view$querySelector.call(view, "img");
+	if (shown === null || shown === void 0 ? void 0 : shown.naturalWidth) return {
+		width: shown.naturalWidth,
+		height: shown.naturalHeight
+	};
+	const src = uri !== null && uri !== void 0 ? uri : shown === null || shown === void 0 ? void 0 : shown.src;
+	return src ? getSize(src) : {
+		width: 0,
+		height: 0
+	};
+}
+function getSize(uri) {
+	return new Promise((resolve) => {
+		Image.getSize(uri, (width, height) => resolve({
+			width,
+			height
+		}), () => resolve({
+			width: 0,
+			height: 0
+		}));
+	});
+}
+const FastImage = FastImageComponent;
+FastImage.resizeMode = resizeMode;
+FastImage.cacheControl = cacheControl;
+FastImage.priority = priority;
+FastImage.preload = (sources) => Promise.all(sources.map((source) => {
+	const uri = source ? source.uri : void 0;
+	if (typeof uri !== "string" || !uri) return Promise.resolve({
+		ok: false,
+		error: "Invalid source: no uri",
+		uri
+	});
+	return Image.prefetch(uri).then(() => getSize(uri).then((size) => ({
+		ok: true,
+		uri,
+		...size
+	})), () => ({
+		ok: false,
+		error: "Failed to load the image",
+		uri
+	}));
+}));
+FastImage.clearMemoryCache = () => Promise.resolve();
+FastImage.clearDiskCache = () => Promise.resolve();
+FastImage.configureCache = () => Promise.resolve({});
+FastImage.writeToCache = () => Promise.resolve(notSupported);
+FastImage.getCachePath = () => Promise.resolve(notSupported);
+const styles = StyleSheet.create({
+	container: { overflow: "hidden" },
+	image: {
+		position: "absolute",
+		top: 0,
+		left: 0,
+		width: "100%",
+		height: "100%"
+	}
+});
+const FastImageWithRef = FastImageComponent;
+const FastImageBackground = forwardRef(({ style, imageStyle, imageRef, children, ...props }, ref) => /* @__PURE__ */ React.createElement(View, {
+	style,
+	ref
+}, /* @__PURE__ */ React.createElement(FastImageWithRef, {
+	...props,
+	style: [StyleSheet.absoluteFill, imageStyle],
+	ref: imageRef
+}), children));
+FastImageBackground.displayName = "FastImageBackground";
+//#endregion
+export { FastImageBackground, FastImage as default };

package/dist/index.web.js.flow

@@ -0,0 +1,154 @@
+// @flow
+
+import type { ViewProps } from 'react-native/Libraries/Components/View/ViewPropTypes'
+import type { SyntheticEvent } from 'react-native/Libraries/Types/CoreEventTypes'
+
+export type OnLoadEvent = SyntheticEvent<
+    $ReadOnly<{
+        width: number,
+        height: number,
+        // The view's React tag. Missing on Android with the legacy architecture.
+        // TODO: make it required once the New Architecture is the minimum.
+        target?: number,
+    }>,
+>
+
+export type OnErrorEvent = SyntheticEvent<
+    $ReadOnly<{|
+        error: string,
+    |}>,
+>
+
+export type OnProgressEvent = SyntheticEvent<
+    $ReadOnly<{|
+        loaded: number,
+        total: number,
+        // loaded / total, from 0 to 1.
+        progress: number,
+    |}>,
+>
+
+export type ResizeMode = $ReadOnly<{|
+    contain: 'contain',
+    cover: 'cover',
+    stretch: 'stretch',
+    center: 'center',
+|}>
+
+export type Priority = $ReadOnly<{|
+    low: 'low',
+    normal: 'normal',
+    high: 'high',
+|}>
+
+export type CacheControl = $ReadOnly<{|
+    immutable: 'immutable',
+    web: 'web',
+    cacheOnly: 'cacheOnly',
+|}>
+
+export type ResizeModes = $Values<ResizeMode>
+export type Priorities = $Values<Priority>
+export type CacheControls = $Values<CacheControl>
+
+export type LoadResult =
+    | {| ok: true, width: number, height: number |}
+    | {| ok: false, error: string |}
+
+export type CacheLimits = {|
+    maxDiskSize?: ?number,
+    maxDiskAge?: ?number,
+    maxMemorySize?: ?number,
+|}
+
+export type CacheState = {|
+    maxDiskSize?: number,
+    maxDiskAge?: number,
+    maxMemorySize?: number,
+    diskSize?: number,
+|}
+
+export type CachePathResult =
+    | {| ok: true, path: string |}
+    | {| ok: false, error: string |}
+
+export type Transition = $ReadOnly<{|
+    duration?: ?number,
+    betweenImages?: ?boolean,
+    skipOnCacheHit?: ?('none' | 'memory' | 'all'),
+|}>
+
+export type PreloadSuccess = {|
+    uri: string,
+    ok: true,
+    width: number,
+    height: number,
+|}
+
+export type PreloadFailure = {|
+    uri?: string,
+    ok: false,
+    error: string,
+|}
+
+export type PreloadResult = PreloadSuccess | PreloadFailure
+
+export type PreloadFn = (
+    sources: Array<FastImageSource>,
+) => Promise<Array<PreloadResult>>
+export type FastImageSource = {
+    uri?: string,
+    headers?: Object,
+    priority?: Priorities,
+    cache?: CacheControls,
+    cacheKey?: string,
+    memoryCache?: boolean,
+}
+
+export type FastImageProps = $ReadOnly<{|
+    ...ViewProps,
+    onError?: ?(event: OnErrorEvent) => void,
+    onLoad?: ?(event: OnLoadEvent) => void,
+    onLoadEnd?: ?(result: LoadResult) => void,
+    onLoadStart?: ?() => void,
+    onProgress?: ?(event: OnProgressEvent) => void,
+
+    source?: ?(FastImageSource | number),
+    defaultSource?: ?number,
+
+    tintColor?: number | string,
+    resizeMode?: ?ResizeModes,
+    fallback?: ?boolean,
+    recyclingKey?: ?string,
+    loop?: ?(boolean | number),
+    imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
+    paused?: ?boolean,
+    transition?: ?(boolean | number | Transition),
+    downsample?: ?boolean,
+    blurRadius?: ?number,
+    testID?: ?string,
+|}>
+
+export type FastImageBackgroundProps = $ReadOnly<{|
+    ...FastImageProps,
+    imageStyle?: $PropertyType<ViewProps, 'style'>,
+    imageRef?: React$Ref<any>,
+    children?: React$Node,
+|}>
+
+declare export var FastImageBackground: React$ComponentType<FastImageBackgroundProps>
+
+declare export default class FastImage extends React$Component<FastImageProps> {
+    static resizeMode: ResizeMode;
+    static priority: Priority;
+    static cacheControl: CacheControl;
+    static preload: PreloadFn;
+    static clearMemoryCache: () => Promise<void>;
+    static clearDiskCache: () => Promise<void>;
+    static getCachePath: (source: FastImageSource) => Promise<CachePathResult>;
+    static configureCache: (limits?: CacheLimits) => Promise<CacheState>;
+    static writeToCache: (
+        source: FastImageSource,
+        file: string,
+    ) => Promise<CachePathResult>;
+}

package/ios/FastImage/FFFDownsampledImage.m

@@ -89,7 +89,12 @@ static CGSize FFFPixelSize(NSData* data) {
     // After a load that isn't downsampled (e.g. a preload), this class
     // wouldn't be used, and the box would be decoded as SDWebImage does (to
     // fill it, stretched). With its own url, a downsampled load only shares
-    // downloads with other downsampled ones.
+    // downloads with other downsampled ones. Not a photo library url, which
+    // isn't downloaded, and whose loader reads everything after ph:// as the
+    // photo's identifier.
+    if ([url.scheme isEqualToString: @"ph"]) {
+        return url;
+    }
     NSURLComponents* components = [NSURLComponents componentsWithURL: url resolvingAgainstBaseURL: NO];
     if (!components) {
         return url;

package/ios/FastImage/FFFastImageSource.h

@@ -53,9 +53,18 @@ typedef NS_ENUM(NSInteger, FFFCacheControl) {
 - (SDWebImageOptions)cacheOptions;
 
 // The loader for `cache: 'web'` images, whose HTTP cache is their own (see
-// webURLCache), or nil for SDWebImage's shared one.
+// webURLCache), for photo library images (ph://, see FFFPhotosLoader), or nil
+// for SDWebImage's shared one.
 - (id<SDImageLoader>)imageLoader;
 
+// Whether the source is a photo library image (ph://<localIdentifier>),
+// which is decoded at about the view's size.
+- (BOOL)isPhotoLibrary;
+
+// A photo library image's own size in pixels (for onLoad when it comes from
+// a cache, where the size it was decoded from isn't recorded), or zero.
+- (CGSize)photoPixelSize;
+
 // The HTTP cache of `cache: 'web'` images: their own rather than the app's
 // shared NSURLCache, so clearDiskCache can empty it without the app's other
 // responses. 50 MB, as on Android.

package/ios/FastImage/FFFastImageSource.m

@@ -5,9 +5,150 @@
 #import <SDWebImage/SDWebImageError.h>
 #import <SDWebImage/SDWebImageDownloaderOperation.h>
 #import <SDWebImage/NSData+ImageContentType.h>
+#import <objc/message.h>
 
 static NSUInteger const FFFWebCacheSize = 50 * 1024 * 1024;
 
+// The photo's own size in pixels, looked up by its identifier (the url after
+// ph://), or zero. Through the runtime, as the Photos framework is only there
+// when the app links it (with SDWebImagePhotosPlugin). Kept once looked up.
+static CGSize FFFLookUpPhotoPixelSize(NSURL *url)
+{
+    Class assetClass = NSClassFromString(@"PHAsset");
+    SEL fetch = NSSelectorFromString(@"fetchAssetsWithLocalIdentifiers:options:");
+    NSString *prefix = @"ph://";
+    NSString *string = url.absoluteString;
+    if (!assetClass || ![assetClass respondsToSelector:fetch] || ![string hasPrefix:prefix]) {
+        return CGSizeZero;
+    }
+    id (*fetchAssets)(id, SEL, NSArray *, id) = (void *)objc_msgSend;
+    id result = fetchAssets(assetClass, fetch, @[[string substringFromIndex:prefix.length]], nil);
+    id asset = [result respondsToSelector:@selector(firstObject)] ? [result firstObject] : nil;
+    if (!asset) {
+        return CGSizeZero;
+    }
+    return CGSizeMake([[asset valueForKey:@"pixelWidth"] doubleValue], [[asset valueForKey:@"pixelHeight"] doubleValue]);
+}
+
+static NSCache<NSString *, NSValue *> *FFFPhotoSizes(void)
+{
+    static NSCache *sizes;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+        sizes = [NSCache new];
+    });
+    return sizes;
+}
+
+static CGSize FFFPhotoPixelSize(NSURL *url)
+{
+    NSString *key = url.absoluteString;
+    NSValue *known = key ? [FFFPhotoSizes() objectForKey:key] : nil;
+    if (known) {
+        return known.CGSizeValue;
+    }
+    CGSize size = FFFLookUpPhotoPixelSize(url);
+    if (key && size.width > 0 && size.height > 0) {
+        [FFFPhotoSizes() setObject:[NSValue valueWithCGSize:size] forKey:key];
+    }
+    return size;
+}
+
+// Loads photo library images (ph://<localIdentifier>) with
+// SDWebImagePhotosPlugin's loader when the app has it (the pod): FastImage
+// finds it at runtime, so it doesn't depend on it or on the Photos framework.
+// Its own instance, so the app's use of the plugin is left as it is. Without
+// the plugin, or for a source it can't load (assets-library://), the load
+// fails with `failure`.
+@interface FFFPhotosLoader : NSObject <SDImageLoader>
+@property (nonatomic, strong) id<SDImageLoader> plugin;
+@property (nonatomic, copy) NSString *failure;
+@end
+
+@implementation FFFPhotosLoader
+
++ (FFFPhotosLoader *)photosLoader
+{
+    static FFFPhotosLoader *loader;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+        loader = [FFFPhotosLoader new];
+        Class pluginClass = NSClassFromString(@"SDImagePhotosLoader");
+        id<SDImageLoader> plugin = pluginClass ? [pluginClass new] : nil;
+        if ([plugin conformsToProtocol:@protocol(SDImageLoader)]) {
+            // One image per load, at full quality. By default the plugin
+            // first sends a quick low quality one, which a view would show
+            // (and fade in) before the one it asked for.
+            // PHImageRequestOptionsDeliveryModeHighQualityFormat. Skipped if
+            // a later version of the plugin renames these.
+            NSObject *requestOptions = [(NSObject *)plugin respondsToSelector:NSSelectorFromString(@"imageRequestOptions")]
+                ? [(NSObject *)plugin valueForKey:@"imageRequestOptions"]
+                : nil;
+            if ([requestOptions respondsToSelector:NSSelectorFromString(@"setDeliveryMode:")]) {
+                [requestOptions setValue:@1 forKey:@"deliveryMode"];
+            }
+            loader.plugin = plugin;
+        } else {
+            loader.failure = @"Photo library images (ph://) need SDWebImagePhotosPlugin: add pod 'SDWebImagePhotosPlugin' to the app's Podfile";
+        }
+    });
+    return loader;
+}
+
++ (FFFPhotosLoader *)assetsLibraryLoader
+{
+    static FFFPhotosLoader *loader;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+        loader = [FFFPhotosLoader new];
+        loader.failure = @"assets-library:// urls aren't supported: use the photo's ph:// url (with SDWebImagePhotosPlugin)";
+    });
+    return loader;
+}
+
+- (BOOL)canRequestImageForURL:(NSURL *)url
+{
+    return YES;
+}
+
+- (id<SDWebImageOperation>)requestImageWithURL:(NSURL *)url
+                                        options:(SDWebImageOptions)options
+                                        context:(SDWebImageContext *)context
+                                       progress:(SDImageLoaderProgressBlock)progressBlock
+                                      completed:(SDImageLoaderCompletedBlock)completedBlock
+{
+    if (!self.plugin) {
+        if (completedBlock) {
+            NSError *error = [NSError errorWithDomain:SDWebImageErrorDomain code:SDWebImageErrorInvalidURL userInfo:@{NSLocalizedDescriptionKey: self.failure}];
+            completedBlock(nil, nil, error, YES);
+        }
+        return nil;
+    }
+    return [self.plugin requestImageWithURL:url options:options context:context progress:progressBlock completed:^(UIImage *image, NSData *data, NSError *error, BOOL finished) {
+        if (!image || !completedBlock) {
+            if (completedBlock) {
+                completedBlock(image, data, error, finished);
+            }
+            return;
+        }
+        // Looks up the photo's own size for onLoad here, off the main thread
+        // (the image is decoded at about the view's size).
+        dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
+            FFFPhotoPixelSize(url);
+            dispatch_async(dispatch_get_main_queue(), ^{
+                completedBlock(image, data, error, finished);
+            });
+        });
+    }];
+}
+
+- (BOOL)shouldBlockFailedURLWithURL:(NSURL *)url error:(NSError *)error
+{
+    return self.plugin ? [self.plugin shouldBlockFailedURLWithURL:url error:error] : NO;
+}
+
+@end
+
 // Downloads `cache: 'web'` images. The HTTP cache only stores a response whose
 // body is an image: a page sent instead (e.g. a captive portal's, with status
 // 200) would be served from there until it expired, and each load would fail.
@@ -75,8 +216,24 @@ static NSUInteger const FFFWebCacheSize = 50 * 1024 * 1024;
     return 0;
 }
 
+- (BOOL)isPhotoLibrary
+{
+    return [_url.scheme isEqualToString:@"ph"];
+}
+
+- (CGSize)photoPixelSize
+{
+    return [self isPhotoLibrary] ? FFFPhotoPixelSize(_url) : CGSizeZero;
+}
+
 - (id<SDImageLoader>)imageLoader
 {
+    if ([self isPhotoLibrary]) {
+        return [FFFPhotosLoader photosLoader];
+    }
+    if ([_url.scheme isEqualToString:@"assets-library"]) {
+        return [FFFPhotosLoader assetsLibraryLoader];
+    }
     if (_cacheControl != FFFCacheControlWeb) {
         return nil;
     }

package/ios/FastImage/FFFastImageView.m

@@ -570,7 +570,9 @@ NSString *FFFErrorMessage(NSError *error)
 
 - (void) sendOnLoad: (UIImage*)image {
     // The full image's size, also when it was decoded smaller.
-    CGSize size = [FFFDownsampledImage sourceSizeOfImage: image];
+    // A photo library image's own size (it's decoded at about the view's
+    // size), looked up when it loaded.
+    CGSize size = [_source isPhotoLibrary] ? [_source photoPixelSize] : [FFFDownsampledImage sourceSizeOfImage: image];
     if (CGSizeEqualToSize(size, CGSizeZero)) {
         size = image.size;
     }
@@ -646,11 +648,15 @@ NSString *FFFErrorMessage(NSError *error)
     }
 }
 
-// Whether images are decoded at about the view's size (downsample).
-// Not for `repeat`, which tiles the image at its own size, or SDWebImage
-// before 5.19.
+// Whether images are decoded at about the view's size (downsample, from
+// SDWebImage 5.19, and always for photo library images, which are large and
+// usually shown small: Photos makes them at the size asked for, on any
+// version). Not for `repeat`, which tiles the image at its own size.
 - (BOOL) downsamples {
-    return _downsample && _resizeMode != RCTResizeModeRepeat && [FFFDownsampledImage isSupported];
+    if (_resizeMode == RCTResizeModeRepeat) {
+        return NO;
+    }
+    return [_source isPhotoLibrary] || (_downsample && [FFFDownsampledImage isSupported]);
 }
 
 // Whether the view has been laid out with an area. One that's 0 wide or tall
@@ -823,6 +829,13 @@ NSString *FFFErrorMessage(NSError *error)
     }
     NSString* key = _source.cacheKeyFilter ? _source.cacheKey : _source.url.absoluteString;
     [FFFDownsampledImage addToContext: context forKey: key box: box cover: self.decodedCover];
+    if ([_source isPhotoLibrary]) {
+        // Photos makes the photo at the size asked for, with no file
+        // downloaded: SDWebImage would keep this smaller copy on disk as the
+        // photo's original, and a larger view would get it from there.
+        context[SDWebImageContextOriginalStoreCacheType] = @(SDImageCacheTypeNone);
+        context[SDWebImageContextOriginalQueryCacheType] = @(SDImageCacheTypeNone);
+    }
     if (!_source.memoryCache) {
         // The smaller copy is only kept in memory, so it isn't kept (the
         // downloaded file is still on disk).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-native-fast-image",
-    "version": "8.22.0",
+    "version": "8.24.0",
     "description": "🚩 FastImage, performant React Native image component.",
     "keywords": [
         "cache",
@@ -19,8 +19,10 @@
     },
     "license": "(MIT AND Apache-2.0)",
     "author": "Dylan Vann <dylan@dylanvann.com> (https://dylanvann.com)",
-    "main": "dist/index.cjs.js",
-    "module": "dist/index.js",
+    "main": "dist/index.cjs",
+    "module": "dist/index",
+    "react-native": "dist/index.cjs",
+    "browser": "dist/index.web.js",
     "typings": "dist/index.d.ts",
     "files": [
         "android/build.gradle",
@@ -34,7 +36,7 @@
         "RNFastImage.podspec"
     ],
     "scripts": {
-        "build": "rm -rf dist && tsc -p tsconfig.build.json && rolldown -c && cp src/index.js.flow dist/index.js.flow && cp src/index.js.flow dist/index.cjs.js.flow",
+        "build": "rm -rf dist && tsc -p tsconfig.build.json && rolldown -c && for f in index index.cjs index.web index.cjs.web; do cp src/index.js.flow dist/$f.js.flow; done",
         "lint": "oxlint",
         "release": "semantic-release",
         "test": "bun test",