react-native-onyx 2.0.117 → 2.0.118

package/dist/types.d.ts

@@ -3,6 +3,7 @@ import type { BuiltIns } from 'type-fest/source/internal';
 import type OnyxUtils from './OnyxUtils';
 import type { WithOnyxInstance, WithOnyxState } from './withOnyx/types';
 import type { OnyxMethod } from './OnyxUtils';
+import type { FastMergeReplaceNullPatch } from './utils';
 /**
  * Utility type that excludes `null` from the type `TValue`.
  */
@@ -412,11 +413,19 @@ type InitOptions = {
     fullyMergedSnapshotKeys?: string[];
 };
 type GenericFunction = (...args: any[]) => any;
+/**
+ * Represents a record where the key is a collection member key and the value is a list of
+ * tuples that we'll use to replace the nested objects of that collection member record with something else.
+ */
+type MultiMergeReplaceNullPatches = {
+    [TKey in OnyxKey]: FastMergeReplaceNullPatch[];
+};
 /**
  * Represents a combination of Merge and Set operations that should be executed in Onyx
  */
 type MixedOperationsQueue = {
     merge: OnyxInputKeyValueMapping;
+    mergeReplaceNullPatches: MultiMergeReplaceNullPatches;
     set: OnyxInputKeyValueMapping;
 };
-export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, DefaultConnectOptions, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, Mapping, NonNull, NonUndefined, OnyxInputKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxMethod, OnyxMethodMap, OnyxUpdate, OnyxValue, Selector, WithOnyxConnectOptions, MixedOperationsQueue, };
+export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, DefaultConnectOptions, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, Mapping, NonNull, NonUndefined, OnyxInputKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxMethod, OnyxMethodMap, OnyxUpdate, OnyxValue, Selector, WithOnyxConnectOptions, MultiMergeReplaceNullPatches, MixedOperationsQueue, };

package/dist/utils.d.ts

@@ -1,16 +1,42 @@
 import type { ConnectOptions, OnyxInput, OnyxKey } from './types';
 type EmptyObject = Record<string, never>;
 type EmptyValue = EmptyObject | null | undefined;
-/** Checks whether the given object is an object and not null/undefined. */
-declare function isEmptyObject<T>(obj: T | EmptyValue): obj is EmptyValue;
+/**
+ * A tuple where the first value is the path to the nested object that contains the
+ * internal `ONYX_INTERNALS__REPLACE_OBJECT_MARK` flag, and the second value is the data we want to replace
+ * in that path.
+ *
+ * This tuple will be used in SQLiteProvider to replace the nested object using `JSON_REPLACE`.
+ * */
+type FastMergeReplaceNullPatch = [string[], unknown];
+type FastMergeOptions = {
+    /** If true, null object values will be removed. */
+    shouldRemoveNestedNulls?: boolean;
+    /**
+     * If set to "mark", we will mark objects that are set to null instead of simply removing them,
+     * so that we can batch changes together, without losing information about the object removal.
+     * If set to "replace", we will completely replace the marked objects with the new value instead of merging them.
+     */
+    objectRemovalMode?: 'mark' | 'replace' | 'none';
+};
+type FastMergeMetadata = {
+    /** The list of tuples that will be used in SQLiteProvider to replace the nested objects using `JSON_REPLACE`. */
+    replaceNullPatches: FastMergeReplaceNullPatch[];
+};
+type FastMergeResult<TValue> = {
+    /** The result of the merge. */
+    result: TValue;
+    /** The list of tuples that will be used in SQLiteProvider to replace the nested objects using `JSON_REPLACE`. */
+    replaceNullPatches: FastMergeReplaceNullPatch[];
+};
 /**
  * Merges two objects and removes null values if "shouldRemoveNestedNulls" is set to true
  *
  * We generally want to remove null values from objects written to disk and cache, because it decreases the amount of data stored in memory and on disk.
- * On native, when merging an existing value with new changes, SQLite will use JSON_PATCH, which removes top-level nullish values.
- * To be consistent with the behaviour for merge, we'll also want to remove null values for "set" operations.
  */
-declare function fastMerge<TValue>(target: TValue, source: TValue, shouldRemoveNestedNulls?: boolean): TValue;
+declare function fastMerge<TValue>(target: TValue, source: TValue, options?: FastMergeOptions, metadata?: FastMergeMetadata, basePath?: string[]): FastMergeResult<TValue>;
+/** Checks whether the given object is an object and not null/undefined. */
+declare function isEmptyObject<T>(obj: T | EmptyValue): obj is EmptyValue;
 /** Deep removes the nested null values from the given value. */
 declare function removeNestedNullValues<TValue extends OnyxInput<OnyxKey> | null>(value: TValue): TValue;
 /** Formats the action name by uppercasing and adding the key if provided. */
@@ -42,13 +68,15 @@ declare function omit<TValue>(obj: Record<string, TValue>, condition: string | s
  */
 declare function hasWithOnyxInstance<TKey extends OnyxKey>(mapping: ConnectOptions<TKey>): unknown;
 declare const _default: {
-    isEmptyObject: typeof isEmptyObject;
     fastMerge: typeof fastMerge;
+    isEmptyObject: typeof isEmptyObject;
     formatActionName: typeof formatActionName;
     removeNestedNullValues: typeof removeNestedNullValues;
     checkCompatibilityWithExistingValue: typeof checkCompatibilityWithExistingValue;
     pick: typeof pick;
     omit: typeof omit;
     hasWithOnyxInstance: typeof hasWithOnyxInstance;
+    ONYX_INTERNALS__REPLACE_OBJECT_MARK: string;
 };
 export default _default;
+export type { FastMergeResult, FastMergeReplaceNullPatch, FastMergeOptions };

package/dist/utils.js

@@ -1,25 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-/** Checks whether the given object is an object and not null/undefined. */
-function isEmptyObject(obj) {
-    return typeof obj === 'object' && Object.keys(obj || {}).length === 0;
-}
-// Mostly copied from https://medium.com/@lubaka.a/how-to-remove-lodash-performance-improvement-b306669ad0e1
+const ONYX_INTERNALS__REPLACE_OBJECT_MARK = 'ONYX_INTERNALS__REPLACE_OBJECT_MARK';
 /**
- * Checks whether the given value can be merged. It has to be an object, but not an array, RegExp or Date.
+ * Merges two objects and removes null values if "shouldRemoveNestedNulls" is set to true
+ *
+ * We generally want to remove null values from objects written to disk and cache, because it decreases the amount of data stored in memory and on disk.
  */
-function isMergeableObject(value) {
-    const isNonNullObject = value != null ? typeof value === 'object' : false;
-    return isNonNullObject && !(value instanceof RegExp) && !(value instanceof Date) && !Array.isArray(value);
+function fastMerge(target, source, options, metadata, basePath = []) {
+    var _a, _b;
+    if (!metadata) {
+        // eslint-disable-next-line no-param-reassign
+        metadata = {
+            replaceNullPatches: [],
+        };
+    }
+    // We have to ignore arrays and nullish values here,
+    // otherwise "mergeObject" will throw an error,
+    // because it expects an object as "source"
+    if (Array.isArray(source) || source === null || source === undefined) {
+        return { result: source, replaceNullPatches: metadata.replaceNullPatches };
+    }
+    const optionsWithDefaults = {
+        shouldRemoveNestedNulls: (_a = options === null || options === void 0 ? void 0 : options.shouldRemoveNestedNulls) !== null && _a !== void 0 ? _a : false,
+        objectRemovalMode: (_b = options === null || options === void 0 ? void 0 : options.objectRemovalMode) !== null && _b !== void 0 ? _b : 'none',
+    };
+    const mergedValue = mergeObject(target, source, optionsWithDefaults, metadata, basePath);
+    return { result: mergedValue, replaceNullPatches: metadata.replaceNullPatches };
 }
 /**
  * Merges the source object into the target object.
  * @param target - The target object.
  * @param source - The source object.
- * @param shouldRemoveNestedNulls - If true, null object values will be removed.
+ * @param options - The options for the merge.
+ * @param metadata - The metadata for the merge.
+ * @param basePath - The base path for the merge.
  * @returns - The merged object.
  */
-function mergeObject(target, source, shouldRemoveNestedNulls = true) {
+function mergeObject(target, source, options, metadata, basePath) {
     const destination = {};
     const targetObject = isMergeableObject(target) ? target : undefined;
     // First we want to copy over all keys from the target into the destination object,
@@ -27,66 +44,67 @@ function mergeObject(target, source, shouldRemoveNestedNulls = true) {
     // If "shouldRemoveNestedNulls" is true, we want to remove null values from the merged object
     // and therefore we need to omit keys where either the source or target value is null.
     if (targetObject) {
-        // eslint-disable-next-line no-restricted-syntax, guard-for-in
-        for (const key in targetObject) {
-            const sourceValue = source === null || source === void 0 ? void 0 : source[key];
-            const targetValue = targetObject === null || targetObject === void 0 ? void 0 : targetObject[key];
-            // If "shouldRemoveNestedNulls" is true, we want to remove null values from the merged object.
-            // Therefore, if either target or source value is null, we want to prevent the key from being set.
-            // targetValue should techincally never be "undefined", because it will always be a value from cache or storage
-            // and we never set "undefined" there. Still, if there targetValue is undefined we don't want to set
-            // the key explicitly to prevent loose undefined values in objects in cache and storage.
-            const isSourceOrTargetNull = targetValue === undefined || targetValue === null || sourceValue === null;
-            const shouldOmitTargetKey = shouldRemoveNestedNulls && isSourceOrTargetNull;
-            if (!shouldOmitTargetKey) {
-                destination[key] = targetValue;
+        Object.keys(targetObject).forEach((key) => {
+            const targetProperty = targetObject === null || targetObject === void 0 ? void 0 : targetObject[key];
+            const sourceProperty = source === null || source === void 0 ? void 0 : source[key];
+            // If "shouldRemoveNestedNulls" is true, we want to remove (nested) null values from the merged object.
+            // If either the source or target value is null, we want to omit the key from the merged object.
+            const shouldOmitNullishProperty = options.shouldRemoveNestedNulls && (targetProperty === null || sourceProperty === null);
+            if (targetProperty === undefined || shouldOmitNullishProperty) {
+                return;
             }
-        }
+            destination[key] = targetProperty;
+        });
     }
     // After copying over all keys from the target object, we want to merge the source object into the destination object.
-    // eslint-disable-next-line no-restricted-syntax, guard-for-in
-    for (const key in source) {
-        const sourceValue = source === null || source === void 0 ? void 0 : source[key];
-        const targetValue = targetObject === null || targetObject === void 0 ? void 0 : targetObject[key];
-        // If undefined is passed as the source value for a key, we want to generally ignore it.
-        // If "shouldRemoveNestedNulls" is set to true and the source value is null,
-        // we don't want to set/merge the source value into the merged object.
-        const shouldIgnoreNullSourceValue = shouldRemoveNestedNulls && sourceValue === null;
-        const shouldOmitSourceKey = sourceValue === undefined || shouldIgnoreNullSourceValue;
-        if (!shouldOmitSourceKey) {
-            // If the source value is a mergable object, we want to merge it into the target value.
-            // If "shouldRemoveNestedNulls" is true, "fastMerge" will recursively
-            // remove nested null values from the merged object.
-            // If source value is any other value we need to set the source value it directly.
-            if (isMergeableObject(sourceValue)) {
-                // If the target value is null or undefined, we need to fallback to an empty object,
-                // so that we can still use "fastMerge" to merge the source value,
-                // to ensure that nested null values are removed from the merged object.
-                const targetValueWithFallback = (targetValue !== null && targetValue !== void 0 ? targetValue : {});
-                destination[key] = fastMerge(targetValueWithFallback, sourceValue, shouldRemoveNestedNulls);
-            }
-            else {
-                destination[key] = sourceValue;
-            }
+    Object.keys(source).forEach((key) => {
+        let targetProperty = targetObject === null || targetObject === void 0 ? void 0 : targetObject[key];
+        const sourceProperty = source === null || source === void 0 ? void 0 : source[key];
+        // If "shouldRemoveNestedNulls" is true, we want to remove (nested) null values from the merged object.
+        // If the source value is null, we want to omit the key from the merged object.
+        const shouldOmitNullishProperty = options.shouldRemoveNestedNulls && sourceProperty === null;
+        if (sourceProperty === undefined || shouldOmitNullishProperty) {
+            return;
         }
-    }
+        // If the source value is not a mergable object, we need to set the key directly.
+        if (!isMergeableObject(sourceProperty)) {
+            destination[key] = sourceProperty;
+            return;
+        }
+        // If "shouldMarkRemovedObjects" is enabled and the previous merge change (targetProperty) is null,
+        // it means we want to fully replace this object when merging the batched changes with the Onyx value.
+        // To achieve this, we first mark these nested objects with an internal flag.
+        // When calling fastMerge again with "mark" removal mode, the marked objects will be removed.
+        if (options.objectRemovalMode === 'mark' && targetProperty === null) {
+            targetProperty = { [ONYX_INTERNALS__REPLACE_OBJECT_MARK]: true };
+            metadata.replaceNullPatches.push([[...basePath, key], Object.assign({}, sourceProperty)]);
+        }
+        // Later, when merging the batched changes with the Onyx value, if a nested object of the batched changes
+        // has the internal flag set, we replace the entire destination object with the source one and remove
+        // the flag.
+        if (options.objectRemovalMode === 'replace' && sourceProperty[ONYX_INTERNALS__REPLACE_OBJECT_MARK]) {
+            // We do a spread here in order to have a new object reference and allow us to delete the internal flag
+            // of the merged object only.
+            const sourcePropertyWithoutMark = Object.assign({}, sourceProperty);
+            delete sourcePropertyWithoutMark.ONYX_INTERNALS__REPLACE_OBJECT_MARK;
+            destination[key] = sourcePropertyWithoutMark;
+            return;
+        }
+        destination[key] = fastMerge(targetProperty, sourceProperty, options, metadata, [...basePath, key]).result;
+    });
     return destination;
 }
+/** Checks whether the given object is an object and not null/undefined. */
+function isEmptyObject(obj) {
+    return typeof obj === 'object' && Object.keys(obj || {}).length === 0;
+}
 /**
- * Merges two objects and removes null values if "shouldRemoveNestedNulls" is set to true
- *
- * We generally want to remove null values from objects written to disk and cache, because it decreases the amount of data stored in memory and on disk.
- * On native, when merging an existing value with new changes, SQLite will use JSON_PATCH, which removes top-level nullish values.
- * To be consistent with the behaviour for merge, we'll also want to remove null values for "set" operations.
+ * Checks whether the given value can be merged. It has to be an object, but not an array, RegExp or Date.
+ * Mostly copied from https://medium.com/@lubaka.a/how-to-remove-lodash-performance-improvement-b306669ad0e1.
  */
-function fastMerge(target, source, shouldRemoveNestedNulls = true) {
-    // We have to ignore arrays and nullish values here,
-    // otherwise "mergeObject" will throw an error,
-    // because it expects an object as "source"
-    if (Array.isArray(source) || source === null || source === undefined) {
-        return source;
-    }
-    return mergeObject(target, source, shouldRemoveNestedNulls);
+function isMergeableObject(value) {
+    const isNonNullObject = value != null ? typeof value === 'object' : false;
+    return isNonNullObject && !(value instanceof RegExp) && !(value instanceof Date) && !Array.isArray(value);
 }
 /** Deep removes the nested null values from the given value. */
 function removeNestedNullValues(value) {
@@ -192,4 +210,14 @@ function omit(obj, condition) {
 function hasWithOnyxInstance(mapping) {
     return 'withOnyxInstance' in mapping && mapping.withOnyxInstance;
 }
-exports.default = { isEmptyObject, fastMerge, formatActionName, removeNestedNullValues, checkCompatibilityWithExistingValue, pick, omit, hasWithOnyxInstance };
+exports.default = {
+    fastMerge,
+    isEmptyObject,
+    formatActionName,
+    removeNestedNullValues,
+    checkCompatibilityWithExistingValue,
+    pick,
+    omit,
+    hasWithOnyxInstance,
+    ONYX_INTERNALS__REPLACE_OBJECT_MARK,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "2.0.117",
+  "version": "2.0.118",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",