react-native-onyx 1.0.1

package/lib/OnyxCache.js

@@ -0,0 +1,195 @@
+import _ from 'underscore';
+import lodashMerge from 'lodash/merge';
+
+
+const isDefined = _.negate(_.isUndefined);
+
+/**
+ * In memory cache providing data by reference
+ * Encapsulates Onyx cache related functionality
+ */
+class OnyxCache {
+    constructor() {
+        /**
+         * @private
+         * Cache of all the storage keys available in persistent storage
+         * @type {Set<string>}
+         */
+        this.storageKeys = new Set();
+
+        /**
+         * @private
+         * Unique list of keys maintained in access order (most recent at the end)
+         * @type {Set<string>}
+         */
+        this.recentKeys = new Set();
+
+        /**
+         * @private
+         * A map of cached values
+         * @type {Record<string, *>}
+         */
+        this.storageMap = {};
+
+        /**
+         * @private
+         * Captured pending tasks for already running storage methods
+         * @type {Record<string, Promise>}
+         */
+        this.pendingPromises = {};
+
+        // bind all public methods to prevent problems with `this`
+        _.bindAll(
+            this,
+            'getAllKeys', 'getValue', 'hasCacheForKey', 'addKey', 'set', 'drop', 'merge',
+            'hasPendingTask', 'getTaskPromise', 'captureTask', 'removeLeastRecentlyUsedKeys',
+            'setRecentKeysLimit'
+        );
+    }
+
+    /**
+     * Get all the storage keys
+     * @returns {string[]}
+     */
+    getAllKeys() {
+        return Array.from(this.storageKeys);
+    }
+
+    /**
+     * Get a cached value from storage
+     * @param {string} key
+     * @returns {*}
+     */
+    getValue(key) {
+        this.addToAccessedKeys(key);
+        return this.storageMap[key];
+    }
+
+    /**
+     * Check whether cache has data for the given key
+     * @param {string} key
+     * @returns {boolean}
+     */
+    hasCacheForKey(key) {
+        return isDefined(this.storageMap[key]);
+    }
+
+    /**
+     * Saves a key in the storage keys list
+     * Serves to keep the result of `getAllKeys` up to date
+     * @param {string} key
+     */
+    addKey(key) {
+        this.storageKeys.add(key);
+    }
+
+    /**
+     * Set's a key value in cache
+     * Adds the key to the storage keys list as well
+     * @param {string} key
+     * @param {*} value
+     * @returns {*} value - returns the cache value
+     */
+    set(key, value) {
+        this.addKey(key);
+        this.addToAccessedKeys(key);
+        this.storageMap[key] = value;
+
+        return value;
+    }
+
+    /**
+     * Forget the cached value for the given key
+     * @param {string} key
+     */
+    drop(key) {
+        delete this.storageMap[key];
+    }
+
+    /**
+     * Deep merge data to cache, any non existing keys will be created
+     * @param {Record<string, *>} data - a map of (cache) key - values
+     */
+    merge(data) {
+        this.storageMap = lodashMerge({}, this.storageMap, data);
+
+        const storageKeys = this.getAllKeys();
+        const mergedKeys = _.keys(data);
+        this.storageKeys = new Set([...storageKeys, ...mergedKeys]);
+        _.each(mergedKeys, key => this.addToAccessedKeys(key));
+    }
+
+    /**
+     * Check whether the given task is already running
+     * @param {string} taskName - unique name given for the task
+     * @returns {*}
+     */
+    hasPendingTask(taskName) {
+        return isDefined(this.pendingPromises[taskName]);
+    }
+
+    /**
+     * Use this method to prevent concurrent calls for the same thing
+     * Instead of calling the same task again use the existing promise
+     * provided from this function
+     * @template T
+     * @param {string} taskName - unique name given for the task
+     * @returns {Promise<T>}
+     */
+    getTaskPromise(taskName) {
+        return this.pendingPromises[taskName];
+    }
+
+    /**
+     * Capture a promise for a given task so other caller can
+     * hook up to the promise if it's still pending
+     * @template T
+     * @param {string} taskName - unique name for the task
+     * @param {Promise<T>} promise
+     * @returns {Promise<T>}
+     */
+    captureTask(taskName, promise) {
+        this.pendingPromises[taskName] = promise.finally(() => {
+            delete this.pendingPromises[taskName];
+        });
+
+        return this.pendingPromises[taskName];
+    }
+
+    /**
+     * @private
+     * Adds a key to the top of the recently accessed keys
+     * @param {string} key
+     */
+    addToAccessedKeys(key) {
+        // Removing and re-adding a key ensures it's at the end of the list
+        this.recentKeys.delete(key);
+        this.recentKeys.add(key);
+    }
+
+    /**
+     * Remove keys that don't fall into the range of recently used keys
+     */
+    removeLeastRecentlyUsedKeys() {
+        if (this.recentKeys.size > this.maxRecentKeysSize) {
+            // Get the last N keys by doing a negative slice
+            const recentlyAccessed = [...this.recentKeys].slice(-this.maxRecentKeysSize);
+            const storageKeys = _.keys(this.storageMap);
+            const keysToRemove = _.difference(storageKeys, recentlyAccessed);
+
+            _.each(keysToRemove, this.drop);
+        }
+    }
+
+    /**
+     * Set the recent keys list size
+     * @param {number} limit
+     */
+    setRecentKeysLimit(limit) {
+        this.maxRecentKeysSize = limit;
+    }
+}
+
+const instance = new OnyxCache();
+
+export default instance;

package/lib/SyncQueue.js

@@ -0,0 +1,51 @@
+/**
+ * Synchronous queue that can be used to ensure promise based tasks are run in sequence.
+ * Pass to the constructor a function that returns a promise to run the task then add data.
+ *
+ * @example
+ *
+ *     const queue = new SyncQueue(({key, val}) => {
+ *         return someAsyncProcess(key, val);
+ *     });
+ *
+ *     queue.push({key: 1, val: '1'});
+ *     queue.push({key: 2, val: '2'});
+ */
+export default class SyncQueue {
+    /**
+     * @param {Function} run - must return a promise
+     */
+    constructor(run) {
+        this.queue = [];
+        this.isProcessing = false;
+        this.run = run;
+    }
+
+    process() {
+        if (this.isProcessing || this.queue.length === 0) {
+            return;
+        }
+
+        this.isProcessing = true;
+
+        const {data, resolve, reject} = this.queue.shift();
+        this.run(data)
+            .then(resolve)
+            .catch(reject)
+            .finally(() => {
+                this.isProcessing = false;
+                this.process();
+            });
+    }
+
+    /**
+     * @param {*} data
+     * @returns {Promise}
+     */
+    push(data) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({resolve, reject, data});
+            this.process();
+        });
+    }
+}

package/lib/compose.js

@@ -0,0 +1,29 @@
+/**
+ * This is a utility function taken directly from Redux. (We don't want to add Redux as a dependency)
+ * It enables functional composition, useful for the chaining/composition of HOCs.
+ *
+ * For example, instead of:
+ *
+ * export default hoc1(config1, hoc2(config2, hoc3(config3)))(Component);
+ *
+ * Use this instead:
+ *
+ * export default compose(
+ *     hoc1(config1),
+ *     hoc2(config2),
+ *     hoc3(config3),
+ * )(Component)
+ *
+ * @returns {Function}
+ */
+export default function compose(...funcs) {
+    if (funcs.length === 0) {
+        return arg => arg;
+    }
+
+    if (funcs.length === 1) {
+        return funcs[0];
+    }
+
+    return funcs.reduce((a, b) => (...args) => a(b(...args)));
+}

package/lib/createDeferredTask.js

@@ -0,0 +1,16 @@
+/**
+ * Create a deferred task that can be resolved when we call `resolve()`
+ * The returned promise will complete when we call `resolve`
+ * Useful when we want to wait for a tasks that is resolved from an external action
+ *
+ * @template T
+ * @returns {{ resolve: function(*), promise: Promise<T|void> }}
+ */
+export default function createDeferredTask() {
+    const deferred = {};
+    deferred.promise = new Promise((res) => {
+        deferred.resolve = res;
+    });
+
+    return deferred;
+}

package/lib/index.js

@@ -0,0 +1,5 @@
+import Onyx from './Onyx';
+import withOnyx from './withOnyx';
+
+export default Onyx;
+export {withOnyx};

package/lib/metrics/index.native.js

@@ -0,0 +1,263 @@
+import _ from 'underscore';
+import performance from 'react-native-performance';
+import MDTable from '../MDTable';
+
+const decoratedAliases = new Set();
+
+/**
+ * Capture a start mark to performance entries
+ * @param {string} alias
+ * @param {Array<*>} args
+ * @returns {{name: string, startTime:number, detail: {args: [], alias: string}}}
+ */
+function addMark(alias, args) {
+    return performance.mark(alias, {detail: {args, alias}});
+}
+
+/**
+ * Capture a measurement between the start mark and now
+ * @param {{name: string, startTime:number, detail: {args: []}}} startMark
+ * @param {*} detail
+ */
+function measureMarkToNow(startMark, detail) {
+    performance.measure(`${startMark.name} [${startMark.detail.args.toString()}]`, {
+        start: startMark.startTime,
+        end: performance.now(),
+        detail: {...startMark.detail, ...detail}
+    });
+}
+
+/**
+ * Wraps a function with metrics capturing logic
+ * @param {function} func
+ * @param {String} [alias]
+ * @returns {function} The wrapped function
+ */
+function decorateWithMetrics(func, alias = func.name) {
+    if (decoratedAliases.has(alias)) {
+        throw new Error(`"${alias}" is already decorated`);
+    }
+
+    decoratedAliases.add(alias);
+
+    function decorated(...args) {
+        const mark = addMark(alias, args);
+
+        const originalPromise = func.apply(this, args);
+
+        /*
+        * Then handlers added here are not affecting the original promise
+        * They create a separate chain that's not exposed (returned) to the original caller
+        * */
+        originalPromise
+            .then((result) => {
+                measureMarkToNow(mark, {result});
+            })
+            .catch((error) => {
+                measureMarkToNow(mark, {error});
+            });
+
+        return originalPromise;
+    }
+
+    return decorated;
+}
+
+/**
+ * Calculate the total sum of a given key in a list
+ * @param {Array<Record<prop, Number>>} list
+ * @param {string} prop
+ * @returns {number}
+ */
+function sum(list, prop) {
+    return _.reduce(list, (memo, next) => memo + next[prop], 0);
+}
+
+/**
+ * Aggregates and returns benchmark information
+ * @returns {{summaries: Record<string, Object>, totalTime: number, lastCompleteCall: *}}
+ * An object with
+ * - `totalTime` - total time spent by decorated methods
+ * - `lastCompleteCall` - millisecond since launch the last call completed at
+ * - `summaries` - mapping of all captured stats: summaries.methodName -> method stats
+ */
+function getMetrics() {
+    const summaries = _.chain(performance.getEntriesByType('measure'))
+        .filter(entry => entry.detail && decoratedAliases.has(entry.detail.alias))
+        .groupBy(entry => entry.detail.alias)
+        .map((calls, methodName) => {
+            const total = sum(calls, 'duration');
+            const avg = (total / calls.length) || 0;
+            const max = _.max(calls, 'duration').duration || 0;
+            const min = _.min(calls, 'duration').duration || 0;
+
+            // Latest complete call (by end time) for all the calls made to the current method
+            const lastCall = _.max(calls, call => call.startTime + call.duration);
+
+            return [methodName, {
+                methodName,
+                total,
+                max,
+                min,
+                avg,
+                lastCall,
+                calls,
+            }];
+        })
+        .object() // Create a map like methodName -> StatSummary
+        .value();
+
+    const totalTime = sum(_.values(summaries), 'total');
+
+    // Latest complete call (by end time) of all methods up to this point
+    const lastCompleteCall = _.max(
+        _.values(summaries),
+        summary => summary.lastCall.startTime + summary.lastCall.duration,
+    ).lastCall;
+
+    return {
+        totalTime,
+        summaries,
+        lastCompleteCall,
+    };
+}
+
+/**
+ * Convert milliseconds to human readable time
+ * @param {number} millis
+ * @param {boolean} [raw=false]
+ * @returns {string|number}
+ */
+function toDuration(millis, raw = false) {
+    if (raw) {
+        return millis;
+    }
+
+    const minute = 60 * 1000;
+    if (millis > minute) {
+        return `${(millis / minute).toFixed(1)}min`;
+    }
+
+    const second = 1000;
+    if (millis > second) {
+        return `${(millis / second).toFixed(2)}sec`;
+    }
+
+    return `${millis.toFixed(3)}ms`;
+}
+
+/**
+ * Print extensive information on the dev console
+ * max, min, average, total time for each method
+ * and a table of individual calls
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.raw=false] - setting this to true will print raw instead of human friendly times
+ * Useful when you copy the printed table to excel and let excel do the number formatting
+ * @param {'console'|'csv'|'json'|'string'} [options.format=console] The output format of this function
+ * `string` is useful when __DEV__ is set to `false` as writing to the console is disabled, but the result of this
+ * method would still get printed as output
+ * @param {string[]} [options.methods] Print stats only for these method names
+ * @returns {string|undefined}
+ */
+function printMetrics({raw = false, format = 'console', methods} = {}) {
+    const {totalTime, summaries, lastCompleteCall} = getMetrics();
+
+    const tableSummary = MDTable.factory({
+        heading: ['method', 'total time spent', 'max', 'min', 'avg', 'time last call completed', 'calls made'],
+        leftAlignedCols: [0],
+    });
+
+    /* Performance marks (startTimes) are relative to system uptime
+     * timeOrigin is the point at which the app started to init
+     * We use timeOrigin to display times relative to app launch time
+     * See: https://github.com/oblador/react-native-performance/issues/50 */
+    const timeOrigin = performance.timeOrigin;
+    const methodNames = _.isArray(methods) ? methods : _.keys(summaries);
+
+    const methodCallTables = _.chain(methodNames)
+        .filter(methodName => summaries[methodName] && summaries[methodName].avg > 0)
+        .map((methodName) => {
+            const {calls, ...methodStats} = summaries[methodName];
+            tableSummary.addRow(
+                methodName,
+                toDuration(methodStats.total, raw),
+                toDuration(methodStats.max, raw),
+                toDuration(methodStats.min, raw),
+                toDuration(methodStats.avg, raw),
+                toDuration((methodStats.lastCall.startTime + methodStats.lastCall.duration) - timeOrigin, raw),
+                calls.length,
+            );
+
+            return MDTable.factory({
+                title: methodName,
+                heading: ['start time', 'end time', 'duration', 'args'],
+                leftAlignedCols: [3],
+                rows: calls.map(call => ([
+                    toDuration(call.startTime - performance.timeOrigin, raw),
+                    toDuration((call.startTime + call.duration) - timeOrigin, raw),
+                    toDuration(call.duration, raw),
+                    call.detail.args.map(String).join(', ').slice(0, 60), // Restrict cell width to 60 chars max
+                ]))
+            });
+        })
+        .value();
+
+    if (/csv|json|string/i.test(format)) {
+        const allTables = [tableSummary, ...methodCallTables];
+
+        return allTables.map((table) => {
+            switch (format.toLowerCase()) {
+                case 'csv':
+                    return table.toCSV();
+                case 'json':
+                    return table.toJSON();
+                default:
+                    return table.toString();
+            }
+        }).join('\n\n');
+    }
+
+    const lastComplete = lastCompleteCall && toDuration(
+        (lastCompleteCall.startTime + lastCompleteCall.duration) - timeOrigin, raw
+    );
+
+    const mainOutput = [
+        '### Onyx Benchmark',
+        `  - Total: ${toDuration(totalTime, raw)}`,
+        `  - Last call finished at: ${lastComplete || 'N/A'}`,
+        '',
+        tableSummary.toString()
+    ];
+
+    /* eslint-disable no-console */
+    console.info(mainOutput.join('\n'));
+    methodCallTables.forEach((table) => {
+        console.groupCollapsed(table.getTitle());
+        console.info(table.toString());
+        console.groupEnd();
+    });
+    /* eslint-enable */
+}
+
+/**
+ * Clears all collected metrics.
+ */
+function resetMetrics() {
+    const {summaries} = getMetrics();
+
+    _.chain(summaries)
+        .map(summary => summary.calls)
+        .flatten()
+        .each((measure) => {
+            performance.clearMarks(measure.detail.alias);
+            performance.clearMeasures(measure.name);
+        });
+}
+
+export {
+    decorateWithMetrics,
+    getMetrics,
+    resetMetrics,
+    printMetrics,
+};

package/lib/metrics/index.web.js

@@ -0,0 +1,13 @@
+// For web-only implementations of Onyx, this module will just be a no-op
+
+function decorateWithMetrics() {}
+function getMetrics() {}
+function printMetrics() {}
+function resetMetrics() {}
+
+export {
+    decorateWithMetrics,
+    getMetrics,
+    resetMetrics,
+    printMetrics,
+};

package/lib/storage/NativeStorage.js

@@ -0,0 +1,3 @@
+import Storage from './providers/AsyncStorage';
+
+export default Storage;

package/lib/storage/WebStorage.js

@@ -0,0 +1,56 @@
+import _ from 'underscore';
+import Storage from './providers/LocalForage';
+
+const SYNC_ONYX = 'SYNC_ONYX';
+
+/**
+ * Raise an event thorough `localStorage` to let other tabs know a value changed
+ * @param {String} onyxKey
+ */
+function raiseStorageSyncEvent(onyxKey) {
+    global.localStorage.setItem(SYNC_ONYX, onyxKey);
+    global.localStorage.removeItem(SYNC_ONYX, onyxKey);
+}
+
+const webStorage = {
+    ...Storage,
+
+    /**
+     * Contains keys for which we want to disable sync event across tabs.
+     * @param {String[]} keysToDisableSyncEvents
+     * Storage synchronization mechanism keeping all opened tabs in sync
+     * @param {function(key: String, data: *)} onStorageKeyChanged
+     */
+    keepInstancesSync(keysToDisableSyncEvents, onStorageKeyChanged) {
+        // Override set, remove and clear to raise storage events that we intercept in other tabs
+        this.setItem = (key, value) => Storage.setItem(key, value)
+            .then(() => raiseStorageSyncEvent(key));
+
+        this.removeItem = key => Storage.removeItem(key)
+            .then(() => raiseStorageSyncEvent(key));
+
+        // If we just call Storage.clear other tabs will have no idea which keys were available previously
+        // so that they can call keysChanged for them. That's why we iterate and remove keys one by one
+        this.clear = () => Storage.getAllKeys()
+            .then(keys => _.map(keys, key => this.removeItem(key)))
+            .then(tasks => Promise.all(tasks));
+
+        // This listener will only be triggered by events coming from other tabs
+        global.addEventListener('storage', (event) => {
+            // Ignore events that don't originate from the SYNC_ONYX logic
+            if (event.key !== SYNC_ONYX || !event.newValue) {
+                return;
+            }
+
+            const onyxKey = event.newValue;
+            if (_.contains(keysToDisableSyncEvents, onyxKey)) {
+                return;
+            }
+
+            Storage.getItem(onyxKey)
+                .then(value => onStorageKeyChanged(onyxKey, value));
+        });
+    },
+};
+
+export default webStorage;

package/lib/storage/__mocks__/index.native.js

@@ -0,0 +1,8 @@
+/**
+ * Because we're using the `react-native` preset of jest this file extension
+ * is .native.js. Otherwise, since jest prefers index.native.js over index.js
+ * it'll skip loading the mock
+ */
+import WebStorage from '../WebStorage';
+
+export default WebStorage;

package/lib/storage/index.native.js

@@ -0,0 +1,8 @@
+import {Platform} from 'react-native';
+
+const Storage = Platform.select({
+    default: () => require('./WebStorage').default,
+    native: () => require('./NativeStorage').default,
+})();
+
+export default Storage;

package/lib/storage/index.web.js

@@ -0,0 +1,3 @@
+import WebStorage from './WebStorage';
+
+export default WebStorage;