@mnightingale/react-native-image-cache-hoc/dist/FileSystem.d.ts

React Native Higher Order Component that adds advanced caching functionality to the react native Image component.

/**
 *
 * This library acts as an interface to abstract the OS file system and is platform independent.
 *
 * File paths passed into this library should be relative, as the base file path is different
 * across platforms, and therefore is automatically set by this library.
 *
 */
import RNFS from 'react-native-fs';
import { Observable, ReplaySubject } from 'rxjs';
import { CacheStrategy } from '.';
import { HeaderFn } from './types';
export interface CacheFileInfo {
    path: string | null;
    fileName: string;
    md5?: string;
}
export declare class FileSystem {
    /**
     * All FileSystem instances will reference the cacheLock singleton "dictionary" to provide cache file locking in order to prevent concurrency race condition bugs.
     *
     * cacheLock structure:
     *
     * cacheLock = {
     *   'filename.jpg': {
     *     'componentIdOne': true,
     *     'componentIdTwo': true
     *   }
     * }
     *
     * In the above example cache/filename.jpg cannot be deleted during cache pruning,
     * until both components release their locks on the dependant image file.
     *
     * One example (of many) of how a race condition could occur:
     *
     * 1st <CacheableImage> mounts and downloads image file into cache, calls render() (or not) etc.
     * 2nd <CacheableImage> mounts concurrently and during download runs pruneCache(), deleting 1st <CacheableImage>'s image file from cache.
     * 1st <CacheableImage> calls render() again at some point in the future, at this time it's image file no longer exists so the render fails.
     */
    static cacheLock: {
        [key: string]: {
            [component: string]: boolean;
        };
    };
    static cacheObservables: {
        [key: string]: ReplaySubject<CacheFileInfo>;
    };
    baseFilePath: string;
    cachePruneTriggerLimit: number;
    static lockCacheFile(fileName: string, componentId: string): void;
    static unlockCacheFile(fileName: string, componentId: string): void;
    constructor(cachePruneTriggerLimit: number | null, fileDirName: string | null);
    /**
     *
     * Sets the base file directory depending on platform. Prefix is used to avoid local file collisions.
     *
     * Apple:
     * Apple requires non-user generated files to be stored in cache dir, they can be flagged to persist. https://developer.apple.com/icloud/documentation/data-storage/index.html
     * it appears reactNativeFetchBlob will flag these files to persist behind the scenes, so cache dir is safe on apple. See: https://www.npmjs.com/package/rn-fetch-blob#cache-file-management
     *
     * Android:
     * Android appears to purge cache dir files so we should use document dir to play it safe (even with reactNativeFetchBlob abstraction) : https://developer.android.com/guide/topics/data/data-storage.html
     *
     * @returns {String} baseFilePath - base path that files are written to in local fs.
     * @private
     */
    _setBaseFilePath(fileDirName?: string): string;
    /**
     *
     * Pseudo-chroot paths to the baseFilePath set in _setBaseFilePath().
     *
     * This method should be called on any passed in path to prevent writing to invalid directories.
     * IE passing in a path of '../../../../../home/should/not/write/here/file.png' to break out of
     * the base file path directory.
     *
     * @param path {String} - local fs path.
     * @param absolute {String} - whether or not the passed in path is absolute or relative. Defaults to relative since base path differs across platforms.
     * @returns {boolean} - Whether or not the file path is valid.
     * @throws error on bad filepath.
     * @private
     */
    _validatePath(path: string, absolute?: boolean): boolean;
    /**
     *
     * Wrapper for https://github.com/joltup/rn-fetch-blob/wiki/File-System-Access-API#existspathstringpromise
     *
     * @param path - local relative file path.
     * @returns {Promise} - boolean promise for if file exists at path or not.
     */
    exists(path: string): Promise<boolean>;
    /**
     *
     * Creates a SHA1 hash filename from a url and normalizes extension.
     *
     * @param url {String} - An absolute url.
     * @throws error on invalid (non jpg, png, gif, bmp) url file type. NOTE file extension or content-type header does not guarantee file mime type. We are trusting that it is set correctly on the server side.
     * @returns fileName {string} - A SHA1 filename that is unique to the resource located at passed in URL and includes an appropriate extension.
     */
    getFileNameFromUrl(url: string): string;
    /**
     *
     * Convenience method used to get the associated local file path of a web image that has been written to disk.
     * If the local file does not exist yet, the remote file is downloaded to local disk then the local filepath is returned.
     *
     * @param url {String} - url of file to download.
     * @returns {Promise<string|null>} promise that resolves to the local file path of downloaded url file.
     */
    getLocalFilePathFromUrl(url: string): Promise<string | null>;
    /**
     *
     * Manually move or copy a local file to the cache.
     * Can be used to pre-warm caches.
     * If calling this method repeatedly to cache a long list of files,
     * be sure to use a queue and limit concurrency so your app performance does not suffer.
     *
     * @param local {String} - path to the local file.
     * @param url {String} - url of file to download.
     * @param move {Boolean} - whether the file should be copied or moved.
     * @param mtime {Date} - creation timestamp
     * @param ctime {Date} - modification timestamp (iOS only)
     * @returns {Promise} promise that resolves to an object that contains cached file info.
     */
    cacheLocalFile(local: string, url: string, move?: boolean, mtime?: Date, ctime?: Date): Promise<{
        url: string;
        path: null;
    } | {
        url: string;
        path: string;
    }>;
    /**
     *
     * Used to download files to local filesystem.
     *
     * @param url {String} - url of file to download.
     * @param fileName {String} - defaults to a sha1 hash of the url param with extension of same filetype.
     * @returns {Observable<CacheFileInfo>} observable that resolves to an object that contains the local path of the downloaded file and the filename.
     */
    fetchFile(url: string, fileName?: string | null, headers?: RNFS.Headers): Observable<CacheFileInfo>;
    /**
     * Used to remove files from cache directory if the cache grows too large.
     * This function will delete files from the cache until the total cache size
     * is less than FileSystem.cachePruneTriggerLimit setting.
     *
     * @returns {Promise}
     */
    pruneCache(): Promise<void>;
    /**
     * Used to delete local files and directories
     *
     * @param path - local relative file path.
     * @returns {Promise} - boolean promise for if deletion was successful.
     */
    unlink(path: string): Promise<boolean>;
    /**
     * Gets a observable which emits when a url is resolved to a local file path
     * A cache lock is required @see {lockCacheFile}
     *
     * @param url {String} - url of file to download.
     * @param componentId {String} - Unique id of the requestor.
     * @param cacheStrategy {CacheStrategy} - The cache strategy to use, defaults to 'immutable'.
     * @param fileName {String} - defaults to a sha1 hash of the url param with extension of same filetype.
     * @param headers {HeaderFn} - Headers to include with requests
     * @returns {Observable<CacheFileInfo>} observable that resolves to an object that contains the local path of the downloaded file and the filename.
     */
    observable(url: string, componentId: string, cacheStrategy?: CacheStrategy, fileName?: string | null, headers?: HeaderFn): Observable<CacheFileInfo>;
}
/**
 *  Export FileSystem factory for convenience.
 *
 * @returns {FileSystem}
 */
export default function FileSystemFactory(cachePruneTriggerLimit?: number | null, fileDirName?: string | null): FileSystem;
//# sourceMappingURL=FileSystem.d.ts.map