Computed values

Author: janicduplessis

lib/Onyx.js

@@ -34,6 +34,9 @@ let lastConnectionID = 0;
 // Holds a mapping of all the react components that want their state subscribed to a store key
 const callbackToStateMapping = {};
 
+// Holds a mapping of cache keys to their dependencies. This is used to invalidate computed keys.
+const dependentCacheKeys = {};
+
 // Keeps a copy of the values of the onyx collection keys as a map for faster lookups
 let onyxCollectionKeyMap = new Map();
 
@@ -143,6 +146,16 @@ const reduceCollectionWithSelector = (collection, selector, withOnyxInstanceStat
         {},
     );
 
+/**
+ * Returns if the key is a computed key.
+ *
+ * @param {Mixed} key
+ * @returns {boolean}
+ */
+function isComputedKey(key) {
+    return typeof key === 'object' && 'compute' in key;
+}
+
 /**
  * Get some data from the store
  *
@@ -248,6 +261,10 @@ function isSafeEvictionKey(testKey) {
     return _.some(evictionAllowList, (key) => isKeyMatch(key, testKey));
 }
 
+function getCacheKey(key) {
+    return isComputedKey(key) ? key.cacheKey : key;
+}
+
 /**
  * Tries to get a value from the cache. If the value is not present in cache it will return the default value or undefined.
  * If the requested key is a collection, it will return an object with all the collection members.
@@ -257,6 +274,30 @@ function isSafeEvictionKey(testKey) {
  * @returns {Mixed}
  */
 function tryGetCachedValue(key, mapping = {}) {
+    if (isComputedKey(key)) {
+        // Check if we have the value in cache already.
+        let val = cache.getValue(key.cacheKey);
+        if (val !== undefined) {
+            return val;
+        }
+
+        // Check if we can compute the value if all dependencies are in cache.
+        const dependencies = _.mapObject(key.dependencies || {}, (dependencyKey) =>
+            tryGetCachedValue(
+                dependencyKey,
+                // TODO: We could support full mapping here.
+                {key: dependencyKey},
+            ),
+        );
+        if (_.all(dependencies, (dependency) => dependency !== undefined)) {
+            val = key.compute(dependencies);
+            cache.set(key.cacheKey, val);
+            return val;
+        }
+
+        return undefined;
+    }
+
     let val = cache.getValue(key);
 
     if (isCollectionKey(key)) {
@@ -404,6 +445,19 @@ function getCachedCollection(collectionKey) {
     );
 }
 
+function clearComputedCacheForKey(key) {
+    const dependentKeys = dependentCacheKeys[key];
+    if (!dependentKeys) {
+        return;
+    }
+
+    dependentKeys.forEach((dependentKey) => {
+        cache.drop(dependentKey);
+
+        clearComputedCacheForKey(dependentKey);
+    });
+}
+
 /**
  * When a collection of keys change, search for any callbacks matching the collection key and trigger those callbacks
  *
@@ -414,6 +468,8 @@ function getCachedCollection(collectionKey) {
  * @param {boolean} [notifyWithOnyxSubscibers=true]
  */
 function keysChanged(collectionKey, partialCollection, notifyRegularSubscibers = true, notifyWithOnyxSubscibers = true) {
+    clearComputedCacheForKey(collectionKey);
+
     // We are iterating over all subscribers similar to keyChanged(). However, we are looking for subscribers who are subscribing to either a collection key or
     // individual collection key member for the collection that is being updated. It is important to note that the collection parameter cane be a PARTIAL collection
     // and does not represent all of the combined keys and values for a collection key. It is just the "new" data that was merged in via mergeCollection().
@@ -590,6 +646,8 @@ function keyChanged(key, data, canUpdateSubscriber, notifyRegularSubscibers = tr
         removeLastAccessedKey(key);
     }
 
+    clearComputedCacheForKey(key);
+
     // We are iterating over all subscribers to see if they are interested in the key that has just changed. If the subscriber's  key is a collection key then we will
     // notify them if the key that changed is a collection member. Or if it is a regular key notify them when there is an exact match. Depending on whether the subscriber
     // was connected via withOnyx we will call setState() directly on the withOnyx instance. If it is a regular connection we will pass the data to the provided callback.
@@ -773,7 +831,7 @@ function addKeyToRecentlyAccessedIfNeeded(mapping) {
             throw new Error(`Cannot subscribe to safe eviction key '${mapping.key}' without providing a canEvict value.`);
         }
 
-        addLastAccessedKey(mapping.key);
+        addLastAccessedKey(getCacheKey(mapping.key));
     }
 }
 
@@ -800,6 +858,15 @@ function getCollectionDataAndSendAsObject(matchingKeys, mapping) {
         .then((val) => sendDataToConnection(mapping, val, undefined, true));
 }
 
+function computeAndSendData(mapping, dependencies) {
+    let val = cache.getValue(mapping.key.cacheKey);
+    if (val === undefined) {
+        val = mapping.key.compute(dependencies);
+        cache.set(mapping.key.cacheKey, val);
+    }
+    sendDataToConnection(mapping, val, mapping.key.cacheKey, true);
+}
+
 /**
  * Subscribes a react component's state directly to a store key
  *
@@ -833,6 +900,48 @@ function connect(mapping) {
     callbackToStateMapping[connectionID] = mapping;
     callbackToStateMapping[connectionID].connectionID = connectionID;
 
+    if (isComputedKey(mapping.key)) {
+        deferredInitTask.promise
+            .then(() => addKeyToRecentlyAccessedIfNeeded(mapping))
+            .then(() => {
+                const mappingDependencies = mapping.key.dependencies || {};
+                const dependenciesCount = _.size(mappingDependencies);
+                if (dependenciesCount === 0) {
+                    // If we have no dependencies we can send the computed value immediately.
+                    computeAndSendData(mapping, {});
+                } else {
+                    callbackToStateMapping[connectionID].dependencyConnections = [];
+
+                    const dependencies = {};
+                    _.each(mappingDependencies, (dependency, mappingKey) => {
+                        // Create a mapping of dependent cache keys so when a key changes, all dependent keys
+                        // can also be cleared from the cache.
+                        const cacheKey = getCacheKey(dependency);
+                        dependentCacheKeys[cacheKey] = dependentCacheKeys[cacheKey] || new Set();
+                        dependentCacheKeys[cacheKey].add(mapping.key.cacheKey);
+
+                        // Connect to dependencies.
+                        const dependencyConnection = connect({
+                            key: dependency,
+                            waitForCollectionCallback: true,
+                            callback: (value) => {
+                                dependencies[mappingKey] = value;
+
+                                // Once all dependencies are ready, compute the value and send it to the connection.
+                                if (_.size(dependencies) === dependenciesCount) {
+                                    computeAndSendData(mapping, dependencies);
+                                }
+                            },
+                        });
+
+                        // Store dependency connections so we can disconnect them later.
+                        callbackToStateMapping[connectionID].dependencyConnections.push(dependencyConnection);
+                    });
+                }
+            });
+        return connectionID;
+    }
+
     if (mapping.initWithStoredValues === false) {
         return connectionID;
     }
@@ -932,6 +1041,10 @@ function disconnect(connectionID, keyToRemoveFromEvictionBlocklist) {
         removeFromEvictionBlockList(keyToRemoveFromEvictionBlocklist, connectionID);
     }
 
+    if (callbackToStateMapping[connectionID].dependencyConnections) {
+        callbackToStateMapping[connectionID].dependencyConnections.forEach((id) => disconnect(id));
+    }
+
     delete callbackToStateMapping[connectionID];
 }
 
@@ -1724,6 +1837,7 @@ const Onyx = {
     isClientManagerReady: ActiveClientManager.isReady,
     isClientTheLeader: ActiveClientManager.isClientTheLeader,
     subscribeToClientChange: ActiveClientManager.subscribeToClientChange,
+    getCacheKey,
 };
 
 /**

lib/index.d.ts

@@ -1,6 +1,6 @@
 import Onyx, {OnyxUpdate, ConnectOptions} from './Onyx';
-import {CustomTypeOptions, OnyxCollection, OnyxEntry} from './types';
+import {CustomTypeOptions, OnyxCollection, OnyxEntry, ComputedKey} from './types';
 import withOnyx from './withOnyx';
 
 export default Onyx;
-export {CustomTypeOptions, OnyxCollection, OnyxEntry, OnyxUpdate, withOnyx, ConnectOptions};
+export {CustomTypeOptions, OnyxCollection, OnyxEntry, OnyxUpdate, withOnyx, ConnectOptions, ComputedKey};

lib/types.d.ts

@@ -99,6 +99,26 @@ type CollectionKey = `${CollectionKeyBase}${string}`;
  */
 type OnyxKey = Key | CollectionKey;
 
+/**
+ * A computed key is a key that is not stored in the database, but instead is computed from other keys
+ * and cached in memory. This is useful for expensive computations that are used in multiple places.
+ */
+type ComputedKey<DependenciesT, ValueT> = {
+    /**
+     * The cache key of the computed value.
+     */
+    cacheKey: string;
+    /**
+     * Keys that this computed key depends on. The values of these keys will be passed to the compute function.
+     * This will also cause the key to be recomputed whenever any of the dependencies value change.
+     */
+    dependencies?: {[KeyT in keyof DependenciesT]: OnyxKey | ComputedKey<any, unknown>};
+    /**
+     * Compute the value for this computed key.
+     */
+    compute: (params: DependenciesT) => ValueT;
+};
+
 /**
  * Represents a mapping of Onyx keys to values, where keys are either normal or collection Onyx keys
  * and values are the corresponding values in Onyx's state.
@@ -226,4 +246,4 @@ type NullishObjectDeep<ObjectType extends object> = {
  */
 type WithOnyxInstanceState<TOnyxProps> = (TOnyxProps & {loading: boolean}) | undefined;
 
-export {CollectionKey, CollectionKeyBase, CustomTypeOptions, DeepRecord, Key, KeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, Selector, NullishDeep, WithOnyxInstanceState};
+export {CollectionKey, CollectionKeyBase, ComputedKey, CustomTypeOptions, DeepRecord, Key, KeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, Selector, NullishDeep, WithOnyxInstanceState};

lib/withOnyx.d.ts

@@ -1,5 +1,5 @@
 import {IsEqual} from 'type-fest';
-import {CollectionKeyBase, KeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, Selector} from './types';
+import {CollectionKeyBase, ComputedKey, KeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, Selector} from './types';
 
 /**
  * Represents the base mapping options between an Onyx key and the component's prop.
@@ -86,6 +86,25 @@ type BaseMappingFunctionKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp ex
     selector: Selector<TOnyxKey, TOnyxProps, TOnyxProps[TOnyxProp]>;
 };
 
+/**
+ * TODO
+ *
+ * @example
+ * ```ts
+ * // Onyx prop with computed key.
+ * accountName: {
+ *     key: {
+ *         cacheKey: ONYXKEYS.COMPUTED.ACCOUNT_NAME,
+ *         dependencies: {account: ONYXKEYS.ACCOUNT},
+ *         compute: ({account}) => account.name,
+ *     },
+ * },
+ * ```
+ */
+type BaseMappingComputedKey<TComponentProps, TOnyxProps, TOnyxProp extends keyof TOnyxProps> = {
+    key: ComputedKey<any, TOnyxProps[TOnyxProp]> | ((props: Omit<TComponentProps, keyof TOnyxProps> & Partial<TOnyxProps>) => ComputedKey<any, TOnyxProps[TOnyxProp]>);
+};
+
 /**
  * Represents the mapping options between an Onyx key and the component's prop with all its possibilities.
  */
@@ -95,6 +114,7 @@ type Mapping<TComponentProps, TOnyxProps, TOnyxProp extends keyof TOnyxProps, TO
         | BaseMappingKey<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey, OnyxEntry<KeyValueMapping[TOnyxKey]>>
         | BaseMappingStringKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>
         | BaseMappingFunctionKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>
+        | BaseMappingComputedKey<TComponentProps, TOnyxProps, TOnyxProp>
     );
 
 /**
@@ -106,6 +126,7 @@ type CollectionMapping<TComponentProps, TOnyxProps, TOnyxProp extends keyof TOny
         | BaseMappingKey<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey, OnyxCollection<KeyValueMapping[TOnyxKey]>>
         | BaseMappingStringKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>
         | BaseMappingFunctionKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>
+        | BaseMappingComputedKey<TComponentProps, TOnyxProps, TOnyxProp>
     );
 
 /**

lib/withOnyx.js

@@ -128,8 +128,8 @@ export default function (mapOnyxToState, shouldDelayUpdates = false) {
                     // (eg. if a user switches chats really quickly). In this case, it's much more stable to always look at the changes to prevProp and prevState to derive the key.
                     // The second case cannot be used all the time because the onyx data doesn't change the first time that `componentDidUpdate()` runs after loading. In this case,
                     // the `mapping.previousKey` must be used for the comparison or else this logic never detects that onyx data could have changed during the loading process.
-                    const previousKey = isFirstTimeUpdatingAfterLoading ? mapping.previousKey : Str.result(mapping.key, {...prevProps, ...prevOnyxDataFromState});
-                    const newKey = Str.result(mapping.key, {...this.props, ...onyxDataFromState});
+                    const previousKey = Onyx.getCacheKey(isFirstTimeUpdatingAfterLoading ? mapping.previousKey : Str.result(mapping.key, {...prevProps, ...prevOnyxDataFromState}));
+                    const newKey = Onyx.getCacheKey(Str.result(mapping.key, {...this.props, ...onyxDataFromState}));
                     if (previousKey !== newKey) {
                         Onyx.disconnect(this.activeConnectionIDs[previousKey], previousKey);
                         delete this.activeConnectionIDs[previousKey];

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "1.0.127",
+  "version": "1.0.128",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",