rn-cached-img-by-key

CachedImage component with key for react-native,

This package is based on kfiroo/react-native-cached-image, adding cache by key functionality, also greatly inspired by @jayesbe's amazing react-native-cacheable-image.

Installation

npm install @experience-os/rn-cached-img-by-key @react-native-community/netinfo rn-fetch-blob --save
- or -
yarn add @experience-os/rn-cached-img-by-key @react-native-community/netinfo rn-fetch-blob

We use rn-fetch-blob to handle file system access in this package and it requires an extra step during the installation.

You should only have to do this once.

react-native link rn-fetch-blob

Or, if you want to add Android permissions to AndroidManifest.xml automatically, use this one:

RNFB_ANDROID_PERMISSIONS=true react-native link rn-fetch-blob

Network Status - Android only

Add the following line to your android/app/src/AndroidManifest.xml

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

iOS only

cd ios && pod install

Usage

TODO - add usage example

import React from 'react';
import { View } from 'react-native';
import {
    CachedImage,
    ImageCacheManager
} from '@experience-os/rn-cached-img-by-key';

const image1 = {
    url: 'https://via.placeholder.com/260?123/123312213618243',
    id: 1,
    last_update: '2020-05-05 12:33:23'
};

const image2 = {
    url: 'https://via.placeholder.com/260?123/123312213618243',
    id: 2,
    last_update: '2020-05-05 12:33:23'
};

export default class Example extends React.Component {
    render() {
        return (
            <View>
                
                /* Usage with unique key (caching for dynamic URLs eg: privately signed urls) */
                <CachedImage
                    keyValue={`${image1.id}-${image1.last_update}`} 
                    source={{uri: image1.url}}
                    showLoader={false}
                    style={{height:100, width:100}}
                />

                /* Usage url only */
                <CachedImage
                    source={{uri: image2.url}}
                    showLoader={false}
                    style={{height:100, width:100}}
                />

            </View>
        );
    }
}

Example using cacheManager directly

const defaultImageCacheManager = ImageCacheManager();

const image1 = {
    url: 'https://via.placeholder.com/260?123/123312213618243',
    id: 1,
    last_update: '2020-05-05 12:33:23'
};

const image2 = {
    url: 'https://via.placeholder.com/260?123/123312213618243',
    id: 2,
    last_update: '2020-05-05 12:33:23'
};

// Usage with unique key (caching for dynamic URLs eg: privately signed urls)
defaultImageCacheManager.downloadAndCacheUrl(image1.url, {key: `${image1.id}-${image1.last_update}`});
// Usage with url only:
defaultImageCacheManager.downloadAndCacheUrl(image2.url);

API

This package exposes 2 modules, for most common cases you only need to use CachedImage

const {
    CachedImage,            // react-native component that is a drop-in replacement for your react-native `Image` components
    ImageCacheManager,      // the logic behind cache machanism - ttl, fs, url resolving etc. 
} = require('@experience-os/rn-cached-img-by-key');

ImageCacheManager

This is where all the cache magic takes place. The API usually takes a URL and a set of ImageCacheManagerOptions.

ImageCacheManager.downloadAndCacheUrl(url: String, options: ImageCacheManagerOptions): Promise<String>

Check the cache for the the URL (after removing fixing the query string according to ImageCacheManagerOptions.useQueryParamsInCacheKey). If the URL exists in cache and is not expired, resolve with the local cached file path. Otherwise, download the file to the cache folder, add it to the cache and then return the cached file path.

ImageCacheManager.seedAndCacheUrl(url: String, seedPath: String, options: ImageCacheManagerOptions): Promise<String>

Check the cache for the the URL (after removing fixing the query string according to ImageCacheManagerOptions.useQueryParamsInCacheKey). If the URL exists in cache and is not expired, resolve with the local cached file path. Otherwise, copy the seed file into the cache folder, add it to the cache and then return the cached file path.

ImageCacheManager.deleteUrl(url: String, options: ImageCacheManagerOptions): Promise

Removes the cache entry for the URL and the local file corresponding to it, if it exists.

ImageCacheManager.clearCache(options: ImageCacheManagerOptions): Promise

Clear the URL cache and remove files in the cache folder (as stated in the ImageCacheManagerOptions.cacheLocation)

ImageCacheManager.getCacheInfo(options: ImageCacheManagerOptions): Promise.<{file: Array, size: Number}>

Returns info about the cache, list of files and the total size of the cache.

CachedImage

CachedImage is a drop in replacement for the Image component that will attempt to cache remote URLs for better performance.
It's main use is to hide the cache layer from the user and provide a simple way to cache images.
CachedImage uses an instance of ImageCacheManager to interact with the cache.

 <CachedImage
        keyValue="unique key identifying image with dynamic url from database" 
        source={{uri: image1.url}}
        style={{height:100, width:100}}
    />

Props

• renderImage - a function that returns a component, used to override the underlying Image component.
• activityIndicatorProps - props for the ActivityIndicator that is shown while the image is downloaded.
• defaultSource - prop to display a background image while the source image is downloaded. This will work even in android, but will not display background image if there you set borderRadius on this component style prop
• keyValue - prop to cache image with key
• showLoader - prop to show loader when image is being downloaded and cached.
• loadingIndicator - component prop to set custom ActivityIndicator.
• fallbackSource - prop to set placeholder image. when source.uri is null or cached failed, the fallbackSource will be display.
• any of the ImageCacheManagerOptionsPropTypes props - customize the ImageCacheManager for this specific CachedImage instance.

ImageCacheManagerOptions

A set of options that are provided to the ImageCacheManager and provide ways to customize it to your needs.

type ImageCacheManagerOptions = {
    headers: PropTypes.object,                      // an object to be used as the headers when sending the request for the url. default {}
    
    key: PropTypes.number,                          // the key value of image

    ttl: PropTypes.number,                          // the number of seconds each url will stay in the cache. default 2 weeks
    
    useQueryParamsInCacheKey: PropTypes.oneOfType([ // when handling a URL with query params, this indicates how it should be treated:
        PropTypes.bool,                             // if a bool value is given the whole query string will be used / ignored
        PropTypes.arrayOf(PropTypes.string)         // if an array of strings is given, only these keys will be taken from the query string.
    ]),                                             // default false
    
    cacheLocation: PropTypes.string,                // the path to the root of the cache folder. default the device cache dir 

    allowSelfSignedSSL: PropTypes.bool,             // true to allow self signed SSL URLs to be downloaded. default false
};