react-native-onyx 1.0.59 → 1.0.61

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/lib/withOnyx.js

@@ -41,7 +41,18 @@ export default function (mapOnyxToState) {
                     const key = Str.result(mapping.key, props);
                     const value = Onyx.tryGetCachedValue(key, mapping);
 
-                    if (value !== undefined) {
+                    /**
+                     * If we have a pending merge for a key it could mean that data is being set via Onyx.merge() and someone expects a component to have this data immediately.
+                     *
+                     * @example
+                     *
+                     * Onyx.merge('report_123', value);
+                     * Navigation.navigate(route); // Where "route" expects the "value" to be available immediately once rendered.
+                     *
+                     * In reality, Onyx.merge() will only update the subscriber after all merges have been batched and the previous value is retrieved via a get() (returns a promise).
+                     * So, we won't use the cache optimization here as it will lead us to arbitrarily defer various actions in the application code.
+                     */
+                    if (value !== undefined && !Onyx.hasPendingMergeForKey(key)) {
                         // eslint-disable-next-line no-param-reassign
                         resultObj[propertyName] = value;
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "1.0.59",
+  "version": "1.0.61",
   "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"