json-diff-ts 5.0.0-alpha.1 → 5.0.0-alpha.2

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-type FunctionKey = (obj: any, shouldReturnKeyName?: boolean) => any;
+type FunctionKey<T = any> = (obj: T, shouldReturnKeyName?: boolean, index?: number) => any;
+
 type EmbeddedObjKeysType = Record<string, string | FunctionKey>;
 type EmbeddedObjKeysMapType = Map<string | RegExp, string | FunctionKey>;
 declare enum Operation {
     REMOVE = "REMOVE",
     ADD = "ADD",
-    UPDATE = "UPDATE",
-    MOVE = "MOVE"
+    UPDATE = "UPDATE"
 }
 interface IChange {
     type: Operation;
@@ -13,8 +13,6 @@ interface IChange {
     embeddedKey?: string | FunctionKey;
     value?: any;
     oldValue?: any;
-    oldIndex?: number;
-    newIndex?: number;
     changes?: IChange[];
 }
 type Changeset = IChange[];
@@ -25,14 +23,14 @@ interface IAtomicChange {
     valueType: string | null;
     value?: any;
     oldValue?: any;
-    oldIndex?: number;
-    newIndex?: number;
 }
 interface Options {
+    /** Identify array elements by a stable key instead of index. */
+    arrayIdentityKeys?: EmbeddedObjKeysType | EmbeddedObjKeysMapType;
+    /** @deprecated Use `arrayIdentityKeys` instead. */
     embeddedObjKeys?: EmbeddedObjKeysType | EmbeddedObjKeysMapType;
-    keysToSkip?: string[];
+    keysToSkip?: readonly string[];
     treatTypeChangeAsReplace?: boolean;
-    detectArrayMoves?: boolean;
 }
 /**
  * Computes the difference between two objects.
@@ -123,5 +121,185 @@ declare const createContainer: (value: object | []) => IComparisonEnrichedNode;
 declare const enrich: (object: any) => IComparisonEnrichedNode;
 declare const applyChangelist: (object: IComparisonEnrichedNode, changelist: IAtomicChange[]) => IComparisonEnrichedNode;
 declare const compare: (oldObject: any, newObject: any) => IComparisonEnrichedNode;
+interface IComparisonDict {
+    type: string;
+    value?: any;
+    oldValue?: any;
+}
+interface IFlatChange {
+    path: string;
+    type: string;
+    value?: any;
+    oldValue?: any;
+}
+/**
+ * Recursively serializes an enriched comparison tree to a plain JS object.
+ * The result is JSON-serializable when contained `value`/`oldValue` are
+ * themselves JSON-serializable. Includes `value`/`oldValue` based on change
+ * type, not truthiness — `null` is preserved as a valid JSON value.
+ */
+declare const comparisonToDict: (node: IComparisonEnrichedNode) => IComparisonDict;
+/**
+ * Flattens an enriched comparison tree to a list of leaf changes with paths.
+ * Uses dot notation for identifier keys and bracket-quote notation for
+ * non-identifier keys (per spec Section 5.5).
+ *
+ * By default, `UNCHANGED` entries are excluded. Set `includeUnchanged: true`
+ * to include them.
+ */
+declare const comparisonToFlatList: (node: IComparisonEnrichedNode, options?: {
+    includeUnchanged?: boolean;
+}) => IFlatChange[];
+
+type DeltaPathSegment = {
+    type: 'root';
+} | {
+    type: 'property';
+    name: string;
+} | {
+    type: 'index';
+    index: number;
+} | {
+    type: 'keyFilter';
+    property: string;
+    value: unknown;
+} | {
+    type: 'valueFilter';
+    value: unknown;
+};
+/**
+ * Format a value as a canonical JSON Delta filter literal.
+ * Strings → single-quoted with doubled-quote escaping.
+ * Numbers, booleans, null → plain JSON representation.
+ */
+declare function formatFilterLiteral(value: unknown): string;
+/**
+ * Parse a filter literal string into a typed JS value.
+ * Reverse of formatFilterLiteral.
+ */
+declare function parseFilterLiteral(s: string): unknown;
+/**
+ * Parse a JSON Delta Path string into an array of typed segments.
+ * Follows the grammar from the JSON Delta spec Section 5.1.
+ */
+declare function parseDeltaPath(path: string): DeltaPathSegment[];
+/**
+ * Build a canonical JSON Delta Path string from an array of segments.
+ */
+declare function buildDeltaPath(segments: DeltaPathSegment[]): string;
+
+type DeltaOp = 'add' | 'remove' | 'replace';
+interface IDeltaOperation {
+    op: DeltaOp;
+    path: string;
+    value?: any;
+    oldValue?: any;
+    [key: string]: any;
+}
+interface IJsonDelta {
+    format: 'json-delta';
+    version: number;
+    operations: IDeltaOperation[];
+    [key: string]: any;
+}
+interface DeltaOptions extends Options {
+    /** Include oldValue for reversibility. Default: true */
+    reversible?: boolean;
+}
+declare function validateDelta(delta: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Compute a canonical JSON Delta between two objects.
+ * This is the spec-conformant delta producer.
+ */
+declare function diffDelta(oldObj: any, newObj: any, options?: DeltaOptions): IJsonDelta;
+/**
+ * Convert an existing v4 changeset or atomic changes to a JSON Delta document.
+ * Best-effort bridge — filter literals will always be string-quoted.
+ * Use `diffDelta()` for canonical spec-conformant output.
+ */
+declare function toDelta(changeset: Changeset | IAtomicChange[], options?: {
+    reversible?: boolean;
+}): IJsonDelta;
+/**
+ * Convert a JSON Delta document to v4 atomic changes.
+ * Returns IAtomicChange[] — one atom per delta operation.
+ * Use `unatomizeChangeset(fromDelta(delta))` if you need a hierarchical Changeset.
+ */
+declare function fromDelta(delta: IJsonDelta): IAtomicChange[];
+/**
+ * Compute the inverse of a JSON Delta document (spec Section 9.2).
+ * Requires all replace/remove operations to have oldValue.
+ */
+declare function invertDelta(delta: IJsonDelta): IJsonDelta;
+/**
+ * Apply a JSON Delta document to an object.
+ * Processes operations sequentially. Handles root operations directly.
+ * Returns the result (MUST use return value for root primitive replacements).
+ */
+declare function applyDelta(obj: any, delta: IJsonDelta): any;
+/**
+ * Revert a JSON Delta by computing its inverse and applying it.
+ * Requires all replace/remove operations to have oldValue.
+ */
+declare function revertDelta(obj: any, delta: IJsonDelta): any;
+
+/**
+ * Returns a copy of the operation containing only spec-defined keys
+ * (`op`, `path`, `value`, `oldValue`). Complement of `operationExtensions`.
+ */
+declare function operationSpecDict(op: IDeltaOperation): IDeltaOperation;
+/**
+ * Returns a record of non-spec keys from the operation (extension properties).
+ * Complement of `operationSpecDict`.
+ */
+declare function operationExtensions(op: IDeltaOperation): Record<string, any>;
+/**
+ * Returns the terminal property name from the operation's path, or `null`
+ * for root, index, and filter segments.
+ */
+declare function leafProperty(op: IDeltaOperation): string | null;
+/**
+ * Returns a copy of the delta with only spec-defined keys in the envelope
+ * and each operation. Strips all extension properties.
+ */
+declare function deltaSpecDict(delta: IJsonDelta): IJsonDelta;
+/**
+ * Returns a record of non-spec keys from the delta envelope.
+ * Complement of `deltaSpecDict`.
+ */
+declare function deltaExtensions(delta: IJsonDelta): Record<string, any>;
+/**
+ * Transforms each operation in the delta using the provided function.
+ * Returns a new delta (immutable). Preserves all envelope properties.
+ */
+declare function deltaMap(delta: IJsonDelta, fn: (op: IDeltaOperation, index: number) => IDeltaOperation): IJsonDelta;
+/**
+ * Returns a new delta with the given extension properties merged onto every
+ * operation. Immutable — the original delta is not modified.
+ */
+declare function deltaStamp(delta: IJsonDelta, extensions: Record<string, any>): IJsonDelta;
+/**
+ * Groups operations in the delta by the result of `keyFn`. Returns a record
+ * mapping each key to a sub-delta containing only the matching operations.
+ * Each sub-delta preserves all envelope properties.
+ */
+declare function deltaGroupBy(delta: IJsonDelta, keyFn: (op: IDeltaOperation) => string): Record<string, IJsonDelta>;
+interface SquashDeltasOptions extends DeltaOptions {
+    /** Pre-computed final state. When provided with deltas, used instead of computing. */
+    target?: any;
+    /** Verify that `target` matches sequential application of deltas. Default: true. */
+    verifyTarget?: boolean;
+}
+/**
+ * Compacts multiple deltas into a single net-effect delta. The result is
+ * equivalent to applying all deltas sequentially, but expressed as a single
+ * `source → final` diff.
+ *
+ * Envelope extensions from all input deltas are merged (last-wins on conflict).
+ */
+declare function squashDeltas(source: any, deltas: IJsonDelta[], options?: SquashDeltasOptions): IJsonDelta;
 
-export { type Changeset, CompareOperation, type EmbeddedObjKeysMapType, type EmbeddedObjKeysType, type IAtomicChange, type IChange, type IComparisonEnrichedNode, Operation, type Options, applyChangelist, applyChangeset, atomizeChangeset, compare, createContainer, createValue, diff, enrich, getTypeOfObj, revertChangeset, unatomizeChangeset };
+export { type Changeset, CompareOperation, type DeltaOp, type DeltaOptions, type DeltaPathSegment, type EmbeddedObjKeysMapType, type EmbeddedObjKeysType, type IAtomicChange, type IChange, type IComparisonDict, type IComparisonEnrichedNode, type IDeltaOperation, type IFlatChange, type IJsonDelta, Operation, type Options, type SquashDeltasOptions, applyChangelist, applyChangeset, applyDelta, atomizeChangeset, buildDeltaPath, compare, comparisonToDict, comparisonToFlatList, createContainer, createValue, deltaExtensions, deltaGroupBy, deltaMap, deltaSpecDict, deltaStamp, diff, diffDelta, enrich, formatFilterLiteral, fromDelta, getTypeOfObj, invertDelta, leafProperty, operationExtensions, operationSpecDict, parseDeltaPath, parseFilterLiteral, revertChangeset, revertDelta, squashDeltas, toDelta, unatomizeChangeset, validateDelta };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-type FunctionKey = (obj: any, shouldReturnKeyName?: boolean) => any;
+type FunctionKey<T = any> = (obj: T, shouldReturnKeyName?: boolean, index?: number) => any;
+
 type EmbeddedObjKeysType = Record<string, string | FunctionKey>;
 type EmbeddedObjKeysMapType = Map<string | RegExp, string | FunctionKey>;
 declare enum Operation {
     REMOVE = "REMOVE",
     ADD = "ADD",
-    UPDATE = "UPDATE",
-    MOVE = "MOVE"
+    UPDATE = "UPDATE"
 }
 interface IChange {
     type: Operation;
@@ -13,8 +13,6 @@ interface IChange {
     embeddedKey?: string | FunctionKey;
     value?: any;
     oldValue?: any;
-    oldIndex?: number;
-    newIndex?: number;
     changes?: IChange[];
 }
 type Changeset = IChange[];
@@ -25,14 +23,14 @@ interface IAtomicChange {
     valueType: string | null;
     value?: any;
     oldValue?: any;
-    oldIndex?: number;
-    newIndex?: number;
 }
 interface Options {
+    /** Identify array elements by a stable key instead of index. */
+    arrayIdentityKeys?: EmbeddedObjKeysType | EmbeddedObjKeysMapType;
+    /** @deprecated Use `arrayIdentityKeys` instead. */
     embeddedObjKeys?: EmbeddedObjKeysType | EmbeddedObjKeysMapType;
-    keysToSkip?: string[];
+    keysToSkip?: readonly string[];
     treatTypeChangeAsReplace?: boolean;
-    detectArrayMoves?: boolean;
 }
 /**
  * Computes the difference between two objects.
@@ -123,5 +121,185 @@ declare const createContainer: (value: object | []) => IComparisonEnrichedNode;
 declare const enrich: (object: any) => IComparisonEnrichedNode;
 declare const applyChangelist: (object: IComparisonEnrichedNode, changelist: IAtomicChange[]) => IComparisonEnrichedNode;
 declare const compare: (oldObject: any, newObject: any) => IComparisonEnrichedNode;
+interface IComparisonDict {
+    type: string;
+    value?: any;
+    oldValue?: any;
+}
+interface IFlatChange {
+    path: string;
+    type: string;
+    value?: any;
+    oldValue?: any;
+}
+/**
+ * Recursively serializes an enriched comparison tree to a plain JS object.
+ * The result is JSON-serializable when contained `value`/`oldValue` are
+ * themselves JSON-serializable. Includes `value`/`oldValue` based on change
+ * type, not truthiness — `null` is preserved as a valid JSON value.
+ */
+declare const comparisonToDict: (node: IComparisonEnrichedNode) => IComparisonDict;
+/**
+ * Flattens an enriched comparison tree to a list of leaf changes with paths.
+ * Uses dot notation for identifier keys and bracket-quote notation for
+ * non-identifier keys (per spec Section 5.5).
+ *
+ * By default, `UNCHANGED` entries are excluded. Set `includeUnchanged: true`
+ * to include them.
+ */
+declare const comparisonToFlatList: (node: IComparisonEnrichedNode, options?: {
+    includeUnchanged?: boolean;
+}) => IFlatChange[];
+
+type DeltaPathSegment = {
+    type: 'root';
+} | {
+    type: 'property';
+    name: string;
+} | {
+    type: 'index';
+    index: number;
+} | {
+    type: 'keyFilter';
+    property: string;
+    value: unknown;
+} | {
+    type: 'valueFilter';
+    value: unknown;
+};
+/**
+ * Format a value as a canonical JSON Delta filter literal.
+ * Strings → single-quoted with doubled-quote escaping.
+ * Numbers, booleans, null → plain JSON representation.
+ */
+declare function formatFilterLiteral(value: unknown): string;
+/**
+ * Parse a filter literal string into a typed JS value.
+ * Reverse of formatFilterLiteral.
+ */
+declare function parseFilterLiteral(s: string): unknown;
+/**
+ * Parse a JSON Delta Path string into an array of typed segments.
+ * Follows the grammar from the JSON Delta spec Section 5.1.
+ */
+declare function parseDeltaPath(path: string): DeltaPathSegment[];
+/**
+ * Build a canonical JSON Delta Path string from an array of segments.
+ */
+declare function buildDeltaPath(segments: DeltaPathSegment[]): string;
+
+type DeltaOp = 'add' | 'remove' | 'replace';
+interface IDeltaOperation {
+    op: DeltaOp;
+    path: string;
+    value?: any;
+    oldValue?: any;
+    [key: string]: any;
+}
+interface IJsonDelta {
+    format: 'json-delta';
+    version: number;
+    operations: IDeltaOperation[];
+    [key: string]: any;
+}
+interface DeltaOptions extends Options {
+    /** Include oldValue for reversibility. Default: true */
+    reversible?: boolean;
+}
+declare function validateDelta(delta: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Compute a canonical JSON Delta between two objects.
+ * This is the spec-conformant delta producer.
+ */
+declare function diffDelta(oldObj: any, newObj: any, options?: DeltaOptions): IJsonDelta;
+/**
+ * Convert an existing v4 changeset or atomic changes to a JSON Delta document.
+ * Best-effort bridge — filter literals will always be string-quoted.
+ * Use `diffDelta()` for canonical spec-conformant output.
+ */
+declare function toDelta(changeset: Changeset | IAtomicChange[], options?: {
+    reversible?: boolean;
+}): IJsonDelta;
+/**
+ * Convert a JSON Delta document to v4 atomic changes.
+ * Returns IAtomicChange[] — one atom per delta operation.
+ * Use `unatomizeChangeset(fromDelta(delta))` if you need a hierarchical Changeset.
+ */
+declare function fromDelta(delta: IJsonDelta): IAtomicChange[];
+/**
+ * Compute the inverse of a JSON Delta document (spec Section 9.2).
+ * Requires all replace/remove operations to have oldValue.
+ */
+declare function invertDelta(delta: IJsonDelta): IJsonDelta;
+/**
+ * Apply a JSON Delta document to an object.
+ * Processes operations sequentially. Handles root operations directly.
+ * Returns the result (MUST use return value for root primitive replacements).
+ */
+declare function applyDelta(obj: any, delta: IJsonDelta): any;
+/**
+ * Revert a JSON Delta by computing its inverse and applying it.
+ * Requires all replace/remove operations to have oldValue.
+ */
+declare function revertDelta(obj: any, delta: IJsonDelta): any;
+
+/**
+ * Returns a copy of the operation containing only spec-defined keys
+ * (`op`, `path`, `value`, `oldValue`). Complement of `operationExtensions`.
+ */
+declare function operationSpecDict(op: IDeltaOperation): IDeltaOperation;
+/**
+ * Returns a record of non-spec keys from the operation (extension properties).
+ * Complement of `operationSpecDict`.
+ */
+declare function operationExtensions(op: IDeltaOperation): Record<string, any>;
+/**
+ * Returns the terminal property name from the operation's path, or `null`
+ * for root, index, and filter segments.
+ */
+declare function leafProperty(op: IDeltaOperation): string | null;
+/**
+ * Returns a copy of the delta with only spec-defined keys in the envelope
+ * and each operation. Strips all extension properties.
+ */
+declare function deltaSpecDict(delta: IJsonDelta): IJsonDelta;
+/**
+ * Returns a record of non-spec keys from the delta envelope.
+ * Complement of `deltaSpecDict`.
+ */
+declare function deltaExtensions(delta: IJsonDelta): Record<string, any>;
+/**
+ * Transforms each operation in the delta using the provided function.
+ * Returns a new delta (immutable). Preserves all envelope properties.
+ */
+declare function deltaMap(delta: IJsonDelta, fn: (op: IDeltaOperation, index: number) => IDeltaOperation): IJsonDelta;
+/**
+ * Returns a new delta with the given extension properties merged onto every
+ * operation. Immutable — the original delta is not modified.
+ */
+declare function deltaStamp(delta: IJsonDelta, extensions: Record<string, any>): IJsonDelta;
+/**
+ * Groups operations in the delta by the result of `keyFn`. Returns a record
+ * mapping each key to a sub-delta containing only the matching operations.
+ * Each sub-delta preserves all envelope properties.
+ */
+declare function deltaGroupBy(delta: IJsonDelta, keyFn: (op: IDeltaOperation) => string): Record<string, IJsonDelta>;
+interface SquashDeltasOptions extends DeltaOptions {
+    /** Pre-computed final state. When provided with deltas, used instead of computing. */
+    target?: any;
+    /** Verify that `target` matches sequential application of deltas. Default: true. */
+    verifyTarget?: boolean;
+}
+/**
+ * Compacts multiple deltas into a single net-effect delta. The result is
+ * equivalent to applying all deltas sequentially, but expressed as a single
+ * `source → final` diff.
+ *
+ * Envelope extensions from all input deltas are merged (last-wins on conflict).
+ */
+declare function squashDeltas(source: any, deltas: IJsonDelta[], options?: SquashDeltasOptions): IJsonDelta;
 
-export { type Changeset, CompareOperation, type EmbeddedObjKeysMapType, type EmbeddedObjKeysType, type IAtomicChange, type IChange, type IComparisonEnrichedNode, Operation, type Options, applyChangelist, applyChangeset, atomizeChangeset, compare, createContainer, createValue, diff, enrich, getTypeOfObj, revertChangeset, unatomizeChangeset };
+export { type Changeset, CompareOperation, type DeltaOp, type DeltaOptions, type DeltaPathSegment, type EmbeddedObjKeysMapType, type EmbeddedObjKeysType, type IAtomicChange, type IChange, type IComparisonDict, type IComparisonEnrichedNode, type IDeltaOperation, type IFlatChange, type IJsonDelta, Operation, type Options, type SquashDeltasOptions, applyChangelist, applyChangeset, applyDelta, atomizeChangeset, buildDeltaPath, compare, comparisonToDict, comparisonToFlatList, createContainer, createValue, deltaExtensions, deltaGroupBy, deltaMap, deltaSpecDict, deltaStamp, diff, diffDelta, enrich, formatFilterLiteral, fromDelta, getTypeOfObj, invertDelta, leafProperty, operationExtensions, operationSpecDict, parseDeltaPath, parseFilterLiteral, revertChangeset, revertDelta, squashDeltas, toDelta, unatomizeChangeset, validateDelta };