react-native-onyx 1.0.4 → 1.0.5

package/API.md

@@ -11,6 +11,12 @@
 <dt><a href="#disconnect">disconnect(connectionID, [keyToRemoveFromEvictionBlocklist])</a></dt>
 <dd><p>Remove the listener for a react component</p>
 </dd>
+<dt><a href="#notifySubscribersOnNextTick">notifySubscribersOnNextTick(key, value)</a></dt>
+<dd><p>This method mostly exists for historical reasons as this library was initially designed without a memory cache and one was added later.
+For this reason, Onyx works more similar to what you might expect from a native AsyncStorage with reads, writes, etc all becoming
+available async. Since we have code in our main applications that might expect things to work this way it&#39;s not safe to change this
+behavior just yet.</p>
+</dd>
 <dt><a href="#set">set(key, value)</a> ⇒ <code>Promise</code></dt>
 <dd><p>Write a value to our store with the given key</p>
 </dd>
@@ -29,6 +35,19 @@ applied in the order they were called. Note: <code>Onyx.set()</code> calls do no
 </dd>
 <dt><a href="#clear">clear()</a> ⇒ <code>Promise.&lt;void&gt;</code></dt>
 <dd><p>Clear out all the data in the store</p>
+<p>Note that calling Onyx.clear() and then Onyx.set() on a key with a default
+key state may store an unexpected value in Storage.</p>
+<p>E.g.
+Onyx.clear();
+Onyx.set(ONYXKEYS.DEFAULT_KEY, &#39;default&#39;);
+Storage.getItem(ONYXKEYS.DEFAULT_KEY)
+    .then((storedValue) =&gt; console.log(storedValue));
+null is logged instead of the expected &#39;default&#39;</p>
+<p>Onyx.set() might call Storage.setItem() before Onyx.clear() calls
+Storage.setItem(). Use Onyx.merge() instead if possible. Onyx.merge() calls
+Onyx.get(key) before calling Storage.setItem() via Onyx.set().
+Storage.setItem() from Onyx.clear() will have already finished and the merged
+value will be saved to storage after the default value.</p>
 </dd>
 <dt><a href="#mergeCollection">mergeCollection(collectionKey, collection)</a> ⇒ <code>Promise</code></dt>
 <dd><p>Merges a collection based on their keys</p>
@@ -46,8 +65,8 @@ applied in the order they were called. Note: <code>Onyx.set()</code> calls do no
 ## connect(mapping) ⇒ <code>Number</code>
 Subscribes a react component's state directly to a store key
 
-**Kind**: global function  
-**Returns**: <code>Number</code> - an ID to use when calling disconnect  
+**Kind**: global function
+**Returns**: <code>Number</code> - an ID to use when calling disconnect
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -58,7 +77,7 @@ Subscribes a react component's state directly to a store key
 | [mapping.callback] | <code>function</code> | a method that will be called with changed data      This is used by any non-React code to connect to Onyx |
 | [mapping.initWithStoredValues] | <code>Boolean</code> | If set to false, then no data will be prefilled into the  component |
 
-**Example**  
+**Example**
 ```js
 const connectionID = Onyx.connect({
     key: ONYXKEYS.SESSION,
@@ -70,23 +89,38 @@ const connectionID = Onyx.connect({
 ## disconnect(connectionID, [keyToRemoveFromEvictionBlocklist])
 Remove the listener for a react component
 
-**Kind**: global function  
+**Kind**: global function
 
 | Param | Type | Description |
 | --- | --- | --- |
 | connectionID | <code>Number</code> | unique id returned by call to Onyx.connect() |
 | [keyToRemoveFromEvictionBlocklist] | <code>String</code> |  |
 
-**Example**  
+**Example**
 ```js
 Onyx.disconnect(connectionID);
 ```
+<a name="notifySubscribersOnNextTick"></a>
+
+## notifySubscribersOnNextTick(key, value)
+This method mostly exists for historical reasons as this library was initially designed without a memory cache and one was added later.
+For this reason, Onyx works more similar to what you might expect from a native AsyncStorage with reads, writes, etc all becoming
+available async. Since we have code in our main applications that might expect things to work this way it's not safe to change this
+behavior just yet.
+
+**Kind**: global function
+
+| Param | Type |
+| --- | --- |
+| key | <code>String</code> |
+| value | <code>\*</code> |
+
 <a name="set"></a>
 
 ## set(key, value) ⇒ <code>Promise</code>
 Write a value to our store with the given key
 
-**Kind**: global function  
+**Kind**: global function
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -98,13 +132,13 @@ Write a value to our store with the given key
 ## multiSet(data) ⇒ <code>Promise</code>
 Sets multiple keys and values
 
-**Kind**: global function  
+**Kind**: global function
 
 | Param | Type | Description |
 | --- | --- | --- |
 | data | <code>Object</code> | object keyed by ONYXKEYS and the values to set |
 
-**Example**  
+**Example**
 ```js
 Onyx.multiSet({'key1': 'a', 'key2': 'b'});
 ```
@@ -122,14 +156,14 @@ Calls to `Onyx.merge()` are batched so that any calls performed in a single tick
 applied in the order they were called. Note: `Onyx.set()` calls do not work this way so use caution when mixing
 `Onyx.merge()` and `Onyx.set()`.
 
-**Kind**: global function  
+**Kind**: global function
 
 | Param | Type | Description |
 | --- | --- | --- |
 | key | <code>String</code> | ONYXKEYS key |
 | value | <code>Object</code> \| <code>Array</code> | Object or Array value to merge |
 
-**Example**  
+**Example**
 ```js
 Onyx.merge(ONYXKEYS.EMPLOYEE_LIST, ['Joe']); // -> ['Joe']
 Onyx.merge(ONYXKEYS.EMPLOYEE_LIST, ['Jack']); // -> ['Joe', 'Jack']
@@ -141,20 +175,36 @@ Onyx.merge(ONYXKEYS.POLICY, {name: 'My Workspace'}); // -> {id: 1, name: 'My Wor
 ## clear() ⇒ <code>Promise.&lt;void&gt;</code>
 Clear out all the data in the store
 
-**Kind**: global function  
+Note that calling Onyx.clear() and then Onyx.set() on a key with a default
+key state may store an unexpected value in Storage.
+
+E.g.
+Onyx.clear();
+Onyx.set(ONYXKEYS.DEFAULT_KEY, 'default');
+Storage.getItem(ONYXKEYS.DEFAULT_KEY)
+    .then((storedValue) => console.log(storedValue));
+null is logged instead of the expected 'default'
+
+Onyx.set() might call Storage.setItem() before Onyx.clear() calls
+Storage.setItem(). Use Onyx.merge() instead if possible. Onyx.merge() calls
+Onyx.get(key) before calling Storage.setItem() via Onyx.set().
+Storage.setItem() from Onyx.clear() will have already finished and the merged
+value will be saved to storage after the default value.
+
+**Kind**: global function
 <a name="mergeCollection"></a>
 
 ## mergeCollection(collectionKey, collection) ⇒ <code>Promise</code>
 Merges a collection based on their keys
 
-**Kind**: global function  
+**Kind**: global function
 
 | Param | Type | Description |
 | --- | --- | --- |
 | collectionKey | <code>String</code> | e.g. `ONYXKEYS.COLLECTION.REPORT` |
 | collection | <code>Object</code> | Object collection keyed by individual collection member keys and values |
 
-**Example**  
+**Example**
 ```js
 Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, {
     [`${ONYXKEYS.COLLECTION.REPORT}1`]: report1,
@@ -166,7 +216,7 @@ Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, {
 ## update(data)
 Insert API responses and lifecycle data into Onyx
 
-**Kind**: global function  
+**Kind**: global function
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -177,7 +227,7 @@ Insert API responses and lifecycle data into Onyx
 ## init([options])
 Initialize the store with actions and listening for storage events
 
-**Kind**: global function  
+**Kind**: global function
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -190,7 +240,7 @@ Initialize the store with actions and listening for storage events
 | [options.shouldSyncMultipleInstances] | <code>Boolean</code> |  | Auto synchronize storage events between multiple instances of Onyx running in different tabs/windows. Defaults to true for platforms that support local storage (web/desktop) |
 | [option.keysToDisableSyncEvents] | <code>Array.&lt;String&gt;</code> | <code>[]</code> | Contains keys for which we want to disable sync event across tabs. |
 
-**Example**  
+**Example**
 ```js
 Onyx.init({
     keys: ONYXKEYS,

package/README.md

@@ -20,7 +20,7 @@ Persistent storage solution wrapped in a Pub/Sub library.
 Onyx is published to [`npm`](https://www.npmjs.com/package/react-native-onyx)
 
 ```shell
-npm install react-native-onyx --save 
+npm install react-native-onyx --save
 ```
 
 ## Initialization
@@ -42,8 +42,8 @@ Onyx.init(config);
 ```
 
 ### Usage in non react-native projects
-Onyx can be used in non react-native projects, by leveraging the `browser` field in `package.json`  
-Bundlers like Webpack respect that field and import code from the specified path  
+Onyx can be used in non react-native projects, by leveraging the `browser` field in `package.json`
+Bundlers like Webpack respect that field and import code from the specified path
 We import Onyx the same way shown above - `import Onyx from 'react-native-onyx'`
 
 ## Setting data
@@ -148,7 +148,7 @@ Under the hood storage access calls are delegated to a [`StorageProvider`](lib/s
 Some platforms (like web and desktop) might use the same storage provider
 
 If a platform needs to use a separate library (like using MMVK for react-native) it should be added in the following way:
-1. Create a `StorageProvider.js` at [lib/storage/providers](lib/storage/providers)  
+1. Create a `StorageProvider.js` at [lib/storage/providers](lib/storage/providers)
    Reference an existing [StorageProvider](lib/storage/providers/AsyncStorage.js) for the interface that has to be implemented
 2. Update the factory at [lib/storage/index.web.js](lib/storage/index.web.js) and [lib/storage/index.native.js](lib/storage/index.native.js) to return the newly created Provider for the desired Platform(s)
 

package/dist/web.development.js

@@ -971,6 +971,20 @@ function disconnect(connectionID, keyToRemoveFromEvictionBlocklist) {
   delete callbackToStateMapping[connectionID];
 }
 
+/**
+ * This method mostly exists for historical reasons as this library was initially designed without a memory cache and one was added later.
+ * For this reason, Onyx works more similar to what you might expect from a native AsyncStorage with reads, writes, etc all becoming
+ * available async. Since we have code in our main applications that might expect things to work this way it's not safe to change this
+ * behavior just yet.
+ *
+ * @param {String} key
+ * @param {*} value
+ */
+// eslint-disable-next-line rulesdir/no-negated-variables
+function notifySubscribersOnNextTick(key, value) {
+  Promise.resolve().then(function () {return keyChanged(key, value);});
+}
+
 /**
  * Remove a key from Onyx and update the subscribers
  *
@@ -981,10 +995,7 @@ function disconnect(connectionID, keyToRemoveFromEvictionBlocklist) {
 function remove(key) {
   // Cache the fact that the value was removed
   _OnyxCache.default.set(key, null);
-
-  // Optimistically inform subscribers on the next tick
-  Promise.resolve().then(function () {return keyChanged(key, null);});
-
+  notifySubscribersOnNextTick(key, null);
   return _storage.default.removeItem(key);
 }
 
@@ -1040,9 +1051,7 @@ function set(key, value) {
 
   // Adds the key to cache when it's not available
   _OnyxCache.default.set(key, value);
-
-  // Optimistically inform subscribers on the next tick
-  Promise.resolve().then(function () {return keyChanged(key, value);});
+  notifySubscribersOnNextTick(key, value);
 
   // Write the thing to persistent storage, which will trigger a storage event for any other tabs open on this domain
   return _storage.default.setItem(key, value).
@@ -1075,7 +1084,7 @@ function multiSet(data) {
   _underscore.default.each(data, function (val, key) {
     // Update cache and optimistically inform subscribers on the next tick
     _OnyxCache.default.set(key, val);
-    Promise.resolve().then(function () {return keyChanged(key, val);});
+    notifySubscribersOnNextTick(key, val);
   });
 
   return _storage.default.multiSet(keyValuePairs).
@@ -1224,11 +1233,9 @@ function clear() {
     _underscore.default.each(keys, function (key) {
       var resetValue = (0, _get.default)(defaultKeyStates, key, null);
       _OnyxCache.default.set(key, resetValue);
-
-      // Optimistically inform subscribers on the next tick
-      Promise.resolve().then(function () {return keyChanged(key, resetValue);});
+      notifySubscribersOnNextTick(key, resetValue);
     });
-    _storage.default.clear();
+    return _storage.default.clear();
   });
 }