Add type declarations

lib/Onyx.d.ts

@@ -1,64 +1,105 @@
 import {Component} from 'react';
 import {PartialDeep} from 'type-fest';
 import * as Logger from './Logger';
-import {CollectionKey, DeepRecord, Key, OnyxKey, KeyValueMapping, Selector} from './types';
+import {
+    CollectionKey,
+    CollectionKeyBase,
+    DeepRecord,
+    Key,
+    KeyValueMapping,
+    OnyxCollectionEntries,
+    OnyxKey,
+    OnyxEntry,
+} 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]: KeyValueMapping[TKey] | null;
+    [TKey in OnyxKey]: OnyxEntry<KeyValueMapping[TKey]>;
 };
 
+/**
+ * Represents the base options used in `Onyx.connect()` method.
+ */
 type BaseConnectOptions<TKey extends OnyxKey> = {
     statePropertyName?: string;
     withOnyxInstance?: Component;
     initWithStoredValues?: boolean;
-    selector?: Selector<TKey, KeyValueMapping[TKey] | null>;
 };
 
+/**
+ * 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 pass `value` as an `OnyxCollectionEntries`.
+ *
+ * If `waitForCollectionCallback` is `false` or not specified, the `key` can be any Onyx key and `callback` will pass `value` as an `OnyxEntry`.
+ */
 type ConnectOptions<TKey extends OnyxKey> = BaseConnectOptions<TKey> &
     (
         | {
               key: TKey extends CollectionKey ? TKey : never;
-              callback?: (value: Record<string, KeyValueMapping[TKey] | null> | null, key?: TKey) => void;
+              callback?: (value: OnyxCollectionEntries<KeyValueMapping[TKey]>, key?: TKey) => void;
               waitForCollectionCallback: true;
           }
         | {
               key: TKey;
-              callback?: (value: KeyValueMapping[TKey] | null, key?: TKey) => void;
+              callback?: (value: OnyxEntry<KeyValueMapping[TKey]>, key?: TKey) => void;
               waitForCollectionCallback?: false;
           }
     );
 
-type Collection<TKey extends Key, TMap, TValue> = {
+/**
+ * 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`.
+ */
+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 extends OnyxKey> =
     | {
           onyxMethod: typeof METHOD.SET;
           key: TKey;
-          value: KeyValueMapping[TKey] | null;
+          value: OnyxEntry<KeyValueMapping[TKey]>;
       }
     | {
           onyxMethod: typeof METHOD.MERGE;
           key: TKey;
           value: PartialDeep<KeyValueMapping[TKey]>;
       }
     | {
-          [TKey in CollectionKey]: {
+          [TKey in CollectionKeyBase]: {
               onyxMethod: typeof METHOD.MERGE_COLLECTION;
               key: TKey;
               value: Record<`${TKey}${string}`, PartialDeep<KeyValueMapping[TKey]>>;
           };
-      }[CollectionKey];
+      }[CollectionKeyBase];
 
+/**
+ * Represents a record of `OnyxUpdate`s to be passed to `Onyx.update()` method, indexed by keys of type `OnyxKey`.
+ * Each `OnyxUpdate` will be associated with its respective Onyx key, ensuring different type-safety for each object.
+ */
 type OnyxUpdates<TKeyList extends OnyxKey[]> = {
     [TKey in keyof TKeyList]: OnyxUpdate<TKeyList[TKey]>;
 };
 
+/**
+ * Represents the options used in `Onyx.init()` method.
+ */
 type InitOptions = {
     keys?: DeepRecord<string, string>;
     initialKeyStates?: Partial<NullableKeyValueMapping>;
@@ -84,25 +125,17 @@ declare function getAllKeys(): Promise<Array<OnyxKey>>;
 /**
  * Checks to see if this key has been flagged as
  * safe for removal.
- *
- * @param testKey
  */
 declare function isSafeEvictionKey(testKey: OnyxKey): boolean;
 
 /**
  * Removes a key previously added to this list
  * which will enable it to be deleted again.
- *
- * @param key
- * @param connectionID
  */
 declare function removeFromEvictionBlockList(key: OnyxKey, connectionID: number): void;
 
 /**
  * Keys added to this list can never be deleted.
- *
- * @param key
- * @param connectionID
  */
 declare function addToEvictionBlockList(key: OnyxKey, connectionID: number): void;
 
@@ -125,11 +158,6 @@ 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.
- *       If the selector is a string, the selector is passed to lodashGet on the sourceData. If the selector is a function, 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).
  * @returns an ID to use when calling disconnect
  */
 declare function connect<TKey extends OnyxKey>(mapping: ConnectOptions<TKey>): number;
@@ -140,7 +168,6 @@ declare function connect<TKey extends OnyxKey>(mapping: ConnectOptions<TKey>): n
  * Onyx.disconnect(connectionID);
  *
  * @param connectionID unique id returned by call to Onyx.connect()
- * @param [keyToRemoveFromEvictionBlocklist]
  */
 declare function disconnect(connectionID: number, keyToRemoveFromEvictionBlocklist?: OnyxKey): void;
 
@@ -150,7 +177,7 @@ declare function disconnect(connectionID: number, keyToRemoveFromEvictionBlockli
  * @param key ONYXKEY to set
  * @param value value to store
  */
-declare function set<TKey extends OnyxKey>(key: TKey, value: KeyValueMapping[TKey] | null): Promise<void>;
+declare function set<TKey extends OnyxKey>(key: TKey, value: OnyxEntry<KeyValueMapping[TKey]>): Promise<void>;
 
 /**
  * Sets multiple keys and values
@@ -220,7 +247,10 @@ declare function clear(keysToPreserve?: OnyxKey[]): Promise<void>;
  * @param collectionKey e.g. `ONYXKEYS.COLLECTION.REPORT`
  * @param collection Object collection keyed by individual collection member keys and values
  */
-declare function mergeCollection<TKey extends CollectionKey, TMap>(collectionKey: TKey, collection: Collection<TKey, TMap, PartialDeep<KeyValueMapping[TKey]>>): Promise<void>;
+declare function mergeCollection<TKey extends CollectionKeyBase, TMap>(
+    collectionKey: TKey,
+    collection: Collection<TKey, TMap, PartialDeep<KeyValueMapping[TKey]>>,
+): Promise<void>;
 
 /**
  * Insert API responses and lifecycle data into Onyx
@@ -257,13 +287,24 @@ declare function update<TKeyList extends OnyxKey[]>(data: OnyxUpdates<[...TKeyLi
  */
 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;
+
 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;
@@ -273,6 +314,7 @@ declare const Onyx: {
     removeFromEvictionBlockList: typeof removeFromEvictionBlockList;
     isSafeEvictionKey: typeof isSafeEvictionKey;
     METHOD: typeof METHOD;
+    setMemoryOnlyKeys: typeof setMemoryOnlyKeys;
 };
 
 export default Onyx;

lib/index.d.ts

@@ -1,6 +1,6 @@
 import Onyx from './Onyx';
-import {CustomTypeOptions} from './types';
+import {CustomTypeOptions, OnyxCollectionEntries, OnyxEntry} from './types';
 import withOnyx from './withOnyx';
 
 export default Onyx;
-export {CustomTypeOptions, withOnyx};
+export {CustomTypeOptions, OnyxCollectionEntries, OnyxEntry, withOnyx};

lib/types.d.ts

@@ -1,9 +1,29 @@
-import {IsEqual, ValueOf} from 'type-fest';
+import {IsEqual} from 'type-fest';
 
+/**
+ * Represents a merged object between `TObject` and `TOtherObject`.
+ * If both objects have a property with the same name, the type from `TOtherObject` is used.
+ */
 type MergeBy<TObject, TOtherObject> = Omit<TObject, keyof TOtherObject> & TOtherObject;
 
+/**
+ * Represents a deeply nested record. It maps keys to values,
+ * and those values can either be of type `TValue` or further nested `DeepRecord` instances.
+ */
 type DeepRecord<TKey extends string | number | symbol, TValue> = {[key: string]: TValue | DeepRecord<TKey, TValue>};
 
+/**
+ * Represents type options to configure all Onyx methods.
+ * It's a combination of predefined options with user-provided options (CustomTypeOptions).
+ *
+ * The options are:
+ * - `keys`: Represents a string union of all Onyx normal keys.
+ * - `collectionKeys`: Represents a string union of all Onyx collection keys.
+ * - `values`: Represents a Record where each key is an Onyx key and each value is its corresponding Onyx value type.
+ *
+ * The user-defined options (CustomTypeOptions) are merged into these predefined options.
+ * In case of conflicting properties, the ones from CustomTypeOptions are prioritized.
+ */
 type TypeOptions = MergeBy<
     {
         keys: string;
@@ -13,28 +33,119 @@ type TypeOptions = MergeBy<
     CustomTypeOptions
 >;
 
+/**
+ * Represents the user-defined options to configure all Onyx methods.
+ *
+ * The developer can configure Onyx methods by augmenting this library and overriding CustomTypeOptions.
+ *
+ * @example
+ * ```ts
+ * // ONYXKEYS.ts
+ * import {ValueOf} from 'type-fest';
+ *
+ * const ONYXKEYS = {
+ *     ACCOUNT: 'account',
+ *     IS_SIDEBAR_LOADED: 'isSidebarLoaded',
+ *
+ *     // Collection Keys
+ *     COLLECTION: {
+ *         REPORT: 'report_',
+ *     },
+ * } as const;
+ *
+ * type OnyxKeysMap = typeof ONYXKEYS;
+ * type OnyxCollectionKey = ValueOf<OnyxKeysMap['COLLECTION']>;
+ * type OnyxKey = DeepValueOf<Omit<OnyxKeysMap, 'COLLECTION'>>;
+ *
+ * type OnyxValues = {
+ *     [ONYXKEYS.ACCOUNT]: Account;
+ *     [ONYXKEYS.IS_SIDEBAR_LOADED]: boolean;
+ *     [report: `${typeof ONYXKEYS.COLLECTION.REPORT}${string}`]: Report;
+ * };
+ *
+ * export default ONYXKEYS;
+ * export type {OnyxKey, OnyxCollectionKey, OnyxValues};
+ *
+ * // global.d.ts
+ * import {OnyxKey, OnyxCollectionKey, OnyxValues} from './ONYXKEYS';
+ *
+ * declare module 'react-native-onyx' {
+ *     interface CustomTypeOptions {
+ *         keys: OnyxKey;
+ *         collectionKeys: OnyxCollectionKey;
+ *         values: OnyxValues;
+ *     }
+ * }
+ * ```
+ */
 interface CustomTypeOptions {}
 
+/**
+ * Represents a string union of all Onyx normal keys.
+ */
 type Key = TypeOptions['keys'];
+
+/**
+ * Represents a string union of all Onyx collection keys.
+ */
 type CollectionKeyBase = TypeOptions['collectionKeys'];
+
+/**
+ * Represents a literal string union of all Onyx collection keys.
+ * It allows appending a string after each collection key e.g. `report_some-id`.
+ */
 type CollectionKey = `${CollectionKeyBase}${string}`;
 
+/**
+ * Represents a string union of all Onyx normal and collection keys.
+ */
 type OnyxKey = Key | CollectionKey;
+
+/**
+ * Represents a Record where each key is an Onyx key and each value is its corresponding Onyx value type.
+ */
 type KeyValueMapping = TypeOptions['values'];
 
-type GetOnyxValue<K extends Key | `${CollectionKeyBase}${string}`> = K extends Key
-    ? KeyValueMapping[K]
-    : K extends `${CollectionKeyBase}`
-    ? Record<string, KeyValueMapping[K] | null>
-    : KeyValueMapping[K];
+/**
+ * Represents a selector function type which operates based on the provided `TKey` and `ReturnType`.
+ *
+ * A `Selector` is a function that accepts a value and returns a processed value.
+ * This type accepts two type parameters: `TKey` and `TReturnType`.
+ *
+ * The type `TKey` extends `OnyxKey` and it is the key used to access a value in `KeyValueMapping`.
+ * `TReturnType` is the type of the returned value from the selector function.
+ *
+ * If `KeyValueMapping[TKey]` is equal to 'unknown', the `Selector` type represents a function
+ * that takes any value and returns an `unknown` value.
+ *
+ * If `KeyValueMapping[TKey]` is not 'unknown', the `Selector` type represents a function that
+ * takes either the value of type `OnyxEntry<KeyValueMapping[TKey]>`, and returns a value of `TReturnType`.
+ */
+type Selector<TKey extends OnyxKey, TReturnType> = IsEqual<KeyValueMapping[TKey], unknown> extends true
+    ? (value: unknown) => unknown
+    : (value: OnyxEntry<KeyValueMapping[TKey]>) => TReturnType;
 
-// type Selector<TKey extends OnyxKey, TReturnType> = KeyValueMapping[TKey] extends object | string | number | boolean
-//     ? (value: KeyValueMapping[TKey] | null) => TReturnType
-//     : KeyValueMapping[TKey] extends unknown
-//     ? (value: unknown) => unknown
-//     : never;
+/**
+ * Represents a single Onyx entry, that can be either `TOnyxValue` or `null` if it doesn't exist.
+ */
+type OnyxEntry<TOnyxValue> = TOnyxValue | null;
 
-// type Selector<TKey extends OnyxKey, TReturnType> = IsEqual<KeyValueMapping[TKey], unknown> extends true ? (value: unknown) => unknown : (value: KeyValueMapping[TKey] | null) => TReturnType;
-type Selector<TKey extends OnyxKey, TReturnType> = IsEqual<GetOnyxValue<TKey>, unknown> extends true ? (value: unknown) => unknown : (value: GetOnyxValue<TKey> | null) => TReturnType;
+/**
+ * Represents an Onyx collection of entries, that can be either a record of `TOnyxValue`s or `null` if it is empty or doesn't exist.
+ */
+type OnyxCollectionEntries<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | null>>;
 
-export {CollectionKey, CustomTypeOptions, DeepRecord, Key, MergeBy, OnyxKey, KeyValueMapping, Selector, GetOnyxValue, TypeOptions};
+export {
+    CollectionKey,
+    CollectionKeyBase,
+    CustomTypeOptions,
+    DeepRecord,
+    Key,
+    KeyValueMapping,
+    MergeBy,
+    OnyxKey,
+    Selector,
+    TypeOptions,
+    OnyxEntry,
+    OnyxCollectionEntries,
+};