Add type declarations

lib/Onyx.d.ts

@@ -5,11 +5,10 @@ import {
     CollectionKey,
     CollectionKeyBase,
     DeepRecord,
-    Key,
     KeyValueMapping,
-    OnyxCollectionEntries,
-    OnyxKey,
+    OnyxCollection,
     OnyxEntry,
+    OnyxKey,
 } from './types';
 
 /**
@@ -35,15 +34,15 @@ type BaseConnectOptions<TKey extends OnyxKey> = {
  * 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 `true`, it expects `key` to be a Onyx collection key and `callback` will pass `value` as an `OnyxCollection`.
  *
  * 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: OnyxCollectionEntries<KeyValueMapping[TKey]>, key?: TKey) => void;
+              callback?: (value: OnyxCollection<KeyValueMapping[TKey]>, key?: TKey) => void;
               waitForCollectionCallback: true;
           }
         | {

lib/index.d.ts

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

lib/types.d.ts

@@ -1,10 +1,4 @@
-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;
+import {IsEqual, Merge} from 'type-fest';
 
 /**
  * Represents a deeply nested record. It maps keys to values,
@@ -24,7 +18,7 @@ type DeepRecord<TKey extends string | number | symbol, TValue> = {[key: string]:
  * 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<
+type TypeOptions = Merge<
     {
         keys: string;
         collectionKeys: string;
@@ -42,6 +36,7 @@ type TypeOptions = MergeBy<
  * ```ts
  * // ONYXKEYS.ts
  * import {ValueOf} from 'type-fest';
+ * import { Account, Report } from './types';
  *
  * const ONYXKEYS = {
  *     ACCOUNT: 'account',
@@ -60,7 +55,7 @@ type TypeOptions = MergeBy<
  * type OnyxValues = {
  *     [ONYXKEYS.ACCOUNT]: Account;
  *     [ONYXKEYS.IS_SIDEBAR_LOADED]: boolean;
- *     [report: `${typeof ONYXKEYS.COLLECTION.REPORT}${string}`]: Report;
+ *     [ONYXKEYS.COLLECTION.REPORT]: Report;
  * };
  *
  * export default ONYXKEYS;
@@ -102,9 +97,19 @@ type CollectionKey = `${CollectionKeyBase}${string}`;
 type OnyxKey = Key | CollectionKey;
 
 /**
- * Represents a Record where each key is an Onyx key and each value is its corresponding Onyx value type.
+ * Represents a mapping of Onyx keys to values, where keys are either normal or collection Onyx keys
+ * and values are the corresponding values in Onyx's state.
+ *
+ * For collection keys, `KeyValueMapping` allows any string to be appended
+ * to the key (e.g., 'report_some-id', 'download_some-id').
+ *
+ * The mapping is derived from the `values` property of the `TypeOptions` type.
  */
-type KeyValueMapping = TypeOptions['values'];
+type KeyValueMapping = {
+    [TKey in keyof TypeOptions['values'] as TKey extends CollectionKeyBase
+        ? `${TKey}${string}`
+        : TKey]: TypeOptions['values'][TKey];
+};
 
 /**
  * Represents a selector function type which operates based on the provided `TKey` and `ReturnType`.
@@ -127,13 +132,63 @@ type Selector<TKey extends OnyxKey, TReturnType> = IsEqual<KeyValueMapping[TKey]
 
 /**
  * Represents a single Onyx entry, that can be either `TOnyxValue` or `null` if it doesn't exist.
+ *
+ * It can be used to specify data retrieved from Onyx e.g. `withOnyx` HOC mappings.
+ *
+ * @example
+ * ```ts
+ * import Onyx, {OnyxEntry, withOnyx} from 'react-native-onyx';
+ *
+ * type OnyxProps = {
+ *     userAccount: OnyxEntry<Account>;
+ * };
+ *
+ * type Props = OnyxProps & {
+ *     prop1: string;
+ * };
+ *
+ * function Component({prop1, userAccount}: Props) {
+ *     // ...
+ * }
+ *
+ * export default withOnyx<Props, OnyxProps>({
+ *     userAccount: {
+ *         key: ONYXKEYS.ACCOUNT,
+ *     },
+ * })(Component);
+ * ```
  */
 type OnyxEntry<TOnyxValue> = TOnyxValue | null;
 
 /**
  * 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.
+ *
+ * It can be used to specify collection data retrieved from Onyx e.g. `withOnyx` HOC mappings.
+ *
+ * @example
+ * ```ts
+ * import Onyx, {OnyxCollection, withOnyx} from 'react-native-onyx';
+ *
+ * type OnyxProps = {
+ *     reports: OnyxCollection<Report>;
+ * };
+ *
+ * type Props = OnyxProps & {
+ *     prop1: string;
+ * };
+ *
+ * function Component({prop1, reports}: Props) {
+ *     // ...
+ * }
+ *
+ * export default withOnyx<Props, OnyxProps>({
+ *     reports: {
+ *         key: ONYXKEYS.COLLECTION.REPORT,
+ *     },
+ * })(Component);
+ * ```
  */
-type OnyxCollectionEntries<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | null>>;
+type OnyxCollection<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | null>>;
 
 export {
     CollectionKey,
@@ -142,10 +197,8 @@ export {
     DeepRecord,
     Key,
     KeyValueMapping,
-    MergeBy,
+    OnyxCollection,
+    OnyxEntry,
     OnyxKey,
     Selector,
-    TypeOptions,
-    OnyxEntry,
-    OnyxCollectionEntries,
 };

lib/withOnyx.d.ts

@@ -1,5 +1,5 @@
 import {IsEqual} from 'type-fest';
-import {CollectionKeyBase, KeyValueMapping, OnyxCollectionEntries, OnyxEntry, OnyxKey, Selector} from './types';
+import {CollectionKeyBase, KeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, Selector} from './types';
 
 /**
  * Represents the base mapping options between an Onyx key and the component's prop.
@@ -116,13 +116,7 @@ type CollectionMapping<
     TOnyxKey extends CollectionKeyBase
 > = BaseMapping<TComponentProps, TOnyxProps> &
     (
-        | BaseMappingKey<
-              TComponentProps,
-              TOnyxProps,
-              TOnyxProp,
-              TOnyxKey,
-              OnyxCollectionEntries<KeyValueMapping[TOnyxKey]>
-          >
+        | BaseMappingKey<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey, OnyxCollection<KeyValueMapping[TOnyxKey]>>
         | BaseMappingStringKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>
         | BaseMappingFunctionKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>
     );