react-native-onyx 2.0.22 → 2.0.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/API.md +49 -50
  2. package/dist/DevTools.js +0 -1
  3. package/dist/Onyx.d.ts +49 -252
  4. package/dist/Onyx.js +192 -1155
  5. package/dist/OnyxCache.d.ts +14 -15
  6. package/dist/OnyxUtils.d.ts +320 -0
  7. package/dist/OnyxUtils.js +1061 -0
  8. package/dist/PerformanceUtils.d.ts +3 -5
  9. package/dist/index.d.ts +3 -2
  10. package/dist/storage/InstanceSync/index.d.ts +14 -0
  11. package/dist/storage/InstanceSync/index.js +20 -0
  12. package/dist/storage/InstanceSync/index.web.d.ts +27 -0
  13. package/dist/storage/InstanceSync/index.web.js +59 -0
  14. package/dist/storage/__mocks__/index.d.ts +15 -12
  15. package/dist/storage/__mocks__/index.js +43 -78
  16. package/dist/storage/index.d.ts +6 -2
  17. package/dist/storage/index.js +170 -2
  18. package/dist/storage/platforms/index.d.ts +2 -0
  19. package/dist/storage/{NativeStorage.js → platforms/index.js} +2 -2
  20. package/dist/storage/platforms/index.native.d.ts +2 -0
  21. package/dist/storage/{index.native.js → platforms/index.native.js} +2 -2
  22. package/dist/storage/providers/{IDBKeyVal.js → IDBKeyValProvider.js} +23 -17
  23. package/dist/storage/providers/MemoryOnlyProvider.d.ts +9 -0
  24. package/dist/storage/providers/MemoryOnlyProvider.js +124 -0
  25. package/dist/storage/providers/NoopProvider.js +85 -0
  26. package/dist/storage/providers/SQLiteProvider.d.ts +3 -0
  27. package/dist/storage/providers/{SQLiteStorage.js → SQLiteProvider.js} +17 -9
  28. package/dist/storage/providers/types.d.ts +17 -10
  29. package/dist/types.d.ts +128 -55
  30. package/dist/types.js +2 -0
  31. package/dist/useOnyx.js +11 -10
  32. package/dist/utils.d.ts +2 -2
  33. package/dist/utils.js +29 -16
  34. package/dist/withOnyx.js +6 -5
  35. package/package.json +1 -1
  36. package/dist/storage/NativeStorage.d.ts +0 -2
  37. package/dist/storage/WebStorage.d.ts +0 -3
  38. package/dist/storage/WebStorage.js +0 -62
  39. package/dist/storage/index.native.d.ts +0 -2
  40. /package/dist/storage/providers/{IDBKeyVal.d.ts → IDBKeyValProvider.d.ts} +0 -0
  41. /package/dist/storage/providers/{SQLiteStorage.d.ts → NoopProvider.d.ts} +0 -0
package/API.md CHANGED
@@ -49,7 +49,7 @@ If the requested key is a collection, it will return an object with all the coll
49
49
  so that keysChanged() is triggered for the collection and not keyChanged(). If this was not done, then the
50
50
  subscriber callbacks receive the data in a different format than they normally expect and it breaks code.</p>
51
51
  </dd>
52
- <dt><a href="#broadcastUpdate">broadcastUpdate(key, value, method, hasChanged, wasRemoved)</a> ⇒ <code>Promise</code></dt>
52
+ <dt><a href="#broadcastUpdate">broadcastUpdate(key, value, hasChanged, wasRemoved)</a> ⇒ <code>Promise</code></dt>
53
53
  <dd><p>Notifys subscribers and writes current value to cache</p>
54
54
  </dd>
55
55
  <dt><a href="#hasPendingMergeForKey">hasPendingMergeForKey(key)</a> ⇒ <code>Boolean</code></dt>
@@ -104,7 +104,7 @@ value will be saved to storage after the default value.</p>
104
104
  ## sendActionToDevTools(method, key, value, mergedValue)
105
105
  Sends an action to DevTools extension
106
106
 
107
- **Kind**: global function
107
+ **Kind**: global function
108
108
 
109
109
  | Param | Type | Description |
110
110
  | --- | --- | --- |
@@ -121,13 +121,13 @@ This happens for example in the Onyx.update function, where we process API respo
121
121
  update operations. Instead of calling the subscribers for each update operation, we batch them together which will
122
122
  cause react to schedule the updates at once instead of after each other. This is mainly a performance optimization.
123
123
 
124
- **Kind**: global function
124
+ **Kind**: global function
125
125
  <a name="getSubsetOfData"></a>
126
126
 
127
127
  ## getSubsetOfData(sourceData, selector, [withOnyxInstanceState]) ⇒ <code>Mixed</code>
128
128
  Uses a selector function to return a simplified version of sourceData
129
129
 
130
- **Kind**: global function
130
+ **Kind**: global function
131
131
 
132
132
  | Param | Type | Description |
133
133
  | --- | --- | --- |
@@ -142,7 +142,7 @@ Takes a collection of items (eg. {testKey_1:{a:'a'}, testKey_2:{b:'b'}})
142
142
  and runs it through a reducer function to return a subset of the data according to a selector.
143
143
  The resulting collection will only contain items that are returned by the selector.
144
144
 
145
- **Kind**: global function
145
+ **Kind**: global function
146
146
 
147
147
  | Param | Type | Description |
148
148
  | --- | --- | --- |
@@ -156,29 +156,29 @@ The resulting collection will only contain items that are returned by the select
156
156
  Checks to see if the a subscriber's supplied key
157
157
  is associated with a collection of keys.
158
158
 
159
- **Kind**: global function
159
+ **Kind**: global function
160
160
 
161
161
  | Param | Type |
162
162
  | --- | --- |
163
- | key | <code>String</code> |
163
+ | key | <code>String</code> |
164
164
 
165
165
  <a name="isCollectionMemberKey"></a>
166
166
 
167
167
  ## isCollectionMemberKey(collectionKey, key) ⇒ <code>Boolean</code>
168
- **Kind**: global function
168
+ **Kind**: global function
169
169
 
170
170
  | Param | Type |
171
171
  | --- | --- |
172
- | collectionKey | <code>String</code> |
173
- | key | <code>String</code> |
172
+ | collectionKey | <code>String</code> |
173
+ | key | <code>String</code> |
174
174
 
175
175
  <a name="splitCollectionMemberKey"></a>
176
176
 
177
177
  ## splitCollectionMemberKey(key) ⇒ <code>Array.&lt;String&gt;</code>
178
178
  Splits a collection member key into the collection key part and the ID part.
179
179
 
180
- **Kind**: global function
181
- **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.
180
+ **Kind**: global function
181
+ **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.
182
182
 
183
183
  | Param | Type | Description |
184
184
  | --- | --- | --- |
@@ -190,20 +190,20 @@ Splits a collection member key into the collection key part and the ID part.
190
190
  Tries to get a value from the cache. If the value is not present in cache it will return the default value or undefined.
191
191
  If the requested key is a collection, it will return an object with all the collection members.
192
192
 
193
- **Kind**: global function
193
+ **Kind**: global function
194
194
 
195
195
  | Param | Type |
196
196
  | --- | --- |
197
- | key | <code>String</code> |
198
- | mapping | <code>Object</code> |
197
+ | key | <code>String</code> |
198
+ | mapping | <code>Object</code> |
199
199
 
200
200
  <a name="connect"></a>
201
201
 
202
202
  ## connect(mapping) ⇒ <code>Number</code>
203
203
  Subscribes a react component's state directly to a store key
204
204
 
205
- **Kind**: global function
206
- **Returns**: <code>Number</code> - an ID to use when calling disconnect
205
+ **Kind**: global function
206
+ **Returns**: <code>Number</code> - an ID to use when calling disconnect
207
207
 
208
208
  | Param | Type | Description |
209
209
  | --- | --- | --- |
@@ -217,7 +217,7 @@ Subscribes a react component's state directly to a store key
217
217
  | [mapping.selector] | <code>function</code> | THIS PARAM IS ONLY USED WITH withOnyx(). If included, this will be used to subscribe to a subset of an Onyx key's data. The sourceData and withOnyx state are passed to the selector and should return the simplified data. Using this setting on `withOnyx` can have very positive performance benefits because the component will only re-render when the subset of data changes. Otherwise, any change of data on any property would normally cause the component to re-render (and that can be expensive from a performance standpoint). |
218
218
  | [mapping.initialValue] | <code>String</code> \| <code>Number</code> \| <code>Boolean</code> \| <code>Object</code> | THIS PARAM IS ONLY USED WITH withOnyx(). If included, this will be passed to the component so that something can be rendered while data is being fetched from the DB. Note that it will not cause the component to have the loading prop set to true. | |
219
219
 
220
- **Example**
220
+ **Example**
221
221
  ```js
222
222
  const connectionID = Onyx.connect({
223
223
  key: ONYXKEYS.SESSION,
@@ -229,14 +229,14 @@ const connectionID = Onyx.connect({
229
229
  ## disconnect(connectionID, [keyToRemoveFromEvictionBlocklist])
230
230
  Remove the listener for a react component
231
231
 
232
- **Kind**: global function
232
+ **Kind**: global function
233
233
 
234
234
  | Param | Type | Description |
235
235
  | --- | --- | --- |
236
236
  | connectionID | <code>Number</code> | unique id returned by call to Onyx.connect() |
237
237
  | [keyToRemoveFromEvictionBlocklist] | <code>String</code> | |
238
238
 
239
- **Example**
239
+ **Example**
240
240
  ```js
241
241
  Onyx.disconnect(connectionID);
242
242
  ```
@@ -245,7 +245,7 @@ Onyx.disconnect(connectionID);
245
245
  ## scheduleSubscriberUpdate(key, value, prevValue, [canUpdateSubscriber]) ⇒ <code>Promise</code>
246
246
  Schedules an update that will be appended to the macro task queue (so it doesn't update the subscribers immediately).
247
247
 
248
- **Kind**: global function
248
+ **Kind**: global function
249
249
 
250
250
  | Param | Type | Description |
251
251
  | --- | --- | --- |
@@ -254,7 +254,7 @@ Schedules an update that will be appended to the macro task queue (so it doesn't
254
254
  | prevValue | <code>\*</code> | |
255
255
  | [canUpdateSubscriber] | <code>function</code> | only subscribers that pass this truth test will be updated |
256
256
 
257
- **Example**
257
+ **Example**
258
258
  ```js
259
259
  scheduleSubscriberUpdate(key, value, subscriber => subscriber.initWithStoredValues === false)
260
260
  ```
@@ -265,36 +265,35 @@ This method is similar to notifySubscribersOnNextTick but it is built for workin
265
265
  so that keysChanged() is triggered for the collection and not keyChanged(). If this was not done, then the
266
266
  subscriber callbacks receive the data in a different format than they normally expect and it breaks code.
267
267
 
268
- **Kind**: global function
268
+ **Kind**: global function
269
269
 
270
270
  | Param | Type |
271
271
  | --- | --- |
272
- | key | <code>String</code> |
273
- | value | <code>\*</code> |
272
+ | key | <code>String</code> |
273
+ | value | <code>\*</code> |
274
274
 
275
275
  <a name="broadcastUpdate"></a>
276
276
 
277
- ## broadcastUpdate(key, value, method, hasChanged, wasRemoved) ⇒ <code>Promise</code>
277
+ ## broadcastUpdate(key, value, hasChanged, wasRemoved) ⇒ <code>Promise</code>
278
278
  Notifys subscribers and writes current value to cache
279
279
 
280
- **Kind**: global function
280
+ **Kind**: global function
281
281
 
282
282
  | Param | Type | Default |
283
283
  | --- | --- | --- |
284
- | key | <code>String</code> | |
285
- | value | <code>\*</code> | |
286
- | method | <code>String</code> | |
287
- | hasChanged | <code>Boolean</code> | |
288
- | wasRemoved | <code>Boolean</code> | <code>false</code> |
284
+ | key | <code>String</code> | |
285
+ | value | <code>\*</code> | |
286
+ | hasChanged | <code>Boolean</code> | |
287
+ | wasRemoved | <code>Boolean</code> | <code>false</code> |
289
288
 
290
289
  <a name="hasPendingMergeForKey"></a>
291
290
 
292
291
  ## hasPendingMergeForKey(key) ⇒ <code>Boolean</code>
293
- **Kind**: global function
292
+ **Kind**: global function
294
293
 
295
294
  | Param | Type |
296
295
  | --- | --- |
297
- | key | <code>String</code> |
296
+ | key | <code>String</code> |
298
297
 
299
298
  <a name="removeNullValues"></a>
300
299
 
@@ -302,20 +301,20 @@ Notifys subscribers and writes current value to cache
302
301
  Removes a key from storage if the value is null.
303
302
  Otherwise removes all nested null values in objects and returns the object
304
303
 
305
- **Kind**: global function
306
- **Returns**: <code>Mixed</code> - The value without null values and a boolean "wasRemoved", which indicates if the key got removed completely
304
+ **Kind**: global function
305
+ **Returns**: <code>Mixed</code> - The value without null values and a boolean "wasRemoved", which indicates if the key got removed completely
307
306
 
308
307
  | Param | Type |
309
308
  | --- | --- |
310
- | key | <code>String</code> |
311
- | value | <code>Mixed</code> |
309
+ | key | <code>String</code> |
310
+ | value | <code>Mixed</code> |
312
311
 
313
312
  <a name="set"></a>
314
313
 
315
314
  ## set(key, value) ⇒ <code>Promise</code>
316
315
  Write a value to our store with the given key
317
316
 
318
- **Kind**: global function
317
+ **Kind**: global function
319
318
 
320
319
  | Param | Type | Description |
321
320
  | --- | --- | --- |
@@ -327,13 +326,13 @@ Write a value to our store with the given key
327
326
  ## multiSet(data) ⇒ <code>Promise</code>
328
327
  Sets multiple keys and values
329
328
 
330
- **Kind**: global function
329
+ **Kind**: global function
331
330
 
332
331
  | Param | Type | Description |
333
332
  | --- | --- | --- |
334
333
  | data | <code>Object</code> | object keyed by ONYXKEYS and the values to set |
335
334
 
336
- **Example**
335
+ **Example**
337
336
  ```js
338
337
  Onyx.multiSet({'key1': 'a', 'key2': 'b'});
339
338
  ```
@@ -349,14 +348,14 @@ Calls to `Onyx.merge()` are batched so that any calls performed in a single tick
349
348
  applied in the order they were called. Note: `Onyx.set()` calls do not work this way so use caution when mixing
350
349
  `Onyx.merge()` and `Onyx.set()`.
351
350
 
352
- **Kind**: global function
351
+ **Kind**: global function
353
352
 
354
353
  | Param | Type | Description |
355
354
  | --- | --- | --- |
356
355
  | key | <code>String</code> | ONYXKEYS key |
357
356
  | changes | <code>Object</code> \| <code>Array</code> | Object or Array value to merge |
358
357
 
359
- **Example**
358
+ **Example**
360
359
  ```js
361
360
  Onyx.merge(ONYXKEYS.EMPLOYEE_LIST, ['Joe']); // -> ['Joe']
362
361
  Onyx.merge(ONYXKEYS.EMPLOYEE_LIST, ['Jack']); // -> ['Joe', 'Jack']
@@ -384,7 +383,7 @@ Onyx.get(key) before calling Storage.setItem() via Onyx.set().
384
383
  Storage.setItem() from Onyx.clear() will have already finished and the merged
385
384
  value will be saved to storage after the default value.
386
385
 
387
- **Kind**: global function
386
+ **Kind**: global function
388
387
 
389
388
  | Param | Type | Description |
390
389
  | --- | --- | --- |
@@ -395,14 +394,14 @@ value will be saved to storage after the default value.
395
394
  ## mergeCollection(collectionKey, collection) ⇒ <code>Promise</code>
396
395
  Merges a collection based on their keys
397
396
 
398
- **Kind**: global function
397
+ **Kind**: global function
399
398
 
400
399
  | Param | Type | Description |
401
400
  | --- | --- | --- |
402
401
  | collectionKey | <code>String</code> | e.g. `ONYXKEYS.COLLECTION.REPORT` |
403
402
  | collection | <code>Object</code> | Object collection keyed by individual collection member keys and values |
404
403
 
405
- **Example**
404
+ **Example**
406
405
  ```js
407
406
  Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, {
408
407
  [`${ONYXKEYS.COLLECTION.REPORT}1`]: report1,
@@ -414,8 +413,8 @@ Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, {
414
413
  ## update(data) ⇒ <code>Promise</code>
415
414
  Insert API responses and lifecycle data into Onyx
416
415
 
417
- **Kind**: global function
418
- **Returns**: <code>Promise</code> - resolves when all operations are complete
416
+ **Kind**: global function
417
+ **Returns**: <code>Promise</code> - resolves when all operations are complete
419
418
 
420
419
  | Param | Type | Description |
421
420
  | --- | --- | --- |
@@ -426,7 +425,7 @@ Insert API responses and lifecycle data into Onyx
426
425
  ## init([options])
427
426
  Initialize the store with actions and listening for storage events
428
427
 
429
- **Kind**: global function
428
+ **Kind**: global function
430
429
 
431
430
  | Param | Type | Default | Description |
432
431
  | --- | --- | --- | --- |
@@ -439,7 +438,7 @@ Initialize the store with actions and listening for storage events
439
438
  | [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) |
440
439
  | [options.debugSetState] | <code>Boolean</code> | | Enables debugging setState() calls to connected components. |
441
440
 
442
- **Example**
441
+ **Example**
443
442
  ```js
444
443
  Onyx.init({
445
444
  keys: ONYXKEYS,
package/dist/DevTools.js CHANGED
@@ -15,7 +15,6 @@ class DevTools {
15
15
  if ((options && options.remote) || typeof window === 'undefined' || !reduxDevtools) {
16
16
  return;
17
17
  }
18
- // eslint-disable-next-line no-underscore-dangle, @typescript-eslint/no-explicit-any
19
18
  return reduxDevtools.connect(options);
20
19
  }
21
20
  catch (e) {
package/dist/Onyx.d.ts CHANGED
@@ -1,156 +1,7 @@
1
- import {Component} from 'react';
2
1
  import * as Logger from './Logger';
3
- import {CollectionKey, CollectionKeyBase, DeepRecord, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, Selector} from './types';
4
-
5
- /**
6
- * Represents a mapping object where each `OnyxKey` maps to either a value of its corresponding type in `KeyValueMapping` or `null`.
7
- *
8
- * It's very similar to `KeyValueMapping` but this type accepts using `null` as well.
9
- */
10
- type NullableKeyValueMapping = {
11
- [TKey in OnyxKey]: OnyxEntry<KeyValueMapping[TKey]>;
12
- };
13
-
14
- /**
15
- * Represents the base options used in `Onyx.connect()` method.
16
- */
17
- type BaseConnectOptions = {
18
- statePropertyName?: string;
19
- withOnyxInstance?: Component;
20
- initWithStoredValues?: boolean;
21
- };
22
-
23
- type TryGetCachedValueMapping<TKey extends OnyxKey> = {
24
- selector?: Selector<TKey, unknown, unknown>;
25
- withOnyxInstance?: Component;
26
- };
27
-
28
- /**
29
- * Represents the options used in `Onyx.connect()` method.
30
- * The type is built from `BaseConnectOptions` and extended to handle key/callback related options.
31
- * It includes two different forms, depending on whether we are waiting for a collection callback or not.
32
- *
33
- * If `waitForCollectionCallback` is `true`, it expects `key` to be a Onyx collection key and `callback` will be triggered with the whole collection
34
- * and will pass `value` as an `OnyxCollection`.
35
- *
36
- *
37
- * If `waitForCollectionCallback` is `false` or not specified, the `key` can be any Onyx key and `callback` will be triggered with updates of each collection item
38
- * and will pass `value` as an `OnyxEntry`.
39
- */
40
- type ConnectOptions<TKey extends OnyxKey> = BaseConnectOptions &
41
- (
42
- | {
43
- key: TKey extends CollectionKeyBase ? TKey : never;
44
- callback?: (value: OnyxCollection<KeyValueMapping[TKey]>) => void;
45
- waitForCollectionCallback: true;
46
- }
47
- | {
48
- key: TKey;
49
- callback?: (value: OnyxEntry<KeyValueMapping[TKey]>, key: TKey) => void;
50
- waitForCollectionCallback?: false;
51
- }
52
- );
53
-
54
- /**
55
- * Represents a mapping between Onyx collection keys and their respective values.
56
- *
57
- * It helps to enforce that a Onyx collection key should not be without suffix (e.g. should always be of the form `${TKey}${string}`),
58
- * and to map each Onyx collection key with suffix to a value of type `TValue`.
59
- *
60
- * Also, the `TMap` type is inferred automatically in `mergeCollection()` method and represents
61
- * the object of collection keys/values specified in the second parameter of the method.
62
- */
63
- type Collection<TKey extends CollectionKeyBase, TMap, TValue> = {
64
- [MapK in keyof TMap]: MapK extends `${TKey}${string}`
65
- ? MapK extends `${TKey}`
66
- ? never // forbids empty id
67
- : TValue
68
- : never;
69
- };
70
-
71
- /**
72
- * Represents different kinds of updates that can be passed to `Onyx.update()` method. It is a discriminated union of
73
- * different update methods (`SET`, `MERGE`, `MERGE_COLLECTION`), each with their own key and value structure.
74
- */
75
- type OnyxUpdate =
76
- | {
77
- [TKey in OnyxKey]:
78
- | {
79
- onyxMethod: typeof METHOD.SET;
80
- key: TKey;
81
- value: OnyxEntry<KeyValueMapping[TKey]>;
82
- }
83
- | {
84
- onyxMethod: typeof METHOD.MERGE;
85
- key: TKey;
86
- value: OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>;
87
- };
88
- }[OnyxKey]
89
- | {
90
- [TKey in CollectionKeyBase]: {
91
- onyxMethod: typeof METHOD.MERGE_COLLECTION;
92
- key: TKey;
93
- value: Record<`${TKey}${string}`, NullishDeep<KeyValueMapping[TKey]>>;
94
- };
95
- }[CollectionKeyBase];
96
-
97
- /**
98
- * Represents the options used in `Onyx.init()` method.
99
- */
100
- type InitOptions = {
101
- keys?: DeepRecord<string, OnyxKey>;
102
- initialKeyStates?: Partial<NullableKeyValueMapping>;
103
- safeEvictionKeys?: OnyxKey[];
104
- maxCachedKeysCount?: number;
105
- shouldSyncMultipleInstances?: boolean;
106
- debugSetState?: boolean;
107
- };
108
-
109
- declare const METHOD: {
110
- readonly SET: 'set';
111
- readonly MERGE: 'merge';
112
- readonly MERGE_COLLECTION: 'mergecollection';
113
- readonly MULTI_SET: 'multiset';
114
- readonly CLEAR: 'clear';
115
- };
116
-
117
- /**
118
- * Returns current key names stored in persisted storage
119
- */
120
- declare function getAllKeys(): Promise<Array<OnyxKey>>;
121
-
122
- /**
123
- * Checks to see if the a subscriber's supplied key
124
- * is associated with a collection of keys.
125
- */
126
- declare function isCollectionKey(key: OnyxKey): key is CollectionKeyBase;
127
-
128
- declare function isCollectionMemberKey<TCollectionKey extends CollectionKeyBase>(collectionKey: TCollectionKey, key: string): key is `${TCollectionKey}${string}`;
129
-
130
- /**
131
- * Splits a collection member key into the collection key part and the ID part.
132
- * @param key - The collection member key to split.
133
- * @returns A tuple where the first element is the collection part and the second element is the ID part.
134
- */
135
- declare function splitCollectionMemberKey<TKey extends CollectionKey>(key: TKey): [TKey extends `${infer Prefix}_${string}` ? `${Prefix}_` : never, string];
136
-
137
- /**
138
- * Checks to see if this key has been flagged as
139
- * safe for removal.
140
- */
141
- declare function isSafeEvictionKey(testKey: OnyxKey): boolean;
142
-
143
- /**
144
- * Removes a key previously added to this list
145
- * which will enable it to be deleted again.
146
- */
147
- declare function removeFromEvictionBlockList(key: OnyxKey, connectionID: number): void;
148
-
149
- /**
150
- * Keys added to this list can never be deleted.
151
- */
152
- declare function addToEvictionBlockList(key: OnyxKey, connectionID: number): void;
153
-
2
+ import type { Collection, CollectionKeyBase, ConnectOptions, InitOptions, KeyValueMapping, Mapping, NullableKeyValueMapping, NullishDeep, OnyxEntry, OnyxKey, OnyxUpdate } from './types';
3
+ /** Initialize the store with actions and listening for storage events */
4
+ declare function init({ keys, initialKeyStates, safeEvictionKeys, maxCachedKeysCount, shouldSyncMultipleInstances, debugSetState, }: InitOptions): void;
154
5
  /**
155
6
  * Subscribes a react component's state directly to a store key
156
7
  *
@@ -170,10 +21,16 @@ declare function addToEvictionBlockList(key: OnyxKey, connectionID: number): voi
170
21
  * @param [mapping.initWithStoredValues] If set to false, then no data will be prefilled into the
171
22
  * component
172
23
  * @param [mapping.waitForCollectionCallback] If set to true, it will return the entire collection to the callback as a single object
24
+ * @param [mapping.selector] THIS PARAM IS ONLY USED WITH withOnyx(). If included, this will be used to subscribe to a subset of an Onyx key's data.
25
+ * The sourceData and withOnyx state are passed to the selector and should return the simplified data. Using this setting on `withOnyx` can have very positive
26
+ * performance benefits because the component will only re-render when the subset of data changes. Otherwise, any change of data on any property would normally
27
+ * cause the component to re-render (and that can be expensive from a performance standpoint).
28
+ * @param [mapping.initialValue] THIS PARAM IS ONLY USED WITH withOnyx().
29
+ * If included, this will be passed to the component so that something can be rendered while data is being fetched from the DB.
30
+ * Note that it will not cause the component to have the loading prop set to true.
173
31
  * @returns an ID to use when calling disconnect
174
32
  */
175
33
  declare function connect<TKey extends OnyxKey>(mapping: ConnectOptions<TKey>): number;
176
-
177
34
  /**
178
35
  * Remove the listener for a react component
179
36
  * @example
@@ -182,15 +39,13 @@ declare function connect<TKey extends OnyxKey>(mapping: ConnectOptions<TKey>): n
182
39
  * @param connectionID unique id returned by call to Onyx.connect()
183
40
  */
184
41
  declare function disconnect(connectionID: number, keyToRemoveFromEvictionBlocklist?: OnyxKey): void;
185
-
186
42
  /**
187
43
  * Write a value to our store with the given key
188
44
  *
189
45
  * @param key ONYXKEY to set
190
46
  * @param value value to store
191
47
  */
192
- declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<KeyValueMapping[TKey]>): Promise<void>;
193
-
48
+ declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<KeyValueMapping[TKey]>): Promise<void[]>;
194
49
  /**
195
50
  * Sets multiple keys and values
196
51
  *
@@ -198,15 +53,12 @@ declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<KeyValueM
198
53
  *
199
54
  * @param data object keyed by ONYXKEYS and the values to set
200
55
  */
201
- declare function multiSet(data: Partial<NullableKeyValueMapping>): Promise<void>;
202
-
56
+ declare function multiSet(data: Partial<NullableKeyValueMapping>): Promise<void[]>;
203
57
  /**
204
58
  * Merge a new value into an existing value at a key.
205
59
  *
206
- * The types of values that can be merged are `Object` and `Array`. To set another type of value use `Onyx.set()`. Merge
207
- * behavior uses lodash/merge under the hood for `Object` and simple concatenation for `Array`. However, it's important
208
- * to note that if you have an array value property on an `Object` that the default behavior of lodash/merge is not to
209
- * concatenate. See here: https://github.com/lodash/lodash/issues/2872
60
+ * The types of values that can be merged are `Object` and `Array`. To set another type of value use `Onyx.set()`.
61
+ * Values of type `Object` get merged with the old value, whilst for `Array`'s we simply replace the current value with the new one.
210
62
  *
211
63
  * Calls to `Onyx.merge()` are batched so that any calls performed in a single tick will stack in a queue and get
212
64
  * applied in the order they were called. Note: `Onyx.set()` calls do not work this way so use caution when mixing
@@ -217,12 +69,22 @@ declare function multiSet(data: Partial<NullableKeyValueMapping>): Promise<void>
217
69
  * Onyx.merge(ONYXKEYS.EMPLOYEE_LIST, ['Jack']); // -> ['Joe', 'Jack']
218
70
  * Onyx.merge(ONYXKEYS.POLICY, {id: 1}); // -> {id: 1}
219
71
  * Onyx.merge(ONYXKEYS.POLICY, {name: 'My Workspace'}); // -> {id: 1, name: 'My Workspace'}
72
+ */
73
+ declare function merge<TKey extends OnyxKey>(key: TKey, changes: OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>): Promise<void | void[]>;
74
+ /**
75
+ * Merges a collection based on their keys
76
+ *
77
+ * @example
78
+ *
79
+ * Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, {
80
+ * [`${ONYXKEYS.COLLECTION.REPORT}1`]: report1,
81
+ * [`${ONYXKEYS.COLLECTION.REPORT}2`]: report2,
82
+ * });
220
83
  *
221
- * @param key ONYXKEYS key
222
- * @param value Object or Array value to merge
84
+ * @param collectionKey e.g. `ONYXKEYS.COLLECTION.REPORT`
85
+ * @param collection Object collection keyed by individual collection member keys and values
223
86
  */
224
- declare function merge<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>): Promise<void>;
225
-
87
+ declare function mergeCollection<TKey extends CollectionKeyBase, TMap>(collectionKey: TKey, collection: Collection<TKey, TMap, NullishDeep<KeyValueMapping[TKey]>>): Promise<void>;
226
88
  /**
227
89
  * Clear out all the data in the store
228
90
  *
@@ -244,97 +106,32 @@ declare function merge<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<Nullish
244
106
  *
245
107
  * @param keysToPreserve is a list of ONYXKEYS that should not be cleared with the rest of the data
246
108
  */
247
- declare function clear(keysToPreserve?: OnyxKey[]): Promise<void>;
248
-
249
- /**
250
- * Merges a collection based on their keys
251
- *
252
- * Note that both `TKey` and `TMap` types are inferred automatically, `TKey` being the
253
- * collection key specified in the first parameter and `TMap` being the object of
254
- * collection keys/values specified in the second parameter.
255
- *
256
- * @example
257
- *
258
- * Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, {
259
- * [`${ONYXKEYS.COLLECTION.REPORT}1`]: report1,
260
- * [`${ONYXKEYS.COLLECTION.REPORT}2`]: report2,
261
- * });
262
- *
263
- * @param collectionKey e.g. `ONYXKEYS.COLLECTION.REPORT`
264
- * @param collection Object collection keyed by individual collection member keys and values
265
- */
266
- declare function mergeCollection<TKey extends CollectionKeyBase, TMap>(collectionKey: TKey, collection: Collection<TKey, TMap, NullishDeep<KeyValueMapping[TKey]>>): Promise<void>;
267
-
109
+ declare function clear(keysToPreserve?: OnyxKey[]): Promise<void[]>;
268
110
  /**
269
111
  * Insert API responses and lifecycle data into Onyx
270
112
  *
271
- * @param data An array of update objects
113
+ * @param data An array of objects with shape {onyxMethod: oneOf('set', 'merge', 'mergeCollection', 'multiSet', 'clear'), key: string, value: *}
272
114
  * @returns resolves when all operations are complete
273
115
  */
274
- declare function update(data: OnyxUpdate[]): Promise<void>;
275
-
276
- /**
277
- * Initialize the store with actions and listening for storage events
278
- *
279
- * @param [options={}] config object
280
- * @param [options.keys={}] `ONYXKEYS` constants object
281
- * @param [options.initialKeyStates={}] initial data to set when `init()` and `clear()` is called
282
- * @param [options.safeEvictionKeys=[]] This is an array of keys
283
- * (individual or collection patterns) that when provided to Onyx are flagged
284
- * as "safe" for removal. Any components subscribing to these keys must also
285
- * implement a canEvict option. See the README for more info.
286
- * @param [options.maxCachedKeysCount=55] Sets how many recent keys should we try to keep in cache
287
- * Setting this to 0 would practically mean no cache
288
- * We try to free cache when we connect to a safe eviction key
289
- * @param [options.shouldSyncMultipleInstances] Auto synchronize storage events between multiple instances
290
- * of Onyx running in different tabs/windows. Defaults to true for platforms that support local storage (web/desktop)
291
- * @param [options.debugSetState] Enables debugging setState() calls to connected components.
292
- * @example
293
- * Onyx.init({
294
- * keys: ONYXKEYS,
295
- * initialKeyStates: {
296
- * [ONYXKEYS.SESSION]: {loading: false},
297
- * },
298
- * });
299
- */
300
- declare function init(config?: InitOptions): void;
301
-
302
- /**
303
- * @private
304
- */
305
- declare function hasPendingMergeForKey(key: OnyxKey): boolean;
306
-
307
- /**
308
- * Tries to get a value from the cache. If the value is not present in cache it will return the default value or undefined.
309
- * If the requested key is a collection, it will return an object with all the collection members.
310
- */
311
- declare function tryGetCachedValue<TKey extends OnyxKey>(
312
- key: TKey,
313
- mapping?: TryGetCachedValueMapping,
314
- ): TKey extends CollectionKeyBase ? OnyxCollection<KeyValueMapping[TKey]> | undefined : OnyxEntry<KeyValueMapping[TKey]> | undefined;
315
-
116
+ declare function update(data: OnyxUpdate[]): Promise<Array<void | void[]>>;
316
117
  declare const Onyx: {
317
- connect: typeof connect;
318
- disconnect: typeof disconnect;
319
- set: typeof set;
320
- multiSet: typeof multiSet;
321
- merge: typeof merge;
322
- mergeCollection: typeof mergeCollection;
323
- hasPendingMergeForKey: typeof hasPendingMergeForKey;
324
- update: typeof update;
325
- clear: typeof clear;
326
- getAllKeys: typeof getAllKeys;
327
- init: typeof init;
328
- registerLogger: typeof Logger.registerLogger;
329
- addToEvictionBlockList: typeof addToEvictionBlockList;
330
- removeFromEvictionBlockList: typeof removeFromEvictionBlockList;
331
- isSafeEvictionKey: typeof isSafeEvictionKey;
332
- METHOD: typeof METHOD;
333
- tryGetCachedValue: typeof tryGetCachedValue;
334
- isCollectionKey: typeof isCollectionKey;
335
- isCollectionMemberKey: typeof isCollectionMemberKey;
336
- splitCollectionMemberKey: typeof splitCollectionMemberKey;
118
+ readonly METHOD: {
119
+ readonly SET: "set";
120
+ readonly MERGE: "merge";
121
+ readonly MERGE_COLLECTION: "mergecollection";
122
+ readonly MULTI_SET: "multiset";
123
+ readonly CLEAR: "clear";
124
+ };
125
+ readonly connect: typeof connect;
126
+ readonly disconnect: typeof disconnect;
127
+ readonly set: typeof set;
128
+ readonly multiSet: typeof multiSet;
129
+ readonly merge: typeof merge;
130
+ readonly mergeCollection: typeof mergeCollection;
131
+ readonly update: typeof update;
132
+ readonly clear: typeof clear;
133
+ readonly init: typeof init;
134
+ readonly registerLogger: typeof Logger.registerLogger;
337
135
  };
338
-
339
136
  export default Onyx;
340
- export {ConnectOptions, OnyxUpdate};
137
+ export type { OnyxUpdate, Mapping, ConnectOptions };