react-native-onyx 2.0.36 → 2.0.37

package/dist/Onyx.d.ts

@@ -1,5 +1,5 @@
 import * as Logger from './Logger';
-import type { Collection, CollectionKeyBase, ConnectOptions, InitOptions, KeyValueMapping, Mapping, NullableKeyValueMapping, NullishDeep, OnyxEntry, OnyxKey, OnyxUpdate } from './types';
+import type { Collection, CollectionKeyBase, ConnectOptions, InitOptions, KeyValueMapping, Mapping, NonUndefined, 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;
 /**
@@ -45,7 +45,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: OnyxEntry<KeyValueMapping[TKey]>): Promise<void>;
+declare function set<TKey extends OnyxKey>(key: TKey, value: NonUndefined<OnyxEntry<KeyValueMapping[TKey]>>): Promise<void>;
 /**
  * Sets multiple keys and values
  *
@@ -70,7 +70,7 @@ declare function multiSet(data: Partial<NullableKeyValueMapping>): Promise<void>
  * 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>;
+declare function merge<TKey extends OnyxKey>(key: TKey, changes: NonUndefined<OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>>): Promise<void>;
 /**
  * Merges a collection based on their keys
  *

package/dist/types.d.ts

@@ -2,6 +2,14 @@ import type { Component } from 'react';
 import type { Merge } from 'type-fest';
 import type { BuiltIns } from 'type-fest/source/internal';
 import type OnyxUtils from './OnyxUtils';
+/**
+ * Utility type that excludes `null` from the type `TValue`.
+ */
+type NonNull<TValue> = TValue extends null ? never : TValue;
+/**
+ * Utility type that excludes `undefined` from the type `TValue`.
+ */
+type NonUndefined<TValue> = TValue extends undefined ? never : TValue;
 /**
  * Represents a deeply nested record. It maps keys to values,
  * and those values can either be of type `TValue` or further nested `DeepRecord` instances.
@@ -126,7 +134,7 @@ type NullableKeyValueMapping = {
  */
 type Selector<TKey extends OnyxKey, TOnyxProps, TReturnType> = (value: OnyxEntry<KeyValueMapping[TKey]>, state: WithOnyxInstanceState<TOnyxProps>) => TReturnType;
 /**
- * Represents a single Onyx entry, that can be either `TOnyxValue` or `null` if it doesn't exist.
+ * Represents a single Onyx entry, that can be either `TOnyxValue` or `null` / `undefined` if it doesn't exist.
  *
  * It can be used to specify data retrieved from Onyx e.g. `withOnyx` HOC mappings.
  *
@@ -153,9 +161,9 @@ type Selector<TKey extends OnyxKey, TOnyxProps, TReturnType> = (value: OnyxEntry
  * })(Component);
  * ```
  */
-type OnyxEntry<TOnyxValue> = TOnyxValue | null;
+type OnyxEntry<TOnyxValue> = TOnyxValue | null | undefined;
 /**
- * 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.
+ * Represents an Onyx collection of entries, that can be either a record of `TOnyxValue`s or `null` / `undefined` if it is empty or doesn't exist.
  *
  * It can be used to specify collection data retrieved from Onyx e.g. `withOnyx` HOC mappings.
  *
@@ -182,7 +190,7 @@ type OnyxEntry<TOnyxValue> = TOnyxValue | null;
  * })(Component);
  * ```
  */
-type OnyxCollection<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | null>>;
+type OnyxCollection<TOnyxValue> = OnyxEntry<Record<string, TOnyxValue | null | undefined>>;
 /** Utility type to extract `TOnyxValue` from `OnyxCollection<TOnyxValue>` */
 type ExtractOnyxCollectionValue<TOnyxCollection> = TOnyxCollection extends NonNullable<OnyxCollection<infer U>> ? U : never;
 type NonTransformableTypes = BuiltIns | ((...args: any[]) => unknown) | Map<unknown, unknown> | Set<unknown> | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | unknown[] | readonly unknown[];
@@ -247,8 +255,8 @@ type WithOnyxConnectOptions<TKey extends OnyxKey> = {
     selector?: Selector<TKey, unknown, unknown>;
     canEvict?: boolean;
 };
-type DefaultConnectCallback<TKey extends OnyxKey> = (value: OnyxEntry<KeyValueMapping[TKey]>, key: TKey) => void;
-type CollectionConnectCallback<TKey extends OnyxKey> = (value: OnyxCollection<KeyValueMapping[TKey]>) => void;
+type DefaultConnectCallback<TKey extends OnyxKey> = (value: NonUndefined<OnyxEntry<KeyValueMapping[TKey]>>, key: TKey) => void;
+type CollectionConnectCallback<TKey extends OnyxKey> = (value: NonUndefined<OnyxCollection<KeyValueMapping[TKey]>>) => void;
 /** Represents the callback function used in `Onyx.connect()` method with a regular key. */
 type DefaultConnectOptions<TKey extends OnyxKey> = {
     key: TKey;
@@ -286,11 +294,11 @@ type OnyxUpdate = {
     [TKey in OnyxKey]: {
         onyxMethod: typeof OnyxUtils.METHOD.SET;
         key: TKey;
-        value: OnyxEntry<KeyValueMapping[TKey]>;
+        value: NonUndefined<OnyxEntry<KeyValueMapping[TKey]>>;
     } | {
         onyxMethod: typeof OnyxUtils.METHOD.MERGE;
         key: TKey;
-        value: OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>;
+        value: NonUndefined<OnyxEntry<NullishDeep<KeyValueMapping[TKey]>>>;
     } | {
         onyxMethod: typeof OnyxUtils.METHOD.MULTI_SET;
         key: TKey;
@@ -334,4 +342,4 @@ type InitOptions = {
     /** Enables debugging setState() calls to connected components */
     debugSetState?: boolean;
 };
-export type { CollectionKey, CollectionKeyBase, CustomTypeOptions, DeepRecord, Key, KeyValueMapping, NullableKeyValueMapping, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, Selector, NullishDeep, WithOnyxInstanceState, ExtractOnyxCollectionValue, Collection, WithOnyxInstance, BaseConnectOptions, WithOnyxConnectOptions, DefaultConnectCallback, CollectionConnectCallback, DefaultConnectOptions, CollectionConnectOptions, ConnectOptions, Mapping, OnyxUpdate, InitOptions, };
+export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, DefaultConnectOptions, ExtractOnyxCollectionValue, InitOptions, Key, KeyValueMapping, Mapping, NonNull, NonUndefined, NullableKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxUpdate, OnyxValue, Selector, WithOnyxConnectOptions, WithOnyxInstance, WithOnyxInstanceState, };

package/dist/useOnyx.d.ts

@@ -1,6 +1,11 @@
 import type { IsEqual } from 'type-fest';
-import type { CollectionKeyBase, OnyxCollection, OnyxKey, OnyxValue, Selector } from './types';
-type UseOnyxOptions<TKey extends OnyxKey, TReturnValue> = {
+import type { CollectionKeyBase, KeyValueMapping, NonNull, OnyxCollection, OnyxEntry, OnyxKey, Selector } from './types';
+/**
+ * Represents a Onyx value that can be either a single entry or a collection of entries, depending on the `TKey` provided.
+ * It's a variation of `OnyxValue` type that is read-only and excludes the `null` type.
+ */
+type UseOnyxValue<TKey extends OnyxKey> = string extends TKey ? unknown : TKey extends CollectionKeyBase ? Readonly<NonNull<OnyxCollection<KeyValueMapping[TKey]>>> : Readonly<NonNull<OnyxEntry<KeyValueMapping[TKey]>>>;
+type BaseUseOnyxOptions = {
     /**
      * Determines if this key in this subscription is safe to be evicted.
      */
@@ -13,10 +18,14 @@ type UseOnyxOptions<TKey extends OnyxKey, TReturnValue> = {
      * If set to true, data will be retrieved from cache during the first render even if there is a pending merge for the key.
      */
     allowStaleData?: boolean;
+};
+type UseOnyxInitialValueOption<TInitialValue> = {
     /**
      * This value will be returned by the hook on the first render while the data is being read from Onyx.
      */
-    initialValue?: TReturnValue;
+    initialValue?: TInitialValue;
+};
+type UseOnyxSelectorOption<TKey extends OnyxKey, TReturnValue> = {
     /**
      * This will be used to subscribe to a subset of an Onyx key's data.
      * Using this setting on `useOnyx` can have very positive performance benefits because the component will only re-render
@@ -26,11 +35,12 @@ type UseOnyxOptions<TKey extends OnyxKey, TReturnValue> = {
     selector?: Selector<TKey, unknown, TReturnValue>;
 };
 type FetchStatus = 'loading' | 'loaded';
-type CachedValue<TKey extends OnyxKey, TValue> = IsEqual<TValue, OnyxValue<TKey>> extends true ? TValue : TKey extends CollectionKeyBase ? NonNullable<OnyxCollection<TValue>> : TValue;
+type CachedValue<TKey extends OnyxKey, TValue> = IsEqual<TValue, UseOnyxValue<TKey>> extends true ? TValue : TKey extends CollectionKeyBase ? Readonly<NonNullable<OnyxCollection<TValue>>> : Readonly<TValue>;
 type ResultMetadata = {
     status: FetchStatus;
 };
 type UseOnyxResult<TKey extends OnyxKey, TValue> = [CachedValue<TKey, TValue>, ResultMetadata];
-declare function useOnyx<TKey extends OnyxKey, TReturnValue = OnyxValue<TKey>>(key: TKey, options?: UseOnyxOptions<TKey, TReturnValue>): UseOnyxResult<TKey, TReturnValue>;
+declare function useOnyx<TKey extends OnyxKey, TReturnValue = UseOnyxValue<TKey>>(key: TKey, options?: BaseUseOnyxOptions & UseOnyxInitialValueOption<TReturnValue> & Required<UseOnyxSelectorOption<TKey, TReturnValue>>): UseOnyxResult<TKey, TReturnValue>;
+declare function useOnyx<TKey extends OnyxKey, TReturnValue = UseOnyxValue<TKey>>(key: TKey, options?: BaseUseOnyxOptions & UseOnyxInitialValueOption<NoInfer<TReturnValue>>): UseOnyxResult<TKey, TReturnValue>;
 export default useOnyx;
 export type { UseOnyxResult, ResultMetadata, FetchStatus };

package/dist/useOnyx.js

@@ -21,10 +21,10 @@ function useOnyx(key, options) {
     // We initialize it to `undefined` to simulate that we don't have any value from cache yet.
     const cachedValueRef = (0, react_1.useRef)(undefined);
     // Stores the previously result returned by the hook, containing the data from cache and the fetch status.
-    // We initialize it to `null` and `loading` fetch status to simulate the initial result when the hook is loading from the cache.
+    // We initialize it to `undefined` and `loading` fetch status to simulate the initial result when the hook is loading from the cache.
     // However, if `initWithStoredValues` is `true` we set the fetch status to `loaded` since we want to signal that data is ready.
     const resultRef = (0, react_1.useRef)([
-        null,
+        undefined,
         {
             status: (options === null || options === void 0 ? void 0 : options.initWithStoredValues) === false ? 'loaded' : 'loading',
         },
@@ -76,8 +76,8 @@ function useOnyx(key, options) {
         // and the result to be returned by the hook.
         if (!(0, fast_equals_1.deepEqual)(cachedValueRef.current, newValue)) {
             cachedValueRef.current = newValue;
-            // If the new value is `undefined` we default it to `null` to ensure the consumer get a consistent result from the hook.
-            resultRef.current = [((_a = cachedValueRef.current) !== null && _a !== void 0 ? _a : null), { status: newFetchStatus !== null && newFetchStatus !== void 0 ? newFetchStatus : 'loaded' }];
+            // If the new value is `null` we default it to `undefined` to ensure the consumer get a consistent result from the hook.
+            resultRef.current = [((_a = cachedValueRef.current) !== null && _a !== void 0 ? _a : undefined), { status: newFetchStatus !== null && newFetchStatus !== void 0 ? newFetchStatus : 'loaded' }];
         }
         return resultRef.current;
     }, [key, selectorRef, options === null || options === void 0 ? void 0 : options.allowStaleData, options === null || options === void 0 ? void 0 : options.initialValue]);

package/dist/withOnyx.d.ts

@@ -125,6 +125,8 @@ type OnyxPropCollectionMapping<TComponentProps, TOnyxProps, TOnyxProp extends ke
 }[CollectionKeyBase];
 
 /**
+ * @deprecated Use `useOnyx` instead of `withOnyx` whenever possible.
+ *
  * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "2.0.36",
+  "version": "2.0.37",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",
@@ -85,7 +85,7 @@
     "reassure": "^0.11.0",
     "ts-node": "^10.9.2",
     "type-fest": "^3.12.0",
-    "typescript": "^5.3.3"
+    "typescript": "^5.4.5"
   },
   "peerDependencies": {
     "idb-keyval": "^6.2.1",