Merge branch 'main' into @chrispader/update-nitro-sqlite-to-v9.6.0

Author: chrispader

.github/scripts/verifyDocs.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+#
+# Re-generates API docs and verifies that there is no diff,
+# because that would indicate that the PR author forgot to run `npm run build:docs`
+# and commit the updated API.md and API-INTERNAL.md files.
+
+declare -r GREEN='\033[0;32m'
+declare -r RED='\033[0;31m'
+declare -r NC='\033[0m'
+
+printf '\nRebuilding API docs...\n'
+if ! npm run build:docs; then
+    echo -e "${RED}Error: \`npm run build:docs\` failed. Please fix the build errors before continuing.${NC}"
+    exit 1
+fi
+
+DIFF_OUTPUT=$(git diff --exit-code API.md API-INTERNAL.md)
+EXIT_CODE=$?
+
+if [[ EXIT_CODE -eq 0 ]]; then
+    echo -e "${GREEN}API docs are up to date!${NC}"
+    exit 0
+else
+    echo -e "${RED}Error: Diff found when API docs were rebuilt. Did you forget to run \`npm run build:docs\` after making changes?${NC}"
+    echo "$DIFF_OUTPUT"
+    exit 1
+fi

.github/workflows/validateDocs.yml

@@ -0,0 +1,26 @@
+name: Validate API Docs
+
+on:
+    pull_request:
+        types: [opened, synchronize]
+        paths: ['lib/**', 'buildDocs.ts', 'API.md', 'API-INTERNAL.md', '.github/workflows/validateDocs.yml', '.github/scripts/verifyDocs.sh']
+
+jobs:
+    verify:
+        runs-on: ubuntu-latest
+        steps:
+            # v5.0.0
+            - uses: actions/checkout@ff7abcd0c3c05ccf6adc123a8cd1fd4fb30fb493
+
+            - name: Setup Node
+              # v4.4.0
+              uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e
+              with:
+                  node-version-file: ".nvmrc"
+                  cache: npm
+                  cache-dependency-path: package-lock.json
+
+            - run: npm ci
+
+            - name: Verify API Docs Are Up To Date
+              run: ./.github/scripts/verifyDocs.sh

API-INTERNAL.md

@@ -17,6 +17,11 @@
 <dt><a href="#getDeferredInitTask">getDeferredInitTask()</a></dt>
 <dd><p>Getter - returns the deffered init task.</p>
 </dd>
+<dt><a href="#afterInit">afterInit(action)</a> ⇒</dt>
+<dd><p>Executes an action after Onyx has been initialized.
+If Onyx is already initialized, the action is executed immediately.
+Otherwise, it waits for initialization to complete before executing.</p>
+</dd>
 <dt><a href="#getSkippableCollectionMemberIDs">getSkippableCollectionMemberIDs()</a></dt>
 <dd><p>Getter - returns the skippable collection member IDs.</p>
 </dd>
@@ -54,45 +59,6 @@ to the values for those keys (correctly typed) such as <code>[OnyxCollection&lt;
 <dt><a href="#getAllKeys">getAllKeys()</a></dt>
 <dd><p>Returns current key names stored in persisted storage</p>
 </dd>
-<dt><a href="#getCollectionKeys">getCollectionKeys()</a></dt>
-<dd><p>Returns set of all registered collection keys</p>
-</dd>
-<dt><a href="#isCollectionKey">isCollectionKey()</a></dt>
-<dd><p>Checks to see if the subscriber&#39;s supplied key
-is associated with a collection of keys.</p>
-</dd>
-<dt><a href="#isCollectionMember">isCollectionMember(key)</a> ⇒</dt>
-<dd><p>Checks if a given key is a collection member key (not just a collection key).</p>
-</dd>
-<dt><a href="#isRamOnlyKey">isRamOnlyKey(key)</a> ⇒</dt>
-<dd><p>Checks if a given key is a RAM-only key, RAM-only collection key, or a RAM-only collection member</p>
-<p>For example:</p>
-<p>For the following Onyx setup</p>
-<p>ramOnlyKeys: [&quot;ramOnlyKey&quot;, &quot;ramOnlyCollection_&quot;]</p>
-<ul>
-<li><code>isRamOnlyKey(&quot;ramOnlyKey&quot;)</code> would return true</li>
-<li><code>isRamOnlyKey(&quot;ramOnlyCollection_&quot;)</code> would return true</li>
-<li><code>isRamOnlyKey(&quot;ramOnlyCollection_1&quot;)</code> would return true</li>
-<li><code>isRamOnlyKey(&quot;someOtherKey&quot;)</code> would return false</li>
-</ul>
-</dd>
-<dt><a href="#splitCollectionMemberKey">splitCollectionMemberKey(key, collectionKey)</a> ⇒</dt>
-<dd><p>Splits a collection member key into the collection key part and the ID part.</p>
-</dd>
-<dt><a href="#isKeyMatch">isKeyMatch()</a></dt>
-<dd><p>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 &quot;collection key&quot;)</p>
-</dd>
-<dt><a href="#getCollectionKey">getCollectionKey(key)</a> ⇒</dt>
-<dd><p>Extracts the collection identifier of a given collection member key.</p>
-<p>For example:</p>
-<ul>
-<li><code>getCollectionKey(&quot;report_123&quot;)</code> would return &quot;report_&quot;</li>
-<li><code>getCollectionKey(&quot;report_&quot;)</code> would return &quot;report_&quot;</li>
-<li><code>getCollectionKey(&quot;report_-1_something&quot;)</code> would return &quot;report_&quot;</li>
-<li><code>getCollectionKey(&quot;sharedNVP_user_-1_something&quot;)</code> would return &quot;sharedNVP_user_&quot;</li>
-</ul>
-</dd>
 <dt><a href="#tryGetCachedValue">tryGetCachedValue()</a></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>
@@ -113,17 +79,6 @@ run out of storage the least recently accessed key can be removed.</p>
 <dt><a href="#getCollectionDataAndSendAsObject">getCollectionDataAndSendAsObject()</a></dt>
 <dd><p>Gets the data for a given an array of matching keys, combines them into an object, and sends the result back to the subscriber.</p>
 </dd>
-<dt><a href="#prepareSubscriberUpdate">prepareSubscriberUpdate(callback)</a></dt>
-<dd><p>Delays promise resolution until the next macrotask to prevent race condition if the key subscription is in progress.</p>
-</dd>
-<dt><a href="#scheduleSubscriberUpdate">scheduleSubscriberUpdate()</a></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()</a></dt>
-<dd><p>This method is similar to scheduleSubscriberUpdate but it is built for working specifically with collections
-so that keysChanged() is triggered for the collection and not keyChanged(). If this was not done, then the
-subscriber callbacks receive the data in a different format than they normally expect and it breaks code.</p>
-</dd>
 <dt><a href="#remove">remove()</a></dt>
 <dd><p>Remove a key from Onyx and update the subscribers</p>
 </dd>
@@ -223,6 +178,20 @@ Getter - returns the default key states.
 Getter - returns the deffered init task.
 
 **Kind**: global function  
+<a name="afterInit"></a>
+
+## afterInit(action) ⇒
+Executes an action after Onyx has been initialized.
+If Onyx is already initialized, the action is executed immediately.
+Otherwise, it waits for initialization to complete before executing.
+
+**Kind**: global function  
+**Returns**: The result of the action  
+
+| Param | Description |
+| --- | --- |
+| action | The action to execute after initialization |
+
 <a name="getSkippableCollectionMemberIDs"></a>
 
 ## getSkippableCollectionMemberIDs()
@@ -312,93 +281,6 @@ Deletes a subscription ID associated with its corresponding key.
 Returns current key names stored in persisted storage
 
 **Kind**: global function  
-<a name="getCollectionKeys"></a>
-
-## getCollectionKeys()
-Returns set of all registered collection keys
-
-**Kind**: global function  
-<a name="isCollectionKey"></a>
-
-## isCollectionKey()
-Checks to see if the subscriber's supplied key
-is associated with a collection of keys.
-
-**Kind**: global function  
-<a name="isCollectionMember"></a>
-
-## isCollectionMember(key) ⇒
-Checks if a given key is a collection member key (not just a collection key).
-
-**Kind**: global function  
-**Returns**: true if the key is a collection member, false otherwise  
-
-| Param | Description |
-| --- | --- |
-| key | The key to check |
-
-<a name="isRamOnlyKey"></a>
-
-## isRamOnlyKey(key) ⇒
-Checks if a given key is a RAM-only key, RAM-only collection key, or a RAM-only collection member
-
-For example:
-
-For the following Onyx setup
-
-ramOnlyKeys: ["ramOnlyKey", "ramOnlyCollection_"]
-
-- `isRamOnlyKey("ramOnlyKey")` would return true
-- `isRamOnlyKey("ramOnlyCollection_")` would return true
-- `isRamOnlyKey("ramOnlyCollection_1")` would return true
-- `isRamOnlyKey("someOtherKey")` would return false
-
-**Kind**: global function  
-**Returns**: true if key is a RAM-only key, RAM-only collection key, or a RAM-only collection member  
-
-| Param | Description |
-| --- | --- |
-| key | The key to check |
-
-<a name="splitCollectionMemberKey"></a>
-
-## splitCollectionMemberKey(key, collectionKey) ⇒
-Splits a collection member key into the collection key part and the ID part.
-
-**Kind**: global function  
-**Returns**: A tuple where the first element is the collection part and the second element is the ID part,
-or throws an Error if the key is not a collection one.  
-
-| Param | Description |
-| --- | --- |
-| key | The collection member key to split. |
-| collectionKey | The collection key of the `key` param that can be passed in advance to optimize the function. |
-
-<a name="isKeyMatch"></a>
-
-## isKeyMatch()
-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")
-
-**Kind**: global function  
-<a name="getCollectionKey"></a>
-
-## getCollectionKey(key) ⇒
-Extracts the collection identifier of a given collection member key.
-
-For example:
-- `getCollectionKey("report_123")` would return "report_"
-- `getCollectionKey("report_")` would return "report_"
-- `getCollectionKey("report_-1_something")` would return "report_"
-- `getCollectionKey("sharedNVP_user_-1_something")` would return "sharedNVP_user_"
-
-**Kind**: global function  
-**Returns**: The plain collection key or throws an Error if the key is not a collection one.  
-
-| Param | Description |
-| --- | --- |
-| key | The collection key to process. |
-
 <a name="tryGetCachedValue"></a>
 
 ## tryGetCachedValue()
@@ -457,35 +339,6 @@ run out of storage the least recently accessed key can be removed.
 ## getCollectionDataAndSendAsObject()
 Gets the data for a given an array of matching keys, combines them into an object, and sends the result back to the subscriber.
 
-**Kind**: global function  
-<a name="prepareSubscriberUpdate"></a>
-
-## prepareSubscriberUpdate(callback)
-Delays promise resolution until the next macrotask to prevent race condition if the key subscription is in progress.
-
-**Kind**: global function  
-
-| Param | Description |
-| --- | --- |
-| callback | The keyChanged/keysChanged callback |
-
-<a name="scheduleSubscriberUpdate"></a>
-
-## scheduleSubscriberUpdate()
-Schedules an update that will be appended to the macro task queue (so it doesn't update the subscribers immediately).
-
-**Kind**: global function  
-**Example**  
-```js
-scheduleSubscriberUpdate(key, value, subscriber => subscriber.initWithStoredValues === false)
-```
-<a name="scheduleNotifyCollectionSubscribers"></a>
-
-## scheduleNotifyCollectionSubscribers()
-This method is similar to scheduleSubscriberUpdate but it is built for working specifically with collections
-so that keysChanged() is triggered for the collection and not keyChanged(). If this was not done, then the
-subscriber callbacks receive the data in a different format than they normally expect and it breaks code.
-
 **Kind**: global function  
 <a name="remove"></a>
 

README.md

@@ -351,59 +351,6 @@ const ReportActionsView = ({reportID, isActiveReport}) => {
 export default ReportActionsView;
 ```
 
-# Benchmarks
-
-Provide the `captureMetrics` boolean flag to `Onyx.init` to capture call statistics
-
-```js
-Onyx.init({
-    keys: ONYXKEYS,
-    evictableKeys: [ONYXKEYS.COLLECTION.REPORT_ACTIONS],
-    captureMetrics: Config.BENCHMARK_ONYX,
-});
-```
-
-At any point you can get the collected statistics using `Onyx.getMetrics()`.
-This will return an object containing `totalTime`, `averageTime` and `summaries`.
-`summaries` is a collection of statistics for each method it contains data about:
-  - method name
-  - total, max, min, average times for this method calls
-  - calls - a list of individual calls with each having: start time; end time; call duration; call arguments
-    - start/end times are relative to application launch time - 0.00 being exactly at launch
-
-If you wish to reset the metrics and start over use `Onyx.resetMetrics()`
-
-Finally, there's a `Onyx.printMetrics()` method which prints human statistics information on the dev console. You can use this method during debugging. For example add an `Onyx.printMetrics()` line somewhere in code or call it through the dev console. It supports 3 popular formats *MD* - human friendly markdown, *CSV* and *JSON*. The default is MD if you want to print another format call `Onyx.printMetrics({ format: 'csv' })` or
-`Onyx.printMetrics({ format: 'json' })`.
-
-Sample output of `Onyx.printMetrics()`
-
-```
-### Onyx Benchmark
-  - Total: 1.5min
-  - Last call finished at: 12.55sec
-
-|     method      | total time spent |    max    |   min    |    avg    | time last call completed | calls made |
-|-----------------|-----------------:|----------:|---------:|----------:|-------------------------:|-----------:|
-| Onyx:getAllKeys |           1.2min |   2.16sec |  0.159ms | 782.230ms |                 12.55sec |         90 |
-| Onyx:merge      |          4.73sec |   2.00sec | 74.412ms | 591.642ms |                 10.24sec |          8 |
-| Onyx:set        |          3.90sec | 846.760ms | 43.663ms | 433.056ms |                  7.47sec |          9 |
-| Onyx:get        |          8.87sec |   2.00sec |  0.063ms |  61.998ms |                 10.24sec |        143 |
-
-
-|                           Onyx:set                            |
-|---------------------------------------------------------------|
-| start time | end time  | duration  |           args           |
-|-----------:|----------:|----------:|--------------------------|
-|  291.042ms | 553.079ms | 262.037ms | session, [object Object] |
-|  293.719ms | 553.316ms | 259.597ms | account, [object Object] |
-|  294.541ms | 553.651ms | 259.109ms | network, [object Object] |
-|  365.378ms | 554.246ms | 188.867ms | iou, [object Object]     |
-|    1.08sec |   2.20sec |   1.12sec | network, [object Object] |
-|    1.08sec |   2.20sec |   1.12sec | iou, [object Object]     |
-|    1.17sec |   2.20sec |   1.03sec | currentURL, /            |
-```
-
 # Debug mode
 
 It can be useful to log why Onyx is calling `setState()` on a particular React component so that we can understand which key changed, what changed about the value, and the connected component that ultimately rendered as a result. When used correctly this can help isolate problem areas and unnecessary renders in the code. To enable this feature, pass `debugSetState: true` to the config and grep JS console logs for `[Onyx-Debug]`.

lib/DevTools/RealDevTools.ts

@@ -1,4 +1,5 @@
 import type {IDevTools, DevtoolsOptions, DevtoolsConnection, ReduxDevtools} from './types';
+import OnyxKeys from '../OnyxKeys';
 
 const ERROR_LABEL = 'Onyx DevTools - Error: ';
 
@@ -76,7 +77,7 @@ class RealDevTools implements IDevTools {
     clearState(keysToPreserve: string[] = []): void {
         const newState = Object.entries(this.state).reduce((obj: Record<string, unknown>, [key, value]) => {
             // eslint-disable-next-line no-param-reassign
-            obj[key] = keysToPreserve.includes(key) ? value : this.defaultState[key];
+            obj[key] = keysToPreserve.some((preserveKey) => OnyxKeys.isKeyMatch(preserveKey, key)) ? value : this.defaultState[key];
             return obj;
         }, {});