Merge pull request #462 from fabioh8010/feature/useOnyx

Implement useOnyx hook

.eslintrc.js

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

API.md

@@ -22,8 +22,15 @@ cause react to schedule the updates at once instead of after each other. This is
 and runs it through a reducer function to return a subset of the data according to a selector.
 The resulting collection will only contain items that are returned by the selector.</p>
 </dd>
+<dt><a href="#isCollectionKey">isCollectionKey(key)</a> ⇒ <code>Boolean</code></dt>
+<dd><p>Checks to see if the a subscriber&#39;s supplied key
+is associated with a collection of keys.</p>
+</dd>
 <dt><a href="#isCollectionMemberKey">isCollectionMemberKey(collectionKey, key)</a> ⇒ <code>Boolean</code></dt>
 <dd></dd>
+<dt><a href="#splitCollectionMemberKey">splitCollectionMemberKey(key)</a> ⇒ <code>Array.&lt;String&gt;</code></dt>
+<dd><p>Splits a collection member key into the collection key part and the ID part.</p>
+</dd>
 <dt><a href="#tryGetCachedValue">tryGetCachedValue(key, mapping)</a> ⇒ <code>Mixed</code></dt>
 <dd><p>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.</p>
@@ -34,7 +41,7 @@ If the requested key is a collection, it will return an object with all the coll
 <dt><a href="#disconnect">disconnect(connectionID, [keyToRemoveFromEvictionBlocklist])</a></dt>
 <dd><p>Remove the listener for a react component</p>
 </dd>
-<dt><a href="#scheduleSubscriberUpdate">scheduleSubscriberUpdate(key, value, [canUpdateSubscriber])</a> ⇒ <code>Promise</code></dt>
+<dt><a href="#scheduleSubscriberUpdate">scheduleSubscriberUpdate(key, value, prevValue, [canUpdateSubscriber])</a> ⇒ <code>Promise</code></dt>
 <dd><p>Schedules an update that will be appended to the macro task queue (so it doesn&#39;t update the subscribers immediately).</p>
 </dd>
 <dt><a href="#scheduleNotifyCollectionSubscribers">scheduleNotifyCollectionSubscribers(key, value)</a> ⇒ <code>Promise</code></dt>
@@ -90,13 +97,6 @@ value will be saved to storage after the default value.</p>
 <dt><a href="#setMemoryOnlyKeys">setMemoryOnlyKeys(keyList)</a></dt>
 <dd><p>When set these keys will not be persisted to storage</p>
 </dd>
-<dt><a href="#onClear">onClear(callback)</a></dt>
-<dd><p>Sets the callback to be called when the clear finishes executing.</p>
-</dd>
-<dt><a href="#subscribeToEvents">subscribeToEvents()</a></dt>
-<dd><p>Subscribes to the Broadcast channel and executes actions based on the
-types of events.</p>
-</dd>
 <dt><a href="#init">init([options])</a></dt>
 <dd><p>Initialize the store with actions and listening for storage events</p>
 </dd>
@@ -153,6 +153,18 @@ The resulting collection will only contain items that are returned by the select
 | selector | <code>String</code> \| <code>function</code> | (see method docs for getSubsetOfData() for full details) |
 | [withOnyxInstanceState] | <code>Object</code> |  |
 
+<a name="isCollectionKey"></a>
+
+## isCollectionKey(key) ⇒ <code>Boolean</code>
+Checks to see if the a subscriber's supplied key
+is associated with a collection of keys.
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| key | <code>String</code> | 
+
 <a name="isCollectionMemberKey"></a>
 
 ## isCollectionMemberKey(collectionKey, key) ⇒ <code>Boolean</code>
@@ -163,6 +175,18 @@ The resulting collection will only contain items that are returned by the select
 | collectionKey | <code>String</code> | 
 | key | <code>String</code> | 
 
+<a name="splitCollectionMemberKey"></a>
+
+## splitCollectionMemberKey(key) ⇒ <code>Array.&lt;String&gt;</code>
+Splits a collection member key into the collection key part and the ID part.
+
+**Kind**: global function  
+**Returns**: <code>Array.&lt;String&gt;</code> - A tuple where the first element is the collection part and the second element is the ID part.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | <code>String</code> | The collection member key to split. |
+
 <a name="tryGetCachedValue"></a>
 
 ## tryGetCachedValue(key, mapping) ⇒ <code>Mixed</code>
@@ -221,7 +245,7 @@ Onyx.disconnect(connectionID);
 ```
 <a name="scheduleSubscriberUpdate"></a>
 
-## scheduleSubscriberUpdate(key, value, [canUpdateSubscriber]) ⇒ <code>Promise</code>
+## scheduleSubscriberUpdate(key, value, prevValue, [canUpdateSubscriber]) ⇒ <code>Promise</code>
 Schedules an update that will be appended to the macro task queue (so it doesn't update the subscribers immediately).
 
 **Kind**: global function  
@@ -230,6 +254,7 @@ Schedules an update that will be appended to the macro task queue (so it doesn't
 | --- | --- | --- |
 | key | <code>String</code> |  |
 | value | <code>\*</code> |  |
+| prevValue | <code>\*</code> |  |
 | [canUpdateSubscriber] | <code>function</code> | only subscribers that pass this truth test will be updated |
 
 **Example**  
@@ -410,24 +435,6 @@ When set these keys will not be persisted to storage
 | --- | --- |
 | keyList | <code>Array.&lt;string&gt;</code> | 
 
-<a name="onClear"></a>
-
-## onClear(callback)
-Sets the callback to be called when the clear finishes executing.
-
-**Kind**: global function  
-
-| Param | Type |
-| --- | --- |
-| callback | <code>function</code> | 
-
-<a name="subscribeToEvents"></a>
-
-## subscribeToEvents()
-Subscribes to the Broadcast channel and executes actions based on the
-types of events.
-
-**Kind**: global function  
 <a name="init"></a>
 
 ## init([options])

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;
           }
@@ -114,6 +119,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.
@@ -289,6 +309,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;
@@ -307,7 +336,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 {Array<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")
@@ -1670,6 +1684,9 @@ const Onyx = {
     setMemoryOnlyKeys,
     tryGetCachedValue,
     hasPendingMergeForKey,
+    isCollectionKey,
+    isCollectionMemberKey,
+    splitCollectionMemberKey,
 };
 
 export default Onyx;

lib/index.d.ts

@@ -1,6 +1,23 @@
 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, FetchStatus} 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,
+    FetchStatus,
+};

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

@@ -15,13 +15,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;