j-templates 8.2.0 → 9.0.0

package/Utils/json.d.ts

@@ -3,17 +3,73 @@ export type JsonWrite = {
     path: (string | number)[];
     value: unknown;
 };
-export type JsonMove = {
-    type: "move";
+/** Removes the property the path ends with from the object holding it */
+export type JsonDelete = {
+    type: "delete";
     path: (string | number)[];
-    sourceProp: string | number;
-    targetProp: string | number;
+};
+/** How an inserted splice item gets its value */
+export declare enum SPLICE_ACTION {
+    /** The element at `from` in the array before the splice is applied */
+    MOVE = 1,
+    /** A new value */
+    INSERT = 2
+}
+export type JsonSpliceItem = {
+    type: SPLICE_ACTION.MOVE;
+    from: number;
+} | {
+    type: SPLICE_ACTION.INSERT;
+    value: unknown;
+};
+/**
+ * One `Array.prototype.splice` call. Splices are applied in order, so `index` is a position in the
+ * array as the splices before it left it. A moved item's `from` is an index in the array before any
+ * splice was applied.
+ */
+export type JsonSplice = {
+    index: number;
+    delete: number;
+    insert: JsonSpliceItem[];
+};
+/** The splices that turn the array at `path` into its new value */
+export type JsonSpliceRecord = {
+    type: "splice";
+    path: (string | number)[];
+    splices: JsonSplice[];
 };
 /**
  * Result of a JSON diff operation, containing paths and values that changed.
  * @template T - The type of the JSON value being diffed
  */
-export type JsonDiffResult<T = unknown> = (JsonMove | JsonWrite)[];
+export type JsonDiffResult<T = unknown> = (JsonWrite | JsonDelete | JsonSpliceRecord)[];
+/**
+ * How JsonDiff handles an object or array that changed:
+ * - `"diff"`: walk into it. An array is diffed by position.
+ * - `"splice"`: arrays only. Diff it as splices that match elements by the diff's identity (see
+ *   JsonDiffIdentityFunc), without walking into them. Anything else is diffed as `"diff"`.
+ * - `"skip"`: record nothing for it.
+ * - `"write"`: write the new value as is.
+ */
+export type JsonDiffStrategy = "diff" | "splice" | "skip" | "write";
+/**
+ * Chooses how JsonDiff handles a changed object or array, given the new value, the old one (of any
+ * type) and the path they're at. Returning undefined means `"diff"`. It isn't called for primitives. `path` is the diff's own, so it
+ * must not be kept or changed.
+ */
+export type JsonDiffStrategyFunc = (newValue: any, oldValue: any, path: readonly (string | number)[]) => JsonDiffStrategy | undefined;
+/**
+ * What a spliced array's element is compared by: two elements whose identities are === are the same
+ * element, so it's matched and never diffed into. It's called for elements of any type, primitives
+ * included, but not to compare two elements that are already ===, so it must give the same identity
+ * for the same value. When two different elements share an identity, they're treated as the same
+ * element; avoiding that is up to the function.
+ */
+export type JsonDiffIdentityFunc = (value: any) => unknown;
+/** The default strategy: every changed object and array is diffed into, arrays by position */
+export declare const JsonDiffDefaultStrategy: JsonDiffStrategyFunc;
+/** The default identity: an element is its own identity, so elements are compared by === */
+export declare const JsonDiffDefaultIdentity: JsonDiffIdentityFunc;
 /**
  * Determines the JSON type of a value.
  * @param value - The value to check
@@ -38,37 +94,121 @@ export declare function JsonMerge(source: unknown, patch: unknown): unknown;
  */
 export declare function JsonDeepClone<T>(value: T, type?: string): T;
 /**
- * Applies a diff result to a root value in place: moves first, then writes.
- * @param resolve - Returns the object to walk into for `parent[prop]`; the walk stores it back at
- *   `parent[prop]` when it's a different object
+ * Applies a diff result to a root value in place, one record at a time in order. A diff doesn't own
+ * its values (see JsonDiff), so each value written or inserted is deep-cloned first: the root never
+ * shares an object with the diff, the value it was computed from, or another record, unless
+ * `clone` says otherwise.
+ * - A write assigns its value at its path
+ * - A delete removes the property its path ends with
+ * - A splice record splices the array at its path in place (see JsonApplySplices)
+ * @param root - The value to update; must be an object or array
+ * @param diff - The diff result to apply
  * @param assign - Assigns a written value (already cloned) to its parent
- * @param move - Assigns a moved value to its new slot. A move relocates a value that's already in
- *   the root, so it's kept separate from `assign`, which handles new values.
+ * @param remove - Removes a deleted property from its parent
+ * @param spliced - Called with each array a splice record changed, after it's changed
+ * @param clone - Copies each value before it's written or inserted. A caller that already owns the
+ *   diff's values can pass one that keeps them, or parts of them, as they are.
+ * @throws For a write or delete with an empty path: the root can't be replaced or removed, only
+ *   changed inside. JsonDiff records one only when the root's JSON type changes.
  */
-export declare function JsonApplyDiff(root: any, diff: JsonDiffResult, assign?: (parent: any, prop: string | number, value: any) => void): void;
+export declare function JsonApplyDiff(root: any, diff: JsonDiffResult, assign?: (parent: any, prop: string | number, value: any) => void, remove?: (parent: any, prop: string | number) => void, spliced?: (array: unknown[]) => void, clone?: (value: unknown) => unknown): void;
 /**
- * Applies a diff result to a root value in place. A diff doesn't own its values (see JsonDiff),
- * so each value is deep-cloned before it's written: the root never shares an object with the
- * diff, the value it was computed from, or another record.
- * - A single record with an empty path replaces the root's contents, keeping its identity
- * - Otherwise each record's value is assigned at its path
- * @param root - The value to update; must be an object or array
- * @param diff - The diff result to apply
- * @param callback - Called with the object written to, the property written ("" when an array
- *   root is replaced), and whether that property is new to the object
- * @throws If a root replacement would change the root's JSON type, or the root is a primitive
+ * Applies splices to an array in place, in one pass however many there are: the new contents are
+ * built from the old ones, then written back into the same array. A moved item is the old element
+ * at its `from`, as is; an inserted item's value is deep-cloned.
+ * @param splices - In ascending, non-overlapping order, as JsonDiffArraySplice returns them: each
+ *   one's index is at or after where the one before it ended
+ * @param clone - Copies each inserted value; see JsonApplyDiff
+ * @throws When a splice starts before the one before it ended
+ */
+export declare function JsonApplySplices(array: unknown[], splices: readonly JsonSplice[], clone?: (value: unknown) => unknown): void;
+/**
+ * Whether two JSON values differ, without recording how: it stops at the first difference and
+ * skips any subtree both values share, so it costs no more than walking what differs. An
+ * undefined property counts as absent, as in JSON. Arrays are compared by position.
+ * @param newValue - The new value
+ * @param oldValue - The old value to compare against
+ * @returns true when the values differ
  */
-export declare function JsonApplyWrites(root: any, diff: JsonWrite[], assign?: (parent: any, prop: string | number, value: any) => void): void;
+export declare function JsonHasChanges(newValue: unknown, oldValue: unknown): boolean;
+/**
+ * `newValue`, with every part that has no changes from the same place in `oldValue` (as
+ * JsonHasChanges compares them) replaced by `oldValue`'s object, so unchanged parts keep their
+ * identity. Neither value is changed: a container of `newValue` is copied only when one of its
+ * children is replaced, and kept as it is otherwise. Arrays are compared by position.
+ *
+ *   old: { a: { x: 1 }, b: { y: 1 } }
+ *   new: { a: { x: 1 }, b: { y: 2 } }
+ *   result: { a: old.a, b: new.b }, a new object
+ *
+ * @param newValue - The new value
+ * @param oldValue - The value whose objects are kept where nothing changed
+ * @returns `oldValue` itself when nothing changed, otherwise `newValue` or a copy of it holding
+ *   `oldValue`'s unchanged parts
+ */
+export declare function JsonMaintainUnchanged<T>(newValue: T, oldValue: unknown): T;
+/** Sets a key as an own property, even `__proto__`, which plain assignment would make the prototype */
+export declare function SetOwnProperty(target: {
+    [key: string]: unknown;
+}, key: string, value: unknown): void;
 /**
  * Computes the differences between two JSON values.
- * Returns an array of paths and values that changed from oldValue to newValue. A record doesn't
+ * Returns an array of paths and values that changed from oldValue to newValue. A value is only
+ * written whole where its JSON type changes (or a strategy says so); an object or array of the
+ * same type is always diffed into, however much of it changed. So the root itself is only ever
+ * written when its type changes, and a diff of values of the same type can always be applied
+ * in place. A record doesn't
  * own its value: it references `newValue`'s objects, so two records can share one, and
  * JsonApplyDiff clones each value as it's applied.
  * @template T - The type of the JSON values being compared
  * @param newValue - The new value
  * @param oldValue - The old value to compare against
- * @param rootPath - Optional dot-separated string for the base path (for internal recursion)
- * @param initResult - Optional initial result array (for internal recursion)
+ * @param rootPath - Optional dot-separated string for the base path
+ * @param strategy - Optional choice of how each changed object or array is diffed; without one,
+ *   everything is diffed by walking into it, arrays by position
+ * @param identity - Optional identity a spliced array's elements are compared by; without one,
+ *   elements are compared by ===. See JsonDiffIdentityFunc
  * @returns Array of change records with path and new value
  */
-export declare function JsonDiff<T>(newValue: T, oldValue: T, rootPath?: string, initResult?: JsonDiffResult<T>): JsonDiffResult<T>;
+export declare function JsonDiff<T>(newValue: T, oldValue: T, rootPath?: string, strategy?: JsonDiffStrategyFunc, identity?: JsonDiffIdentityFunc): JsonDiffResult<T>;
+/**
+ * Appends the differences between two JSON values to `result`, so several values can be diffed into
+ * one result.
+ * @param path - The path the values are at
+ * @param strategy - See JsonDiff
+ * @param identity - See JsonDiff
+ * @returns The result
+ */
+export declare function JsonDiffInto<T>(newValue: T, oldValue: T, path: (string | number)[], result: JsonDiffResult<T>, strategy?: JsonDiffStrategyFunc, identity?: JsonDiffIdentityFunc): JsonDiffResult<T>;
+/**
+ * The splices that turn `oldValue` into `newValue`, matching elements by identity without walking
+ * into them: two elements are the same when their identities are ===. With the default identity,
+ * that's the elements themselves. A matched element is never diffed into, even when it isn't === to
+ * its match. An identity that repeats is matched in order, and a repeat with no old element left to
+ * match is inserted.
+ *
+ * It works in four stages, followed through this example in the comments below:
+ *
+ *   old: [A, B, C, D, E, F]
+ *   new: [A, E, B, X, D, F]
+ *
+ * 1. Trim the elements identical at the start and end (A and F): they can't need a change.
+ * 2. Match each remaining new element to the old index holding the same element, or -1.
+ * 3. Choose which matched elements stay in place: the longest run of them still in their old
+ *    order (B, D). Keeping the longest run is what keeps the number of moves as small as possible.
+ * 4. Walk both arrays from kept element to kept element. Between two kept elements, delete the
+ *    old elements that aren't kept (C, E) and insert the new ones that aren't (E as a move, X as
+ *    a new value).
+ *
+ * @returns The splices, in the order to apply them; none when the arrays hold the same elements.
+ *   Applied in order to [A, B, C, D, E, F], with each move read from the array before any splice:
+ *
+ *   splice(1, 0, E)   [A, E, B, C, D, E, F]
+ *   splice(3, 1, X)   [A, E, B, X, D, E, F]
+ *   splice(5, 1)      [A, E, B, X, D, F]
+ *
+ * @param identity - What elements are compared by; see JsonDiffIdentityFunc. Elements that are
+ *   === are the same element without calling it, and it's called at most a few times for each
+ *   other element, so it must give the same identity for the same value.
+ */
+export declare function JsonDiffArraySplice(newValue: readonly unknown[], oldValue: readonly unknown[], identity?: JsonDiffIdentityFunc): JsonSplice[];