Implement useOnyx hook

.eslintrc.js

@@ -67,6 +67,7 @@ module.exports = {
                         tsx: 'never',
                     },
                 ],
+                'rulesdir/prefer-onyx-connect-in-libs': 'off',
             },
         },
         {

lib/Onyx.d.ts

@@ -1,6 +1,6 @@
 import {Component} from 'react';
 import * as Logger from './Logger';
-import {CollectionKey, CollectionKeyBase, DeepRecord, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey} from './types';
+import {CollectionKey, CollectionKeyBase, DeepRecord, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, Selector} from './types';
 
 /**
  * Represents a mapping object where each `OnyxKey` maps to either a value of its corresponding type in `KeyValueMapping` or `null`.
@@ -20,6 +20,11 @@ type BaseConnectOptions = {
     initWithStoredValues?: boolean;
 };
 
+type TryGetCachedValueMapping<TKey extends OnyxKey> = {
+    selector?: Selector<TKey, unknown, unknown>;
+    withOnyxInstance?: Component;
+};
+
 /**
  * Represents the options used in `Onyx.connect()` method.
  * The type is built from `BaseConnectOptions` and extended to handle key/callback related options.
@@ -35,7 +40,7 @@ type BaseConnectOptions = {
 type ConnectOptions<TKey extends OnyxKey> = BaseConnectOptions &
     (
         | {
-              key: TKey extends CollectionKey ? TKey : never;
+              key: TKey extends CollectionKeyBase ? TKey : never;
               callback?: (value: OnyxCollection<KeyValueMapping[TKey]>) => void;
               waitForCollectionCallback: true;
           }
@@ -115,6 +120,21 @@ declare const METHOD: {
  */
 declare function getAllKeys(): Promise<Array<OnyxKey>>;
 
+/**
+ * Checks to see if the a subscriber's supplied key
+ * is associated with a collection of keys.
+ */
+declare function isCollectionKey(key: OnyxKey): key is CollectionKeyBase;
+
+declare function isCollectionMemberKey<TCollectionKey extends CollectionKeyBase>(collectionKey: TCollectionKey, key: string): key is `${TCollectionKey}${string}`;
+
+/**
+ * Splits a collection member key into the collection key part and the ID part.
+ * @param key - The collection member key to split.
+ * @returns A tuple where the first element is the collection part and the second element is the ID part.
+ */
+declare function splitCollectionMemberKey<TKey extends CollectionKey>(key: TKey): [TKey extends `${infer Prefix}_${string}` ? `${Prefix}_` : never, string];
+
 /**
  * Checks to see if this key has been flagged as
  * safe for removal.
@@ -291,6 +311,15 @@ declare function hasPendingMergeForKey(key: OnyxKey): boolean;
  */
 declare function setMemoryOnlyKeys(keyList: OnyxKey[]): void;
 
+/**
+ * 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.
+ */
+declare function tryGetCachedValue<TKey extends OnyxKey>(
+    key: TKey,
+    mapping?: TryGetCachedValueMapping,
+): TKey extends CollectionKeyBase ? OnyxCollection<KeyValueMapping[TKey]> | undefined : OnyxEntry<KeyValueMapping[TKey]> | undefined;
+
 declare const Onyx: {
     connect: typeof connect;
     disconnect: typeof disconnect;
@@ -309,7 +338,11 @@ declare const Onyx: {
     isSafeEvictionKey: typeof isSafeEvictionKey;
     METHOD: typeof METHOD;
     setMemoryOnlyKeys: typeof setMemoryOnlyKeys;
+    tryGetCachedValue: typeof tryGetCachedValue;
+    isCollectionKey: typeof isCollectionKey;
+    isCollectionMemberKey: typeof isCollectionMemberKey;
+    splitCollectionMemberKey: typeof splitCollectionMemberKey;
 };
 
 export default Onyx;
-export {OnyxUpdate, ConnectOptions};
+export {ConnectOptions, OnyxUpdate};

lib/Onyx.js

@@ -196,7 +196,6 @@ function getAllKeys() {
  * Checks to see if the a subscriber's supplied key
  * is associated with a collection of keys.
  *
- * @private
  * @param {String} key
  * @returns {Boolean}
  */
@@ -213,6 +212,21 @@ function isCollectionMemberKey(collectionKey, key) {
     return Str.startsWith(key, collectionKey) && key.length > collectionKey.length;
 }
 
+/**
+ * Splits a collection member key into the collection key part and the ID part.
+ * @param {String} key - The collection member key to split.
+ * @returns {[String, String]} A tuple where the first element is the collection part and the second element is the ID part.
+ */
+function splitCollectionMemberKey(key) {
+    const underscoreIndex = key.indexOf('_');
+
+    if (underscoreIndex === -1) {
+        throw new Error(`Invalid ${key} key provided, only collection keys are allowed.`);
+    }
+
+    return [key.substring(0, underscoreIndex + 1), key.substring(underscoreIndex + 1)];
+}
+
 /**
  * Checks to see if a provided key is the exact configured key of our connected subscriber
  * or if the provided key is a collection member key (in case our configured key is a "collection key")
@@ -1630,6 +1644,9 @@ const Onyx = {
     setMemoryOnlyKeys,
     tryGetCachedValue,
     hasPendingMergeForKey,
+    isCollectionKey,
+    isCollectionMemberKey,
+    splitCollectionMemberKey,
 };
 
 /**

lib/index.d.ts

@@ -1,6 +1,22 @@
 import Onyx, {OnyxUpdate, ConnectOptions} from './Onyx';
-import {CustomTypeOptions, OnyxCollection, OnyxEntry, NullishDeep, KeyValueMapping, OnyxKey, Selector, WithOnyxInstanceState} from './types';
+import {CustomTypeOptions, OnyxCollection, OnyxEntry, NullishDeep, KeyValueMapping, OnyxKey, Selector, WithOnyxInstanceState, OnyxValue} from './types';
 import withOnyx from './withOnyx';
+import useOnyx, {UseOnyxResult} from './useOnyx';
 
 export default Onyx;
-export {CustomTypeOptions, OnyxCollection, OnyxEntry, OnyxUpdate, withOnyx, ConnectOptions, NullishDeep, KeyValueMapping, OnyxKey, Selector, WithOnyxInstanceState};
+export {
+    CustomTypeOptions,
+    OnyxCollection,
+    OnyxEntry,
+    OnyxUpdate,
+    withOnyx,
+    ConnectOptions,
+    NullishDeep,
+    KeyValueMapping,
+    OnyxKey,
+    Selector,
+    WithOnyxInstanceState,
+    useOnyx,
+    UseOnyxResult,
+    OnyxValue,
+};

lib/index.js

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

lib/storage/__mocks__/index.ts

@@ -16,13 +16,20 @@ const idbKeyvalMock: StorageProvider = {
     },
     multiSet(pairs) {
         const setPromises = pairs.map(([key, value]) => this.setItem(key, value));
-        return new Promise((resolve) => Promise.all(setPromises).then(() => resolve(storageMapInternal)));
+        return new Promise((resolve) => {
+            Promise.all(setPromises).then(() => resolve(storageMapInternal));
+        });
     },
     getItem(key) {
         return Promise.resolve(storageMapInternal[key]);
     },
     multiGet(keys) {
-        const getPromises = keys.map((key) => new Promise((resolve) => this.getItem(key).then((value) => resolve([key, value]))));
+        const getPromises = keys.map(
+            (key) =>
+                new Promise((resolve) => {
+                    this.getItem(key).then((value) => resolve([key, value]));
+                }),
+        );
         return Promise.all(getPromises) as Promise<KeyValuePairList>;
     },
     multiMerge(pairs) {

lib/types.d.ts

@@ -99,6 +99,11 @@ type CollectionKey = `${CollectionKeyBase}${string}`;
  */
 type OnyxKey = Key | CollectionKey;
 
+/**
+ * Represents a Onyx value that can be either a single entry or a collection of entries, depending on the `TKey` provided.
+ */
+type OnyxValue<TKey extends OnyxKey> = TKey extends CollectionKeyBase ? OnyxCollection<KeyValueMapping[TKey]> : OnyxEntry<KeyValueMapping[TKey]>;
+
 /**
  * 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.
@@ -239,6 +244,7 @@ export {
     OnyxCollection,
     OnyxEntry,
     OnyxKey,
+    OnyxValue,
     Selector,
     NullishDeep,
     WithOnyxInstanceState,

lib/useLiveRef.ts

@@ -0,0 +1,14 @@
+import {useRef} from 'react';
+
+/**
+ * Creates a mutable reference to a value, useful when you need to
+ * maintain a reference to a value that may change over time without triggering re-renders.
+ */
+function useLiveRef<T>(value: T) {
+    const ref = useRef<T>(value);
+    ref.current = value;
+
+    return ref;
+}
+
+export default useLiveRef;