react-native-onyx 1.0.1

package/lib/storage/providers/AsyncStorage.js

@@ -0,0 +1,83 @@
+/**
+ * The AsyncStorage provider stores everything in a key/value store by
+ * converting the value to a JSON string
+ */
+
+import _ from 'underscore';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const provider = {
+    /**
+     * Get the value of a given key or return `null` if it's not available in storage
+     * @param {String} key
+     * @return {Promise<*>}
+     */
+    getItem(key) {
+        return AsyncStorage.getItem(key)
+            .then((value) => {
+                const parsed = value && JSON.parse(value);
+                return parsed;
+            });
+    },
+
+    /**
+     * Get multiple key-value pairs for the give array of keys in a batch
+     * @param {String[]} keys
+     * @return {Promise<Array<[key, value]>>}
+     */
+    multiGet(keys) {
+        return AsyncStorage.multiGet(keys)
+            .then(pairs => _.map(pairs, ([key, value]) => [key, value && JSON.parse(value)]));
+    },
+
+    /**
+     * Sets the value for a given key. The only requirement is that the value should be serializable to JSON string
+     * @param {String} key
+     * @param {*} value
+     * @return {Promise<void>}
+     */
+    setItem(key, value) {
+        return AsyncStorage.setItem(key, JSON.stringify(value));
+    },
+
+    /**
+     * Stores multiple key-value pairs in a batch
+     * @param {Array<[key, value]>} pairs
+     * @return {Promise<void>}
+     */
+    multiSet(pairs) {
+        const stringPairs = _.map(pairs, ([key, value]) => [key, JSON.stringify(value)]);
+        return AsyncStorage.multiSet(stringPairs);
+    },
+
+    /**
+     * Multiple merging of existing and new values in a batch
+     * @param {Array<[key, value]>} pairs
+     * @return {Promise<void>}
+     */
+    multiMerge(pairs) {
+        const stringPairs = _.map(pairs, ([key, value]) => [key, JSON.stringify(value)]);
+        return AsyncStorage.multiMerge(stringPairs);
+    },
+
+    /**
+     * Returns all keys available in storage
+     * @returns {Promise<String[]>}
+     */
+    getAllKeys: AsyncStorage.getAllKeys,
+
+    /**
+     * Remove given key and it's value from storage
+     * @param {String} key
+     * @returns {Promise<void>}
+     */
+    removeItem: AsyncStorage.removeItem,
+
+    /**
+     * Clear absolutely everything from storage
+     * @returns {Promise<void>}
+     */
+    clear: AsyncStorage.clear,
+};
+
+export default provider;

package/lib/storage/providers/LocalForage.js

@@ -0,0 +1,111 @@
+/**
+ * @file
+ * The storage provider based on localforage allows us to store most anything in its
+ * natural form in the underlying DB without having to stringify or de-stringify it
+ */
+
+import localforage from 'localforage';
+import _ from 'underscore';
+import lodashMerge from 'lodash/merge';
+import SyncQueue from '../../SyncQueue';
+
+localforage.config({
+    name: 'OnyxDB'
+});
+
+const provider = {
+    /**
+     * Writing very quickly to IndexedDB causes performance issues and can lock up the page and lead to jank.
+     * So, we are slowing this process down by waiting until one write is complete before moving on
+     * to the next.
+     */
+    setItemQueue: new SyncQueue(({key, value, shouldMerge}) => {
+        if (shouldMerge) {
+            return localforage.getItem(key)
+                .then((existingValue) => {
+                    const newValue = _.isObject(existingValue)
+                        ? lodashMerge({}, existingValue, value)
+                        : value;
+                    return localforage.setItem(key, newValue);
+                });
+        }
+
+        return localforage.setItem(key, value);
+    }),
+
+    /**
+     * Get multiple key-value pairs for the give array of keys in a batch
+     * @param {String[]} keys
+     * @return {Promise<Array<[key, value]>>}
+     */
+    multiGet(keys) {
+        const pairs = _.map(
+            keys,
+            key => localforage.getItem(key)
+                .then(value => [key, value])
+        );
+
+        return Promise.all(pairs);
+    },
+
+    /**
+     * Multiple merging of existing and new values in a batch
+     * @param {Array<[key, value]>} pairs
+     * @return {Promise<void>}
+     */
+    multiMerge(pairs) {
+        const tasks = _.map(pairs, ([key, value]) => this.setItemQueue.push({key, value, shouldMerge: true}));
+
+        // We're returning Promise.resolve, otherwise the array of task results will be returned to the caller
+        return Promise.all(tasks).then(() => Promise.resolve());
+    },
+
+    /**
+     * Stores multiple key-value pairs in a batch
+     * @param {Array<[key, value]>} pairs
+     * @return {Promise<void>}
+     */
+    multiSet(pairs) {
+        // We're returning Promise.resolve, otherwise the array of task results will be returned to the caller
+        const tasks = _.map(pairs, ([key, value]) => this.setItem(key, value));
+        return Promise.all(tasks).then(() => Promise.resolve());
+    },
+
+    /**
+     * Clear absolutely everything from storage
+     * @returns {Promise<void>}
+     */
+    clear: localforage.clear,
+
+    /**
+     * Returns all keys available in storage
+     * @returns {Promise<String[]>}
+     */
+    getAllKeys: localforage.keys,
+
+    /**
+     * Get the value of a given key or return `null` if it's not available in storage
+     * @param {String} key
+     * @return {Promise<*>}
+     */
+    getItem: localforage.getItem,
+
+    /**
+     * Remove given key and it's value from storage
+     * @param {String} key
+     * @returns {Promise<void>}
+     */
+    removeItem: localforage.removeItem,
+
+    /**
+     * Sets the value for a given key. The only requirement is that the value should be serializable to JSON string
+     * @param {String} key
+     * @param {*} value
+     * @return {Promise<void>}
+     */
+    setItem(key, value) {
+        return this.setItemQueue.push({key, value});
+    },
+};
+
+export default provider;

package/lib/withOnyx.js

@@ -0,0 +1,200 @@
+/**
+ * This is a higher order component that provides the ability to map a state property directly to
+ * something in Onyx (a key/value store). That way, as soon as data in Onyx changes, the state will be set and the view
+ * will automatically change to reflect the new data.
+ */
+import React from 'react';
+import _ from 'underscore';
+import PropTypes from 'prop-types';
+import Str from 'expensify-common/lib/str';
+import Onyx from './Onyx';
+
+/**
+ * Returns the display name of a component
+ *
+ * @param {object} component
+ * @returns {string}
+ */
+function getDisplayName(component) {
+    return component.displayName || component.name || 'Component';
+}
+
+export default function (mapOnyxToState) {
+    // A list of keys that must be present in tempState before we can render the WrappedComponent
+    const requiredKeysForInit = _.chain(mapOnyxToState)
+        .omit(config => config.initWithStoredValues === false)
+        .keys()
+        .value();
+
+    return (WrappedComponent) => {
+        class withOnyx extends React.Component {
+            constructor(props) {
+                super(props);
+
+                this.setWithOnyxState = this.setWithOnyxState.bind(this);
+
+                // This stores all the Onyx connection IDs to be used when the component unmounts so everything can be
+                // disconnected. It is a key value store with the format {[mapping.key]: connectionID}.
+                this.activeConnectionIDs = {};
+
+                // Object holding the temporary initial state for the component while we load the various Onyx keys
+                this.tempState = {};
+
+                this.state = {
+                    // If there are no required keys for init then we can render the wrapped component immediately
+                    loading: requiredKeysForInit.length > 0,
+                };
+            }
+
+            componentDidMount() {
+                // Subscribe each of the state properties to the proper Onyx key
+                _.each(mapOnyxToState, (mapping, propertyName) => {
+                    this.connectMappingToOnyx(mapping, propertyName);
+                });
+                this.checkEvictableKeys();
+            }
+
+            componentDidUpdate(prevProps) {
+                // If any of the mappings use data from the props, then when the props change, all the
+                // connections need to be reconnected with the new props
+                _.each(mapOnyxToState, (mapping, propertyName) => {
+                    const previousKey = Str.result(mapping.key, prevProps);
+                    const newKey = Str.result(mapping.key, this.props);
+
+                    if (previousKey !== newKey) {
+                        Onyx.disconnect(this.activeConnectionIDs[previousKey], previousKey);
+                        delete this.activeConnectionIDs[previousKey];
+                        this.connectMappingToOnyx(mapping, propertyName);
+                    }
+                });
+                this.checkEvictableKeys();
+            }
+
+            componentWillUnmount() {
+                // Disconnect everything from Onyx
+                _.each(mapOnyxToState, (mapping) => {
+                    const key = Str.result(mapping.key, this.props);
+                    const connectionID = this.activeConnectionIDs[key];
+                    Onyx.disconnect(connectionID, key);
+                });
+            }
+
+            /**
+             * This method is used externally by sendDataToConnection to prevent unnecessary renders while a component
+             * still in a loading state. The temporary initial state is saved to the component instance and setState()
+             * only called once all the necessary data has been collected.
+             *
+             * @param {String} statePropertyName
+             * @param {*} val
+             */
+            setWithOnyxState(statePropertyName, val) {
+                if (!this.state.loading) {
+                    this.setState({[statePropertyName]: val});
+                    return;
+                }
+
+                this.tempState[statePropertyName] = val;
+
+                // All state keys should exist and at least have a value of null
+                if (_.some(requiredKeysForInit, key => _.isUndefined(this.tempState[key]))) {
+                    return;
+                }
+
+                this.setState({...this.tempState, loading: false});
+                delete this.tempState;
+            }
+
+            /**
+             * Makes sure each Onyx key we requested has been set to state with a value of some kind.
+             * We are doing this so that the wrapped component will only render when all the data
+             * it needs is available to it.
+             */
+            checkEvictableKeys() {
+                // We will add this key to our list of recently accessed keys
+                // if the canEvict function returns true. This is necessary criteria
+                // we MUST use to specify if a key can be removed or not.
+                _.each(mapOnyxToState, (mapping) => {
+                    if (_.isUndefined(mapping.canEvict)) {
+                        return;
+                    }
+
+                    const canEvict = Str.result(mapping.canEvict, this.props);
+                    const key = Str.result(mapping.key, this.props);
+
+                    if (!Onyx.isSafeEvictionKey(key)) {
+                        // eslint-disable-next-line max-len
+                        throw new Error(`canEvict cannot be used on key '${key}'. This key must explicitly be flagged as safe for removal by adding it to Onyx.init({safeEvictionKeys: []}).`);
+                    }
+
+                    if (canEvict) {
+                        Onyx.removeFromEvictionBlockList(key, mapping.connectionID);
+                    } else {
+                        Onyx.addToEvictionBlockList(key, mapping.connectionID);
+                    }
+                });
+            }
+
+            /**
+             * Takes a single mapping and binds the state of the component to the store
+             *
+             * @param {object} mapping
+             * @param {string|function} mapping.key key to connect to. can be a string or a
+             * function that takes this.props as an argument and returns a string
+             * @param {string} statePropertyName the name of the state property that Onyx will add the data to
+             * @param {boolean} [mapping.initWithStoredValues] If set to false, then no data will be prefilled into the
+             *  component
+             */
+            connectMappingToOnyx(mapping, statePropertyName) {
+                const key = Str.result(mapping.key, this.props);
+
+                this.activeConnectionIDs[key] = Onyx.connect({
+                    ...mapping,
+                    key,
+                    statePropertyName,
+                    withOnyxInstance: this,
+                });
+            }
+
+            render() {
+                if (this.state.loading) {
+                    return null;
+                }
+
+                // Remove any internal state properties used by withOnyx
+                // that should not be passed to a wrapped component
+                let stateToPass = _.omit(this.state, 'loading');
+                stateToPass = _.omit(stateToPass, value => _.isNull(value));
+
+                // Remove any null values so that React replaces them with default props
+                const propsToPass = _.omit(this.props, value => _.isNull(value));
+
+                // Spreading props and state is necessary in an HOC where the data cannot be predicted
+                return (
+                    <WrappedComponent
+                        // eslint-disable-next-line react/jsx-props-no-spreading
+                        {...propsToPass}
+                        // eslint-disable-next-line react/jsx-props-no-spreading
+                        {...stateToPass}
+                        ref={this.props.forwardedRef}
+                    />
+                );
+            }
+        }
+
+        withOnyx.propTypes = {
+            forwardedRef: PropTypes.oneOfType([
+                PropTypes.func,
+                PropTypes.shape({current: PropTypes.instanceOf(React.Component)}),
+            ]),
+        };
+        withOnyx.defaultProps = {
+            forwardedRef: undefined,
+        };
+        withOnyx.displayName = `withOnyx(${getDisplayName(WrappedComponent)})`;
+        return React.forwardRef((props, ref) => {
+            const Component = withOnyx;
+            // eslint-disable-next-line react/jsx-props-no-spreading
+            return <Component {...props} forwardedRef={ref} />;
+        });
+    };
+}

package/native.js

@@ -0,0 +1,11 @@
+/**
+ * @file
+ * Native entry point for Onyx
+ * This file is resolved by react-native projects
+ */
+import Onyx from './lib';
+
+// We resolve pure source for react-native projects and let `metro` bundle it
+// We can test small changes directly from the parent project `node_modules/react-native-onyx` source
+export * from './lib';
+export default Onyx;

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "react-native-onyx",
+  "version": "1.0.1",
+  "author": "Expensify, Inc.",
+  "homepage": "https://expensify.com",
+  "description": "State management for React Native",
+  "license": "MIT",
+  "private": false,
+  "files": [
+    "dist/**/*",
+    "lib/**/*",
+    "native.js",
+    "web.js",
+    "API.md",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "react-native": "native.js",
+  "main": "native.js",
+  "browser": "web.js",
+  "scripts": {
+    "lint": "eslint .",
+    "lint-tests": "eslint tests/**",
+    "test": "jest",
+    "build:web": "webpack --config webpack.config.js",
+    "build:docs": "node buildDocs.js"
+  },
+  "dependencies": {
+    "ascii-table": "0.0.9",
+    "lodash": "^4.17.21",
+    "underscore": "^1.13.1"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.17.10",
+    "@babel/plugin-proposal-class-properties": "^7.16.7",
+    "@babel/runtime": "^7.11.2",
+    "@react-native-async-storage/async-storage": "^1.15.5",
+    "@react-native-community/eslint-config": "^2.0.0",
+    "@testing-library/jest-native": "^3.4.2",
+    "@testing-library/react-native": "^7.0.2",
+    "babel-eslint": "^10.1.0",
+    "babel-jest": "^26.2.2",
+    "babel-loader": "^8.2.5",
+    "babel-plugin-module-resolver": "^4.0.0",
+    "babel-plugin-react-native-web": "^0.13.5",
+    "babel-plugin-transform-class-properties": "^6.24.1",
+    "eslint": "^7.6.0",
+    "eslint-config-expensify": "^2.0.11",
+    "expensify-common": "git+https://github.com/Expensify/expensify-common.git#427295da130a4eacc184d38693664280d020dffd",
+    "jest": "^26.5.2",
+    "jest-cli": "^26.5.2",
+    "jsdoc-to-markdown": "^7.1.0",
+    "localforage": "^1.10.0",
+    "metro-react-native-babel-preset": "^0.61.0",
+    "prop-types": "^15.7.2",
+    "react": "^17.0.2",
+    "react-native": "0.64.1",
+    "react-native-performance": "^2.0.0",
+    "react-test-renderer": "16.13.1",
+    "webpack": "^5.72.1",
+    "webpack-cli": "^4.9.2",
+    "webpack-merge": "^5.8.0"
+  },
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": "^1.15.5",
+    "expensify-common": ">=1",
+    "localforage": "^1.10.0",
+    "react": ">=17.0.2",
+    "react-native-performance": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native-performance": {
+      "optional": true
+    },
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    },
+    "localforage": {
+      "optional": true
+    }
+  },
+  "jest": {
+    "preset": "react-native",
+    "transform": {
+      "^.+\\.jsx?$": "babel-jest"
+    },
+    "transformIgnorePatterns": [
+      "node_modules/(?!react-native)/"
+    ],
+    "testPathIgnorePatterns": [
+      "<rootDir>/node_modules/",
+      "<rootDir>/tests/unit/mocks/"
+    ],
+    "testMatch": [
+      "**/tests/unit/**/*.[jt]s?(x)",
+      "**/?(*.)+(spec|test).[jt]s?(x)"
+    ],
+    "globals": {
+      "__DEV__": true,
+      "WebSocket": {}
+    },
+    "timers": "fake",
+    "testEnvironment": "jsdom",
+    "setupFilesAfterEnv": [
+      "@testing-library/jest-native/extend-expect"
+    ]
+  },
+  "sideEffects": false
+}

package/web.js

@@ -0,0 +1,12 @@
+/**
+ * @file
+ * Web entry point for Onyx
+ * This file is resolved by non react-native projects
+ * Like React for web or pure JS
+ */
+
+if (process.env.NODE_ENV === 'production') {
+    module.exports = require('./dist/web.min.js');
+} else {
+    module.exports = require('./dist/web.development.js');
+}