UNPKG

5.09 kBTypeScriptView Raw
1import { Pointer } from './pointer';
2/**
3All diff* functions should return a list of operations, often empty.
4
5Each operation should be an object with two to four fields:
6* `op`: the name of the operation; one of "add", "remove", "replace", "move",
7 "copy", or "test".
8* `path`: a JSON pointer string
9* `from`: a JSON pointer string
10* `value`: a JSON value
11
12The different operations have different arguments.
13* "add": [`path`, `value`]
14* "remove": [`path`]
15* "replace": [`path`, `value`]
16* "move": [`from`, `path`]
17* "copy": [`from`, `path`]
18* "test": [`path`, `value`]
19
20Currently this only really differentiates between Arrays, Objects, and
21Everything Else, which is pretty much just what JSON substantially
22differentiates between.
23*/
24export interface AddOperation {
25 op: 'add';
26 path: string;
27 value: any;
28}
29export interface RemoveOperation {
30 op: 'remove';
31 path: string;
32}
33export interface ReplaceOperation {
34 op: 'replace';
35 path: string;
36 value: any;
37}
38export interface MoveOperation {
39 op: 'move';
40 from: string;
41 path: string;
42}
43export interface CopyOperation {
44 op: 'copy';
45 from: string;
46 path: string;
47}
48export interface TestOperation {
49 op: 'test';
50 path: string;
51 value: any;
52}
53export type Operation = AddOperation | RemoveOperation | ReplaceOperation | MoveOperation | CopyOperation | TestOperation;
54export declare function isDestructive({ op }: Operation): boolean;
55export type Diff = (input: any, output: any, ptr: Pointer) => Operation[];
56/**
57VoidableDiff exists to allow the user to provide a partial diff(...) function,
58falling back to the built-in diffAny(...) function if the user-provided function
59returns void.
60*/
61export type VoidableDiff = (input: any, output: any, ptr: Pointer) => Operation[] | void;
62/**
63List the keys in `minuend` that are not in `subtrahend`.
64
65A key is only considered if it is both 1) an own-property (o.hasOwnProperty(k))
66of the object, and 2) has a value that is not undefined. This is to match JSON
67semantics, where JSON object serialization drops keys with undefined values.
68
69@param minuend Object of interest
70@param subtrahend Object of comparison
71@returns Array of keys that are in `minuend` but not in `subtrahend`.
72*/
73export declare function subtract(minuend: {
74 [index: string]: any;
75}, subtrahend: {
76 [index: string]: any;
77}): string[];
78/**
79List the keys that shared by all `objects`.
80
81The semantics of what constitutes a "key" is described in {@link subtract}.
82
83@param objects Array of objects to compare
84@returns Array of keys that are in ("own-properties" of) every object in `objects`.
85*/
86export declare function intersection(objects: ArrayLike<{
87 [index: string]: any;
88}>): string[];
89/**
90Calculate the shortest sequence of operations to get from `input` to `output`,
91using a dynamic programming implementation of the Levenshtein distance algorithm.
92
93To get from the input ABC to the output AZ we could just delete all the input
94and say "insert A, insert Z" and be done with it. That's what we do if the
95input is empty. But we can be smarter.
96
97 output
98 A Z
99 - -
100 [0] 1 2
101input A | 1 [0] 1
102 B | 2 [1] 1
103 C | 3 2 [2]
104
1051) start at 0,0 (+0)
1062) keep A (+0)
1073) remove B (+1)
1084) replace C with Z (+1)
109
110If the `input` (source) is empty, they'll all be in the top row, resulting in an
111array of 'add' operations.
112If the `output` (target) is empty, everything will be in the left column,
113resulting in an array of 'remove' operations.
114
115@returns A list of add/remove/replace operations.
116*/
117export declare function diffArrays<T>(input: T[], output: T[], ptr: Pointer, diff?: Diff): Operation[];
118export declare function diffObjects(input: any, output: any, ptr: Pointer, diff?: Diff): Operation[];
119/**
120`diffAny()` returns an empty array if `input` and `output` are materially equal
121(i.e., would produce equivalent JSON); otherwise it produces an array of patches
122that would transform `input` into `output`.
123
124> Here, "equal" means that the value at the target location and the
125> value conveyed by "value" are of the same JSON type, and that they
126> are considered equal by the following rules for that type:
127> o strings: are considered equal if they contain the same number of
128> Unicode characters and their code points are byte-by-byte equal.
129> o numbers: are considered equal if their values are numerically
130> equal.
131> o arrays: are considered equal if they contain the same number of
132> values, and if each value can be considered equal to the value at
133> the corresponding position in the other array, using this list of
134> type-specific rules.
135> o objects: are considered equal if they contain the same number of
136> members, and if each member can be considered equal to a member in
137> the other object, by comparing their keys (as strings) and their
138> values (using this list of type-specific rules).
139> o literals (false, true, and null): are considered equal if they are
140> the same.
141*/
142export declare function diffAny(input: any, output: any, ptr: Pointer, diff?: Diff): Operation[];