shelving/util/diff.d.ts

Toolkit for using data in JavaScript.

import type { ImmutableArray } from "./array.js";
import type { DeepPartial, ImmutableObject } from "./object.js";
/** The `SAME` symbol indicates sameness. */
export declare const SAME: unique symbol;
/**
 * Deeply diff two unknown values to produce the transformation needed to transform `left` into `right`, or the `SAME` constant if they are deeply equal.
 *
 * @param left The old value.
 * @param right The new/target value.
 *
 * @return The transformation needed to transform `left` into `right`
 * - If the two values are deeply equal the `SAME` constant is returned.
 * - Unequal scalar values can't be diffed, so `right` is always returned.
 * - If `right` is an array, returns whatever `deepDiffArray()` returns.
 * - If `right` is an object, returns whatever `deepDiffObject()` returns.
 */
export declare function deepDiff<R extends ImmutableObject>(left: unknown, right: R): R | DeepPartial<R> | typeof SAME;
export declare function deepDiff<R>(left: unknown, right: R): R | typeof SAME;
/**
 * Diff two arrays to produce the transformation needed to transform `left` into `right`
 * DH: Currently arrays don't diff at an item level, they return the entire new array if not deeply equal.
 *
 * @returns The `right` array if it is different to `left`, or the exact `SAME` constant otherwise.
 * - If the two values are deeply equal the `SAME` constant is returned.
 */
export declare function deepDiffArray<R extends ImmutableArray>(left: ImmutableArray, right: R): R | typeof SAME;
/**
 * Diff two objects to produce the transformation needed to transform `left` into `right`
 * - Only works on enumerable own keys (as returned by `Object.keys()`).
 * - Includes a constructor check — if `left` and `right` have different constructors they will not be merged and `right` will be returned (ensures arrays aren't compared with objects).
 * - Properties that exist in `left` but not `right` (i.e. have been deleted) are represented with `undefined`
 *
 * @return Object containing the missing/updated properties that `left` needs to become `right`.
 * - If the two values are deeply equal the `SAME` constant is returned.
 * - If `left` isn't an object then the result can't be diffed so entire `right` is returned.
 */
export declare function deepDiffObject<R extends ImmutableObject>(left: ImmutableObject, right: R): R | DeepPartial<R> | typeof SAME;