@loro-dev/json-patch 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +314 -2
- package/dist/diff.cjs +1666 -0
- package/dist/diff.d.cts +126 -0
- package/dist/diff.d.ts +126 -0
- package/dist/diff.js +1463 -0
- package/dist/index.cjs +1124 -0
- package/dist/index.d.cts +74 -0
- package/dist/index.d.ts +74 -0
- package/dist/index.js +1097 -0
- package/dist/loro.cjs +2722 -0
- package/dist/loro.d.cts +115 -0
- package/dist/loro.d.ts +115 -0
- package/dist/loro.js +2710 -0
- package/package.json +70 -3
package/dist/diff.d.cts
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
//#region src/types.d.ts
|
|
2
|
+
/** Plain JSON object value map. */
|
|
3
|
+
type JsonObject = {
|
|
4
|
+
readonly [key: string]: JsonValue;
|
|
5
|
+
};
|
|
6
|
+
/**
|
|
7
|
+
* Lossless value model shared across `@loro-dev/json-patch`, `@loro-dev/loro-repo-client`, and the Rust engine.
|
|
8
|
+
* Supports `bigint` (exact 64-bit integers outside JS `MAX_SAFE_INTEGER`) and raw `Uint8Array` binary blobs.
|
|
9
|
+
*/
|
|
10
|
+
type JsonValue = null | boolean | number | bigint | string | Uint8Array | readonly JsonValue[] | JsonObject;
|
|
11
|
+
/** Single step in a {@link JsonPath}: object property name or zero-based array index. */
|
|
12
|
+
type PathSeg = string | number;
|
|
13
|
+
/** Sequence of keys/indices addressing a node inside a {@link JsonValue}. Empty (`[]`) denotes the document root. */
|
|
14
|
+
type JsonPath = readonly PathSeg[];
|
|
15
|
+
/** Atomic JSON Patch operation supported by Loro Repo and `loro-json-patch`. */
|
|
16
|
+
type JsonOp = {
|
|
17
|
+
readonly op: "set";
|
|
18
|
+
readonly path: JsonPath;
|
|
19
|
+
readonly value: JsonValue;
|
|
20
|
+
} | {
|
|
21
|
+
readonly op: "unset";
|
|
22
|
+
readonly path: JsonPath;
|
|
23
|
+
} | {
|
|
24
|
+
readonly op: "arr_splice";
|
|
25
|
+
readonly path: JsonPath;
|
|
26
|
+
readonly at: number;
|
|
27
|
+
readonly del: number;
|
|
28
|
+
readonly items: readonly JsonValue[];
|
|
29
|
+
} | {
|
|
30
|
+
readonly op: "move";
|
|
31
|
+
readonly from: JsonPath;
|
|
32
|
+
readonly to: JsonPath;
|
|
33
|
+
} | {
|
|
34
|
+
readonly op: "str_splice";
|
|
35
|
+
readonly path: JsonPath;
|
|
36
|
+
readonly at: number;
|
|
37
|
+
readonly del: number;
|
|
38
|
+
readonly ins: string;
|
|
39
|
+
};
|
|
40
|
+
/** Ordered sequence of {@link JsonOp} mutations applied atomically. */
|
|
41
|
+
type JsonPatch = readonly JsonOp[];
|
|
42
|
+
/** Machine-readable failure classification for {@link ApplyError}. */
|
|
43
|
+
type ApplyErrorKind = "InvalidPath" | "MissingPath" | "IndexOutOfBounds" | "TypeMismatch" | "InvalidUtf16Boundary" | "InvalidValue";
|
|
44
|
+
/** Error thrown when {@link apply} or {@link applyOp} rejects an invalid path, index, boundary, or value. */
|
|
45
|
+
declare class ApplyError extends Error {
|
|
46
|
+
readonly kind: ApplyErrorKind;
|
|
47
|
+
readonly opIndex: number;
|
|
48
|
+
constructor(kind: ApplyErrorKind, opIndex: number, message: string);
|
|
49
|
+
}
|
|
50
|
+
/** Machine-readable failure classification for {@link DecodeError}. */
|
|
51
|
+
type DecodeErrorKind = "UnknownOp" | "UnknownOpName" | "InvalidFormat" | "InvalidPath" | "NonFiniteFloat" | "UnsupportedExtension" | "InvalidBase64" | "BytesRejected" | "Json" | "MessagePack";
|
|
52
|
+
/** Error thrown by JSON or MessagePack wire codecs when encoding/decoding malformed patches or values. */
|
|
53
|
+
declare class DecodeError extends Error {
|
|
54
|
+
readonly kind: DecodeErrorKind;
|
|
55
|
+
readonly opCode?: number | bigint;
|
|
56
|
+
constructor(kind: DecodeErrorKind, message: string, opCode?: number | bigint);
|
|
57
|
+
}
|
|
58
|
+
/** Returns `true` for plain JSON records (excluding `null`, arrays, `Uint8Array`, and class instances). */
|
|
59
|
+
declare function isPlainObject(v: unknown): v is Record<string, JsonValue>;
|
|
60
|
+
/** Validates that `value` is a legal {@link JsonValue} (no NaN/Infinity, no lone UTF-16 surrogates, valid i64/u64 bigints). */
|
|
61
|
+
declare function validateJsonValue(value: JsonValue, opIndex?: number): void;
|
|
62
|
+
/** Compares `number` and `bigint` values mathematically (handles `-0 === 0` and integer cross-type equality). */
|
|
63
|
+
declare function numbersEqual(a: number | bigint, b: number | bigint): boolean;
|
|
64
|
+
/** Deep structural equality for two {@link JsonValue}s (including `Uint8Array` byte-by-byte and `bigint`/`number`). */
|
|
65
|
+
declare function valuesEqual(a: JsonValue, b: JsonValue): boolean;
|
|
66
|
+
/** Returns `true` if two {@link JsonPath}s contain identical segments. */
|
|
67
|
+
declare function pathsEqual(a: JsonPath, b: JsonPath): boolean;
|
|
68
|
+
/** Returns `true` if either path is a prefix of the other (including exact equality). */
|
|
69
|
+
declare function pathsOverlap(a: JsonPath, b: JsonPath): boolean;
|
|
70
|
+
/** Throws {@link ApplyError} (`"InvalidUtf16Boundary"`) if `offset` is out of bounds or splits a UTF-16 surrogate pair. */
|
|
71
|
+
declare function assertValidUtf16Boundary(s: string, offset: number, opIndex: number): void;
|
|
72
|
+
/** Validates `[at, at + del)` is a valid UTF-16 range not splitting surrogate pairs and returns `at + del`. */
|
|
73
|
+
declare function assertValidUtf16Range(s: string, at: number, del: number, opIndex: number): number;
|
|
74
|
+
/** Throws {@link ApplyError} (`"InvalidValue"`) if `s` contains any unpaired UTF-16 high/low surrogate. */
|
|
75
|
+
declare function assertNoLoneSurrogates(s: string, opIndex: number): void;
|
|
76
|
+
//#endregion
|
|
77
|
+
//#region src/diff.d.ts
|
|
78
|
+
/** Wildcard segment matching any single key or array index inside a pattern. */
|
|
79
|
+
declare const ANY_SEG: unique symbol;
|
|
80
|
+
/** Rest wildcard matching zero or more trailing segments inside a pattern. */
|
|
81
|
+
declare const ANY_REST_SEG: unique symbol;
|
|
82
|
+
/** Single segment in a path-matching pattern (literal key/index, {@link ANY_SEG}, or {@link ANY_REST_SEG}). */
|
|
83
|
+
type PatternSeg = string | number | typeof ANY_SEG | typeof ANY_REST_SEG;
|
|
84
|
+
/** Returns `true` when `path` matches `pattern` (supports single-segment and multi-segment globs). */
|
|
85
|
+
declare function patternMatches(pattern: readonly PatternSeg[], path: JsonPath): boolean;
|
|
86
|
+
/** Extracts a stable item identity key from an array element (either a property name or extractor function). */
|
|
87
|
+
type KeyExtractor = string | ((val: JsonValue) => string | undefined);
|
|
88
|
+
/** Tree-array diffing specification enabling hierarchical `move` detection across parent/child arrays. */
|
|
89
|
+
interface TreeDiffSpec {
|
|
90
|
+
/** Pattern matching the tree array path. */
|
|
91
|
+
readonly rootPath: readonly PatternSeg[];
|
|
92
|
+
/** Unique node identifier property name. */
|
|
93
|
+
readonly idField: string;
|
|
94
|
+
/** Child array property name on each node. */
|
|
95
|
+
readonly childrenField: string;
|
|
96
|
+
}
|
|
97
|
+
/** Options controlling how {@link diff} handles arrays (keyed `move` emission and tree structures). */
|
|
98
|
+
interface DiffOptions {
|
|
99
|
+
/** Path-scoped key extractors; matching arrays diff by identity (`move` + item field diff) via LIS instead of positional splice. */
|
|
100
|
+
readonly keyExtractors?: readonly {
|
|
101
|
+
readonly path: readonly PatternSeg[];
|
|
102
|
+
readonly extractor: KeyExtractor;
|
|
103
|
+
}[];
|
|
104
|
+
/** Nested tree specifications for hierarchical reorder/reparent diffs. */
|
|
105
|
+
readonly treeSpecs?: readonly TreeDiffSpec[];
|
|
106
|
+
}
|
|
107
|
+
/** O(K log K) Longest Increasing Subsequence membership mask. */
|
|
108
|
+
declare function lisMask(seq: readonly number[]): boolean[];
|
|
109
|
+
/**
|
|
110
|
+
* Compute minimal `[fromIdx, toIdx]` move pairs in `O(K log K)` transforming `[0..K)`
|
|
111
|
+
* into `targetSeq` (a permutation of `0..K`), keeping the LIS stationary.
|
|
112
|
+
*/
|
|
113
|
+
declare function lisMovePairs(targetSeq: readonly number[]): [number, number][];
|
|
114
|
+
/** Single-pass UTF-16 common prefix/suffix string diff avoiding surrogate splits. */
|
|
115
|
+
declare function diffStringAt(path: readonly PathSeg[], oldStr: string, newStr: string, ops: JsonOp[]): void;
|
|
116
|
+
/**
|
|
117
|
+
* Computes {@link JsonOp} operations transforming plain JSON `oldState` into `newState`.
|
|
118
|
+
* Emits `str_splice` on modified strings, `arr_splice` on unkeyed arrays, and LIS-minimal `move` + inner diffs
|
|
119
|
+
* when `options.keyExtractors` matches an array path.
|
|
120
|
+
* This function does not inspect a Loro DocSchema. Its string splices may be rejected by
|
|
121
|
+
* strict Loro writes targeting atomic string values; use scalar `set` operations there and
|
|
122
|
+
* reserve `str_splice` for LoroText containers. Key extractors only control array identity.
|
|
123
|
+
*/
|
|
124
|
+
declare function diff(oldState: JsonValue, newState: JsonValue, options?: DiffOptions): JsonOp[];
|
|
125
|
+
//#endregion
|
|
126
|
+
export { valuesEqual as A, assertValidUtf16Boundary as C, pathsEqual as D, numbersEqual as E, pathsOverlap as O, assertNoLoneSurrogates as S, isPlainObject as T, JsonOp as _, PatternSeg as a, JsonValue as b, diffStringAt as c, patternMatches as d, ApplyError as f, JsonObject as g, DecodeErrorKind as h, KeyExtractor as i, validateJsonValue as k, lisMask as l, DecodeError as m, ANY_SEG as n, TreeDiffSpec as o, ApplyErrorKind as p, DiffOptions as r, diff as s, ANY_REST_SEG as t, lisMovePairs as u, JsonPatch as v, assertValidUtf16Range as w, PathSeg as x, JsonPath as y };
|
package/dist/diff.d.ts
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
//#region src/types.d.ts
|
|
2
|
+
/** Plain JSON object value map. */
|
|
3
|
+
type JsonObject = {
|
|
4
|
+
readonly [key: string]: JsonValue;
|
|
5
|
+
};
|
|
6
|
+
/**
|
|
7
|
+
* Lossless value model shared across `@loro-dev/json-patch`, `@loro-dev/loro-repo-client`, and the Rust engine.
|
|
8
|
+
* Supports `bigint` (exact 64-bit integers outside JS `MAX_SAFE_INTEGER`) and raw `Uint8Array` binary blobs.
|
|
9
|
+
*/
|
|
10
|
+
type JsonValue = null | boolean | number | bigint | string | Uint8Array | readonly JsonValue[] | JsonObject;
|
|
11
|
+
/** Single step in a {@link JsonPath}: object property name or zero-based array index. */
|
|
12
|
+
type PathSeg = string | number;
|
|
13
|
+
/** Sequence of keys/indices addressing a node inside a {@link JsonValue}. Empty (`[]`) denotes the document root. */
|
|
14
|
+
type JsonPath = readonly PathSeg[];
|
|
15
|
+
/** Atomic JSON Patch operation supported by Loro Repo and `loro-json-patch`. */
|
|
16
|
+
type JsonOp = {
|
|
17
|
+
readonly op: "set";
|
|
18
|
+
readonly path: JsonPath;
|
|
19
|
+
readonly value: JsonValue;
|
|
20
|
+
} | {
|
|
21
|
+
readonly op: "unset";
|
|
22
|
+
readonly path: JsonPath;
|
|
23
|
+
} | {
|
|
24
|
+
readonly op: "arr_splice";
|
|
25
|
+
readonly path: JsonPath;
|
|
26
|
+
readonly at: number;
|
|
27
|
+
readonly del: number;
|
|
28
|
+
readonly items: readonly JsonValue[];
|
|
29
|
+
} | {
|
|
30
|
+
readonly op: "move";
|
|
31
|
+
readonly from: JsonPath;
|
|
32
|
+
readonly to: JsonPath;
|
|
33
|
+
} | {
|
|
34
|
+
readonly op: "str_splice";
|
|
35
|
+
readonly path: JsonPath;
|
|
36
|
+
readonly at: number;
|
|
37
|
+
readonly del: number;
|
|
38
|
+
readonly ins: string;
|
|
39
|
+
};
|
|
40
|
+
/** Ordered sequence of {@link JsonOp} mutations applied atomically. */
|
|
41
|
+
type JsonPatch = readonly JsonOp[];
|
|
42
|
+
/** Machine-readable failure classification for {@link ApplyError}. */
|
|
43
|
+
type ApplyErrorKind = "InvalidPath" | "MissingPath" | "IndexOutOfBounds" | "TypeMismatch" | "InvalidUtf16Boundary" | "InvalidValue";
|
|
44
|
+
/** Error thrown when {@link apply} or {@link applyOp} rejects an invalid path, index, boundary, or value. */
|
|
45
|
+
declare class ApplyError extends Error {
|
|
46
|
+
readonly kind: ApplyErrorKind;
|
|
47
|
+
readonly opIndex: number;
|
|
48
|
+
constructor(kind: ApplyErrorKind, opIndex: number, message: string);
|
|
49
|
+
}
|
|
50
|
+
/** Machine-readable failure classification for {@link DecodeError}. */
|
|
51
|
+
type DecodeErrorKind = "UnknownOp" | "UnknownOpName" | "InvalidFormat" | "InvalidPath" | "NonFiniteFloat" | "UnsupportedExtension" | "InvalidBase64" | "BytesRejected" | "Json" | "MessagePack";
|
|
52
|
+
/** Error thrown by JSON or MessagePack wire codecs when encoding/decoding malformed patches or values. */
|
|
53
|
+
declare class DecodeError extends Error {
|
|
54
|
+
readonly kind: DecodeErrorKind;
|
|
55
|
+
readonly opCode?: number | bigint;
|
|
56
|
+
constructor(kind: DecodeErrorKind, message: string, opCode?: number | bigint);
|
|
57
|
+
}
|
|
58
|
+
/** Returns `true` for plain JSON records (excluding `null`, arrays, `Uint8Array`, and class instances). */
|
|
59
|
+
declare function isPlainObject(v: unknown): v is Record<string, JsonValue>;
|
|
60
|
+
/** Validates that `value` is a legal {@link JsonValue} (no NaN/Infinity, no lone UTF-16 surrogates, valid i64/u64 bigints). */
|
|
61
|
+
declare function validateJsonValue(value: JsonValue, opIndex?: number): void;
|
|
62
|
+
/** Compares `number` and `bigint` values mathematically (handles `-0 === 0` and integer cross-type equality). */
|
|
63
|
+
declare function numbersEqual(a: number | bigint, b: number | bigint): boolean;
|
|
64
|
+
/** Deep structural equality for two {@link JsonValue}s (including `Uint8Array` byte-by-byte and `bigint`/`number`). */
|
|
65
|
+
declare function valuesEqual(a: JsonValue, b: JsonValue): boolean;
|
|
66
|
+
/** Returns `true` if two {@link JsonPath}s contain identical segments. */
|
|
67
|
+
declare function pathsEqual(a: JsonPath, b: JsonPath): boolean;
|
|
68
|
+
/** Returns `true` if either path is a prefix of the other (including exact equality). */
|
|
69
|
+
declare function pathsOverlap(a: JsonPath, b: JsonPath): boolean;
|
|
70
|
+
/** Throws {@link ApplyError} (`"InvalidUtf16Boundary"`) if `offset` is out of bounds or splits a UTF-16 surrogate pair. */
|
|
71
|
+
declare function assertValidUtf16Boundary(s: string, offset: number, opIndex: number): void;
|
|
72
|
+
/** Validates `[at, at + del)` is a valid UTF-16 range not splitting surrogate pairs and returns `at + del`. */
|
|
73
|
+
declare function assertValidUtf16Range(s: string, at: number, del: number, opIndex: number): number;
|
|
74
|
+
/** Throws {@link ApplyError} (`"InvalidValue"`) if `s` contains any unpaired UTF-16 high/low surrogate. */
|
|
75
|
+
declare function assertNoLoneSurrogates(s: string, opIndex: number): void;
|
|
76
|
+
//#endregion
|
|
77
|
+
//#region src/diff.d.ts
|
|
78
|
+
/** Wildcard segment matching any single key or array index inside a pattern. */
|
|
79
|
+
declare const ANY_SEG: unique symbol;
|
|
80
|
+
/** Rest wildcard matching zero or more trailing segments inside a pattern. */
|
|
81
|
+
declare const ANY_REST_SEG: unique symbol;
|
|
82
|
+
/** Single segment in a path-matching pattern (literal key/index, {@link ANY_SEG}, or {@link ANY_REST_SEG}). */
|
|
83
|
+
type PatternSeg = string | number | typeof ANY_SEG | typeof ANY_REST_SEG;
|
|
84
|
+
/** Returns `true` when `path` matches `pattern` (supports single-segment and multi-segment globs). */
|
|
85
|
+
declare function patternMatches(pattern: readonly PatternSeg[], path: JsonPath): boolean;
|
|
86
|
+
/** Extracts a stable item identity key from an array element (either a property name or extractor function). */
|
|
87
|
+
type KeyExtractor = string | ((val: JsonValue) => string | undefined);
|
|
88
|
+
/** Tree-array diffing specification enabling hierarchical `move` detection across parent/child arrays. */
|
|
89
|
+
interface TreeDiffSpec {
|
|
90
|
+
/** Pattern matching the tree array path. */
|
|
91
|
+
readonly rootPath: readonly PatternSeg[];
|
|
92
|
+
/** Unique node identifier property name. */
|
|
93
|
+
readonly idField: string;
|
|
94
|
+
/** Child array property name on each node. */
|
|
95
|
+
readonly childrenField: string;
|
|
96
|
+
}
|
|
97
|
+
/** Options controlling how {@link diff} handles arrays (keyed `move` emission and tree structures). */
|
|
98
|
+
interface DiffOptions {
|
|
99
|
+
/** Path-scoped key extractors; matching arrays diff by identity (`move` + item field diff) via LIS instead of positional splice. */
|
|
100
|
+
readonly keyExtractors?: readonly {
|
|
101
|
+
readonly path: readonly PatternSeg[];
|
|
102
|
+
readonly extractor: KeyExtractor;
|
|
103
|
+
}[];
|
|
104
|
+
/** Nested tree specifications for hierarchical reorder/reparent diffs. */
|
|
105
|
+
readonly treeSpecs?: readonly TreeDiffSpec[];
|
|
106
|
+
}
|
|
107
|
+
/** O(K log K) Longest Increasing Subsequence membership mask. */
|
|
108
|
+
declare function lisMask(seq: readonly number[]): boolean[];
|
|
109
|
+
/**
|
|
110
|
+
* Compute minimal `[fromIdx, toIdx]` move pairs in `O(K log K)` transforming `[0..K)`
|
|
111
|
+
* into `targetSeq` (a permutation of `0..K`), keeping the LIS stationary.
|
|
112
|
+
*/
|
|
113
|
+
declare function lisMovePairs(targetSeq: readonly number[]): [number, number][];
|
|
114
|
+
/** Single-pass UTF-16 common prefix/suffix string diff avoiding surrogate splits. */
|
|
115
|
+
declare function diffStringAt(path: readonly PathSeg[], oldStr: string, newStr: string, ops: JsonOp[]): void;
|
|
116
|
+
/**
|
|
117
|
+
* Computes {@link JsonOp} operations transforming plain JSON `oldState` into `newState`.
|
|
118
|
+
* Emits `str_splice` on modified strings, `arr_splice` on unkeyed arrays, and LIS-minimal `move` + inner diffs
|
|
119
|
+
* when `options.keyExtractors` matches an array path.
|
|
120
|
+
* This function does not inspect a Loro DocSchema. Its string splices may be rejected by
|
|
121
|
+
* strict Loro writes targeting atomic string values; use scalar `set` operations there and
|
|
122
|
+
* reserve `str_splice` for LoroText containers. Key extractors only control array identity.
|
|
123
|
+
*/
|
|
124
|
+
declare function diff(oldState: JsonValue, newState: JsonValue, options?: DiffOptions): JsonOp[];
|
|
125
|
+
//#endregion
|
|
126
|
+
export { valuesEqual as A, assertValidUtf16Boundary as C, pathsEqual as D, numbersEqual as E, pathsOverlap as O, assertNoLoneSurrogates as S, isPlainObject as T, JsonOp as _, PatternSeg as a, JsonValue as b, diffStringAt as c, patternMatches as d, ApplyError as f, JsonObject as g, DecodeErrorKind as h, KeyExtractor as i, validateJsonValue as k, lisMask as l, DecodeError as m, ANY_SEG as n, TreeDiffSpec as o, ApplyErrorKind as p, DiffOptions as r, diff as s, ANY_REST_SEG as t, lisMovePairs as u, JsonPatch as v, assertValidUtf16Range as w, PathSeg as x, JsonPath as y };
|