react-native-onyx 1.0.59 → 1.0.60

package/lib/Logger.d.ts

@@ -0,0 +1,13 @@
+declare type LogData = {
+    message: string;
+    level: 'alert' | 'info';
+};
+
+/**
+ * Register the logging callback
+ *
+ * @param callback
+ */
+declare function registerLogger(callback: (data: LogData) => void): void;
+
+export {registerLogger};

package/lib/Onyx.d.ts

@@ -0,0 +1,326 @@
+import {Component} from 'react';
+import {PartialDeep} from 'type-fest';
+import * as Logger from './Logger';
+import {
+    CollectionKey,
+    CollectionKeyBase,
+    DeepRecord,
+    KeyValueMapping,
+    OnyxCollection,
+    OnyxEntry,
+    OnyxKey,
+} 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;
+};
+
+/**
+ * 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 CollectionKey ? TKey : never;
+              callback?: (value: OnyxCollection<KeyValueMapping[TKey]>, key?: 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: PartialDeep<KeyValueMapping[TKey]>;
+                };
+      }[OnyxKey]
+    | {
+          [TKey in CollectionKeyBase]: {
+              onyxMethod: typeof METHOD.MERGE_COLLECTION;
+              key: TKey;
+              value: Record<`${TKey}${string}`, PartialDeep<KeyValueMapping[TKey]>>;
+          };
+      }[CollectionKeyBase];
+
+/**
+ * Represents the options used in `Onyx.init()` method.
+ */
+type InitOptions = {
+    keys?: DeepRecord<string, OnyxKey>;
+    initialKeyStates?: Partial<NullableKeyValueMapping>;
+    safeEvictionKeys?: OnyxKey[];
+    maxCachedKeysCount?: number;
+    captureMetrics?: boolean;
+    shouldSyncMultipleInstances?: boolean;
+    debugSetState?: boolean;
+};
+
+declare const METHOD: {
+    readonly SET: 'set';
+    readonly MERGE: 'merge';
+    readonly MERGE_COLLECTION: 'mergecollection';
+    readonly CLEAR: 'clear';
+};
+
+/**
+ * Returns current key names stored in persisted storage
+ */
+declare function getAllKeys(): Promise<Array<OnyxKey>>;
+
+/**
+ * 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;
+
+/**
+ * Subscribes a react component's state directly to a store key
+ *
+ * @example
+ * const connectionID = Onyx.connect({
+ *     key: ONYXKEYS.SESSION,
+ *     callback: onSessionChange,
+ * });
+ *
+ * @param mapping the mapping information to connect Onyx to the components state
+ * @param mapping.key ONYXKEY to subscribe to
+ * @param [mapping.statePropertyName] the name of the property in the state to connect the data to
+ * @param [mapping.withOnyxInstance] whose setState() method will be called with any changed data
+ *      This is used by React components to connect to Onyx
+ * @param [mapping.callback] a method that will be called with changed data
+ *      This is used by any non-React code to connect to Onyx
+ * @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
+ * @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
+ * Onyx.disconnect(connectionID);
+ *
+ * @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>;
+
+/**
+ * Sets multiple keys and values
+ *
+ * @example Onyx.multiSet({'key1': 'a', 'key2': 'b'});
+ *
+ * @param data object keyed by ONYXKEYS and the values to set
+ */
+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
+ *
+ * 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
+ * `Onyx.merge()` and `Onyx.set()`.
+ *
+ * @example
+ * Onyx.merge(ONYXKEYS.EMPLOYEE_LIST, ['Joe']); // -> ['Joe']
+ * 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'}
+ *
+ * @param key ONYXKEYS key
+ * @param value Object or Array value to merge
+ */
+declare function merge<TKey extends OnyxKey>(key: TKey, value: PartialDeep<KeyValueMapping[TKey]>): Promise<void>;
+
+/**
+ * Clear out all the data in the store
+ *
+ * Note that calling Onyx.clear() and then Onyx.set() on a key with a default
+ * key state may store an unexpected value in Storage.
+ *
+ * E.g.
+ * Onyx.clear();
+ * Onyx.set(ONYXKEYS.DEFAULT_KEY, 'default');
+ * Storage.getItem(ONYXKEYS.DEFAULT_KEY)
+ *     .then((storedValue) => console.log(storedValue));
+ * null is logged instead of the expected 'default'
+ *
+ * Onyx.set() might call Storage.setItem() before Onyx.clear() calls
+ * Storage.setItem(). Use Onyx.merge() instead if possible. Onyx.merge() calls
+ * Onyx.get(key) before calling Storage.setItem() via Onyx.set().
+ * Storage.setItem() from Onyx.clear() will have already finished and the merged
+ * value will be saved to storage after the default value.
+ *
+ * @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, PartialDeep<KeyValueMapping[TKey]>>,
+): Promise<void>;
+
+/**
+ * Insert API responses and lifecycle data into Onyx
+ *
+ * @param data An array of update objects
+ * @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.captureMetrics] Enables Onyx benchmarking and exposes the get/print/reset functions
+ * @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;
+
+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;
+};
+
+export default Onyx;
+export {OnyxUpdate};

package/lib/index.d.ts

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

package/lib/types.d.ts

@@ -0,0 +1,196 @@
+import {IsEqual, Merge} from 'type-fest';
+
+/**
+ * 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 = Merge<
+    {
+        keys: string;
+        collectionKeys: string;
+        values: Record<string, unknown>;
+    },
+    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';
+ * import { Account, Report } from './types';
+ *
+ * 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;
+ *     [ONYXKEYS.COLLECTION.REPORT]: 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 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 = {
+    [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`.
+ *
+ * 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.
+ */
+type Selector<TKey extends OnyxKey, TReturnType> = (value: OnyxEntry<KeyValueMapping[TKey]>) => TReturnType;
+
+/**
+ * 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 OnyxCollection<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | null>>;
+
+export {
+    CollectionKey,
+    CollectionKeyBase,
+    CustomTypeOptions,
+    DeepRecord,
+    Key,
+    KeyValueMapping,
+    OnyxCollection,
+    OnyxEntry,
+    OnyxKey,
+    Selector,
+};

package/lib/withOnyx.d.ts

@@ -0,0 +1,153 @@
+import {IsEqual} from 'type-fest';
+import {CollectionKeyBase, KeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, Selector} from './types';
+
+/**
+ * Represents the base mapping options between an Onyx key and the component's prop.
+ */
+type BaseMapping<TComponentProps, TOnyxProps> = {
+    canEvict?: boolean | ((props: Omit<TComponentProps, keyof TOnyxProps>) => boolean);
+    initWithStoredValues?: boolean;
+};
+
+/**
+ * Represents the string / function `key` mapping option between an Onyx key and the component's prop.
+ *
+ * If `key` is `string`, the type of the Onyx value that is associated with `key` must match with the type of the component's prop,
+ * otherwise an error will be thrown.
+ *
+ * If `key` is `function`, the return type of `key` function must be a valid Onyx key and the type of the Onyx value associated
+ * with `key` must match with the type of the component's prop, otherwise an error will be thrown.
+ *
+ * @example
+ * ```ts
+ * // Onyx prop with `string` key
+ * onyxProp: {
+ *     key: ONYXKEYS.ACCOUNT,
+ * },
+ *
+ * // Onyx prop with `function` key
+ * onyxProp: {
+ *     key: ({reportId}) => ONYXKEYS.ACCOUNT,
+ * },
+ * ```
+ */
+type BaseMappingKey<
+    TComponentProps,
+    TOnyxProps,
+    TOnyxProp extends keyof TOnyxProps,
+    TOnyxKey extends OnyxKey,
+    TOnyxValue
+> = IsEqual<TOnyxValue, TOnyxProps[TOnyxProp]> extends true
+    ? {
+          key: TOnyxKey | ((props: Omit<TComponentProps, keyof TOnyxProps>) => TOnyxKey);
+      }
+    : never;
+
+/**
+ * Represents the string `key` and `selector` mapping options between an Onyx key and the component's prop.
+ *
+ * The function signature and return type of `selector` must match with the type of the component's prop,
+ * otherwise an error will be thrown.
+ *
+ * @example
+ * ```ts
+ * // Onyx prop with `string` key and selector
+ * onyxProp: {
+ *     key: ONYXKEYS.ACCOUNT,
+ *     selector: (value: Account | null): string => value?.id ?? '',
+ * },
+ * ```
+ */
+type BaseMappingStringKeyAndSelector<
+    TComponentProps,
+    TOnyxProps,
+    TOnyxProp extends keyof TOnyxProps,
+    TOnyxKey extends OnyxKey
+> = {
+    key: TOnyxKey;
+    selector: Selector<TOnyxKey, TOnyxProps[TOnyxProp]>;
+};
+
+/**
+ * Represents the function `key` and `selector` mapping options between an Onyx key and the component's prop.
+ *
+ * The function signature and return type of `selector` must match with the type of the component's prop,
+ * otherwise an error will be thrown.
+ *
+ * @example
+ * ```ts
+ * // Onyx prop with `function` key and selector
+ * onyxProp: {
+ *     key: ({reportId}) => ONYXKEYS.ACCOUNT,
+ *     selector: (value: Account | null) => value?.id ?? '',
+ * },
+ * ```
+ */
+type BaseMappingFunctionKeyAndSelector<
+    TComponentProps,
+    TOnyxProps,
+    TOnyxProp extends keyof TOnyxProps,
+    TOnyxKey extends OnyxKey
+> = {
+    key: (props: Omit<TComponentProps, keyof TOnyxProps>) => TOnyxKey;
+    selector: Selector<TOnyxKey, TOnyxProps[TOnyxProp]>;
+};
+
+/**
+ * Represents the mapping options between an Onyx key and the component's prop with all its possibilities.
+ */
+type Mapping<TComponentProps, TOnyxProps, TOnyxProp extends keyof TOnyxProps, TOnyxKey extends OnyxKey> = BaseMapping<
+    TComponentProps,
+    TOnyxProps
+> &
+    (
+        | BaseMappingKey<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey, OnyxEntry<KeyValueMapping[TOnyxKey]>>
+        | BaseMappingStringKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>
+        | BaseMappingFunctionKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>
+    );
+
+/**
+ * Represents the mapping options between an Onyx collection key without suffix and the component's prop with all its possibilities.
+ */
+type CollectionMapping<
+    TComponentProps,
+    TOnyxProps,
+    TOnyxProp extends keyof TOnyxProps,
+    TOnyxKey extends CollectionKeyBase
+> = BaseMapping<TComponentProps, TOnyxProps> &
+    (
+        | BaseMappingKey<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey, OnyxCollection<KeyValueMapping[TOnyxKey]>>
+        | BaseMappingStringKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>
+        | BaseMappingFunctionKeyAndSelector<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>
+    );
+
+/**
+ * Represents an union type of all the possible Onyx key mappings.
+ * Each `OnyxPropMapping` will be associated with its respective Onyx key, ensuring different type-safety for each object.
+ */
+type OnyxPropMapping<TComponentProps, TOnyxProps, TOnyxProp extends keyof TOnyxProps> = {
+    [TOnyxKey in OnyxKey]: Mapping<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>;
+}[OnyxKey];
+
+/**
+ * Represents an union type of all the possible Onyx collection keys without suffix mappings.
+ * Each `OnyxPropCollectionMapping` will be associated with its respective Onyx key, ensuring different type-safety for each object.
+ */
+type OnyxPropCollectionMapping<TComponentProps, TOnyxProps, TOnyxProp extends keyof TOnyxProps> = {
+    [TOnyxKey in CollectionKeyBase]: CollectionMapping<TComponentProps, TOnyxProps, TOnyxProp, TOnyxKey>;
+}[CollectionKeyBase];
+
+/**
+ * This is a higher order component that provides the ability to map a state property directly to
+ * something in Onyx (a key/value store). That way, as soon as data in Onyx changes, the state will be set and the view
+ * will automatically change to reflect the new data.
+ */
+declare function withOnyx<TComponentProps, TOnyxProps>(
+    mapping: {
+        [TOnyxProp in keyof TOnyxProps]:
+            | OnyxPropMapping<TComponentProps, TOnyxProps, TOnyxProp>
+            | OnyxPropCollectionMapping<TComponentProps, TOnyxProps, TOnyxProp>;
+    },
+): (component: React.ComponentType<TComponentProps>) => React.ComponentType<Omit<TComponentProps, keyof TOnyxProps>>;
+
+export default withOnyx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "1.0.59",
+  "version": "1.0.60",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",
@@ -31,6 +31,7 @@
   "react-native": "native.js",
   "main": "native.js",
   "browser": "web.js",
+  "types": "lib/index.d.ts",
   "scripts": {
     "lint": "eslint .",
     "lint-tests": "eslint tests/**",
@@ -50,6 +51,7 @@
     "@react-native-community/eslint-config": "^2.0.0",
     "@testing-library/jest-native": "^3.4.2",
     "@testing-library/react-native": "^7.0.2",
+    "@types/react": "^18.2.14",
     "babel-eslint": "^10.1.0",
     "babel-jest": "^26.2.2",
     "babel-loader": "^8.2.5",
@@ -68,6 +70,7 @@
     "react-native-performance": "^2.0.0",
     "react-native-quick-sqlite": "^8.0.0-beta.2",
     "react-test-renderer": "18.1.0",
+    "type-fest": "^3.12.0",
     "webpack": "^5.72.1",
     "webpack-cli": "^4.9.2",
     "webpack-merge": "^5.8.0"