react-native-onyx 2.0.21 → 2.0.23

package/dist/Onyx.d.ts

@@ -1,156 +1,7 @@
-import {Component} from 'react';
 import * as Logger from './Logger';
-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`.
- *
- * It's very similar to `KeyValueMapping` but this type accepts using `null` as well.
- */
-type NullableKeyValueMapping = {
-    [TKey in OnyxKey]: OnyxEntry<KeyValueMapping[TKey]>;
-};
-
-/**
- * Represents the base options used in `Onyx.connect()` method.
- */
-type BaseConnectOptions = {
-    statePropertyName?: string;
-    withOnyxInstance?: Component;
-    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.
- * It includes two different forms, depending on whether we are waiting for a collection callback or not.
- *
- * If `waitForCollectionCallback` is `true`, it expects `key` to be a Onyx collection key and `callback` will be triggered with the whole collection
- * and will pass `value` as an `OnyxCollection`.
- *
- *
- * 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
- * and will pass `value` as an `OnyxEntry`.
- */
-type ConnectOptions<TKey extends OnyxKey> = BaseConnectOptions &
-    (
-        | {
-              key: TKey extends CollectionKeyBase ? TKey : never;
-              callback?: (value: OnyxCollection<KeyValueMapping[TKey]>) => void;
-              waitForCollectionCallback: true;
-          }
-        | {
-              key: TKey;
-              callback?: (value: OnyxEntry<KeyValueMapping[TKey]>, key: TKey) => void;
-              waitForCollectionCallback?: false;
-          }
-    );
-
-/**
- * Represents a mapping between Onyx collection keys and their respective values.
- *
- * It helps to enforce that a Onyx collection key should not be without suffix (e.g. should always be of the form `${TKey}${string}`),
- * and to map each Onyx collection key with suffix to a value of type `TValue`.
- *
- * Also, the `TMap` type is inferred automatically in `mergeCollection()` method and represents
- * the object of collection keys/values specified in the second parameter of the method.
- */
-type Collection<TKey extends CollectionKeyBase, TMap, TValue> = {
-    [MapK in keyof TMap]: MapK extends `${TKey}${string}`
-        ? MapK extends `${TKey}`
-            ? never // forbids empty id
-            : TValue
-        : never;
-};
-
-/**
- * Represents different kinds of updates that can be passed to `Onyx.update()` method. It is a discriminated union of
- * different update methods (`SET`, `MERGE`, `MERGE_COLLECTION`), each with their own key and value structure.
- */
-type OnyxUpdate =
-    | {
-          [TKey in OnyxKey]:
-              | {
-                    onyxMethod: typeof METHOD.SET;
-                    key: TKey;
-                    value: OnyxEntry<KeyValueMapping[TKey]>;
-                }
-              | {
-                    onyxMethod: typeof METHOD.MERGE;
-                    key: TKey;
-                    value: OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>;
-                };
-      }[OnyxKey]
-    | {
-          [TKey in CollectionKeyBase]: {
-              onyxMethod: typeof METHOD.MERGE_COLLECTION;
-              key: TKey;
-              value: Record<`${TKey}${string}`, NullishDeep<KeyValueMapping[TKey]>>;
-          };
-      }[CollectionKeyBase];
-
-/**
- * Represents the options used in `Onyx.init()` method.
- */
-type InitOptions = {
-    keys?: DeepRecord<string, OnyxKey>;
-    initialKeyStates?: Partial<NullableKeyValueMapping>;
-    safeEvictionKeys?: OnyxKey[];
-    maxCachedKeysCount?: number;
-    shouldSyncMultipleInstances?: boolean;
-    debugSetState?: boolean;
-};
-
-declare const METHOD: {
-    readonly SET: 'set';
-    readonly MERGE: 'merge';
-    readonly MERGE_COLLECTION: 'mergecollection';
-    readonly MULTI_SET: 'multiset';
-    readonly CLEAR: 'clear';
-};
-
-/**
- * Returns current key names stored in persisted storage
- */
-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.
- */
-declare function isSafeEvictionKey(testKey: OnyxKey): boolean;
-
-/**
- * Removes a key previously added to this list
- * which will enable it to be deleted again.
- */
-declare function removeFromEvictionBlockList(key: OnyxKey, connectionID: number): void;
-
-/**
- * Keys added to this list can never be deleted.
- */
-declare function addToEvictionBlockList(key: OnyxKey, connectionID: number): void;
-
+import type { Collection, CollectionKeyBase, ConnectOptions, InitOptions, KeyValueMapping, Mapping, NullableKeyValueMapping, NullishDeep, OnyxEntry, OnyxKey, OnyxUpdate } from './types';
+/** Initialize the store with actions and listening for storage events */
+declare function init({ keys, initialKeyStates, safeEvictionKeys, maxCachedKeysCount, shouldSyncMultipleInstances, debugSetState, }: InitOptions): void;
 /**
  * Subscribes a react component's state directly to a store key
  *
@@ -170,10 +21,16 @@ declare function addToEvictionBlockList(key: OnyxKey, connectionID: number): voi
  * @param [mapping.initWithStoredValues] If set to false, then no data will be prefilled into the
  *  component
  * @param [mapping.waitForCollectionCallback] If set to true, it will return the entire collection to the callback as a single object
+ * @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.
+ *       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).
+ * @param [mapping.initialValue] 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.
  * @returns an ID to use when calling disconnect
  */
 declare function connect<TKey extends OnyxKey>(mapping: ConnectOptions<TKey>): number;
-
 /**
  * Remove the listener for a react component
  * @example
@@ -182,15 +39,13 @@ declare function connect<TKey extends OnyxKey>(mapping: ConnectOptions<TKey>): n
  * @param connectionID unique id returned by call to Onyx.connect()
  */
 declare function disconnect(connectionID: number, keyToRemoveFromEvictionBlocklist?: OnyxKey): void;
-
 /**
  * Write a value to our store with the given key
  *
  * @param key ONYXKEY to set
  * @param value value to store
  */
-declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<KeyValueMapping[TKey]>): Promise<void>;
-
+declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<KeyValueMapping[TKey]>): Promise<void[]>;
 /**
  * Sets multiple keys and values
  *
@@ -198,15 +53,12 @@ declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<KeyValueM
  *
  * @param data object keyed by ONYXKEYS and the values to set
  */
-declare function multiSet(data: Partial<NullableKeyValueMapping>): Promise<void>;
-
+declare function multiSet(data: Partial<NullableKeyValueMapping>): Promise<void[]>;
 /**
  * Merge a new value into an existing value at a key.
  *
- * The types of values that can be merged are `Object` and `Array`. To set another type of value use `Onyx.set()`. Merge
- * behavior uses lodash/merge under the hood for `Object` and simple concatenation for `Array`. However, it's important
- * to note that if you have an array value property on an `Object` that the default behavior of lodash/merge is not to
- * concatenate. See here: https://github.com/lodash/lodash/issues/2872
+ * The types of values that can be merged are `Object` and `Array`. To set another type of value use `Onyx.set()`.
+ * Values of type `Object` get merged with the old value, whilst for `Array`'s we simply replace the current value with the new one.
  *
  * Calls to `Onyx.merge()` are batched so that any calls performed in a single tick will stack in a queue and get
  * 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>
  * Onyx.merge(ONYXKEYS.EMPLOYEE_LIST, ['Jack']); // -> ['Joe', 'Jack']
  * Onyx.merge(ONYXKEYS.POLICY, {id: 1}); // -> {id: 1}
  * Onyx.merge(ONYXKEYS.POLICY, {name: 'My Workspace'}); // -> {id: 1, name: 'My Workspace'}
+ */
+declare function merge<TKey extends OnyxKey>(key: TKey, changes: OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>): Promise<void | void[]>;
+/**
+ * Merges a collection based on their keys
+ *
+ * @example
+ *
+ * Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, {
+ *     [`${ONYXKEYS.COLLECTION.REPORT}1`]: report1,
+ *     [`${ONYXKEYS.COLLECTION.REPORT}2`]: report2,
+ * });
  *
- * @param key ONYXKEYS key
- * @param value Object or Array value to merge
+ * @param collectionKey e.g. `ONYXKEYS.COLLECTION.REPORT`
+ * @param collection Object collection keyed by individual collection member keys and values
  */
-declare function merge<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>): Promise<void>;
-
+declare function mergeCollection<TKey extends CollectionKeyBase, TMap>(collectionKey: TKey, collection: Collection<TKey, TMap, NullishDeep<KeyValueMapping[TKey]>>): Promise<void>;
 /**
  * Clear out all the data in the store
  *
@@ -244,103 +106,32 @@ declare function merge<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<Nullish
  *
  * @param keysToPreserve is a list of ONYXKEYS that should not be cleared with the rest of the data
  */
-declare function clear(keysToPreserve?: OnyxKey[]): Promise<void>;
-
-/**
- * Merges a collection based on their keys
- *
- * Note that both `TKey` and `TMap` types are inferred automatically, `TKey` being the
- * collection key specified in the first parameter and `TMap` being the object of
- * collection keys/values specified in the second parameter.
- *
- * @example
- *
- * Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, {
- *     [`${ONYXKEYS.COLLECTION.REPORT}1`]: report1,
- *     [`${ONYXKEYS.COLLECTION.REPORT}2`]: report2,
- * });
- *
- * @param collectionKey e.g. `ONYXKEYS.COLLECTION.REPORT`
- * @param collection Object collection keyed by individual collection member keys and values
- */
-declare function mergeCollection<TKey extends CollectionKeyBase, TMap>(collectionKey: TKey, collection: Collection<TKey, TMap, NullishDeep<KeyValueMapping[TKey]>>): Promise<void>;
-
+declare function clear(keysToPreserve?: OnyxKey[]): Promise<void[]>;
 /**
  * Insert API responses and lifecycle data into Onyx
  *
- * @param data An array of update objects
+ * @param data An array of objects with shape {onyxMethod: oneOf('set', 'merge', 'mergeCollection', 'multiSet', 'clear'), key: string, value: *}
  * @returns resolves when all operations are complete
  */
-declare function update(data: OnyxUpdate[]): Promise<void>;
-
-/**
- * Initialize the store with actions and listening for storage events
- *
- * @param [options={}] config object
- * @param [options.keys={}] `ONYXKEYS` constants object
- * @param [options.initialKeyStates={}] initial data to set when `init()` and `clear()` is called
- * @param [options.safeEvictionKeys=[]] This is an array of keys
- * (individual or collection patterns) that when provided to Onyx are flagged
- * as "safe" for removal. Any components subscribing to these keys must also
- * implement a canEvict option. See the README for more info.
- * @param [options.maxCachedKeysCount=55] Sets how many recent keys should we try to keep in cache
- * Setting this to 0 would practically mean no cache
- * We try to free cache when we connect to a safe eviction key
- * @param [options.shouldSyncMultipleInstances] 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)
- * @param [options.debugSetState] Enables debugging setState() calls to connected components.
- * @example
- * Onyx.init({
- *     keys: ONYXKEYS,
- *     initialKeyStates: {
- *         [ONYXKEYS.SESSION]: {loading: false},
- *     },
- * });
- */
-declare function init(config?: InitOptions): void;
-
-/**
- * @private
- */
-declare function hasPendingMergeForKey(key: OnyxKey): boolean;
-
-/**
- * When set these keys will not be persisted to storage
- */
-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 function update(data: OnyxUpdate[]): Promise<Array<void | void[]>>;
 declare const Onyx: {
-    connect: typeof connect;
-    disconnect: typeof disconnect;
-    set: typeof set;
-    multiSet: typeof multiSet;
-    merge: typeof merge;
-    mergeCollection: typeof mergeCollection;
-    hasPendingMergeForKey: typeof hasPendingMergeForKey;
-    update: typeof update;
-    clear: typeof clear;
-    getAllKeys: typeof getAllKeys;
-    init: typeof init;
-    registerLogger: typeof Logger.registerLogger;
-    addToEvictionBlockList: typeof addToEvictionBlockList;
-    removeFromEvictionBlockList: typeof removeFromEvictionBlockList;
-    isSafeEvictionKey: typeof isSafeEvictionKey;
-    METHOD: typeof METHOD;
-    setMemoryOnlyKeys: typeof setMemoryOnlyKeys;
-    tryGetCachedValue: typeof tryGetCachedValue;
-    isCollectionKey: typeof isCollectionKey;
-    isCollectionMemberKey: typeof isCollectionMemberKey;
-    splitCollectionMemberKey: typeof splitCollectionMemberKey;
+    readonly METHOD: {
+        readonly SET: "set";
+        readonly MERGE: "merge";
+        readonly MERGE_COLLECTION: "mergecollection";
+        readonly MULTI_SET: "multiset";
+        readonly CLEAR: "clear";
+    };
+    readonly connect: typeof connect;
+    readonly disconnect: typeof disconnect;
+    readonly set: typeof set;
+    readonly multiSet: typeof multiSet;
+    readonly merge: typeof merge;
+    readonly mergeCollection: typeof mergeCollection;
+    readonly update: typeof update;
+    readonly clear: typeof clear;
+    readonly init: typeof init;
+    readonly registerLogger: typeof Logger.registerLogger;
 };
-
 export default Onyx;
-export {ConnectOptions, OnyxUpdate};
+export type { OnyxUpdate, Mapping, ConnectOptions };