UNPKG

12.1 kBTypeScriptView Raw
1// Type definitions for diff 5.0
2// Project: https://github.com/kpdecker/jsdiff
3// Definitions by: vvakame <https://github.com/vvakame>
4// szdc <https://github.com/szdc>
5// moc-yuto <https://github.com/moc-yuto>
6// BendingBender <https://github.com/BendingBender>
7// Piotr Błażejewicz <https://github.com/peterblazejewicz>
8// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
9
10export as namespace Diff;
11
12export type Callback = (err: undefined, value?: Change[]) => void;
13
14export interface CallbackOptions {
15 /**
16 * Callback to call with the result instead of returning the result directly.
17 */
18 callback: Callback;
19}
20
21export interface BaseOptions {
22 /**
23 * `true` to ignore casing difference.
24 * @default false
25 */
26 ignoreCase?: boolean;
27}
28
29export interface WordsOptions extends BaseOptions {
30 /**
31 * `true` to ignore leading and trailing whitespace. This is the same as `diffWords()`.
32 */
33 ignoreWhitespace?: boolean;
34}
35
36export interface LinesOptions extends BaseOptions {
37 /**
38 * `true` to ignore leading and trailing whitespace. This is the same as `diffTrimmedLines()`.
39 */
40 ignoreWhitespace?: boolean;
41
42 /**
43 * `true` to treat newline characters as separate tokens. This allows for changes to the newline structure
44 * to occur independently of the line content and to be treated as such. In general this is the more
45 * human friendly form of `diffLines()` and `diffLines()` is better suited for patches and other computer
46 * friendly output.
47 */
48 newlineIsToken?: boolean;
49}
50
51export interface JsonOptions extends LinesOptions {
52 /**
53 * Replacer used to stringify the properties of the passed objects.
54 */
55 stringifyReplacer?: (key: string, value: any) => any;
56
57 /**
58 * The value to use when `undefined` values in the passed objects are encountered during stringification.
59 * Will only be used if `stringifyReplacer` option wasn't specified.
60 * @default undefined
61 */
62 undefinedReplacement?: any;
63}
64
65export interface ArrayOptions<TLeft, TRight> extends BaseOptions {
66 /**
67 * Comparator for custom equality checks.
68 */
69 comparator?: (left: TLeft, right: TRight) => boolean;
70}
71
72export interface PatchOptions extends LinesOptions {
73 /**
74 * Describes how many lines of context should be included.
75 * @default 4
76 */
77 context?: number;
78}
79
80export interface ApplyPatchOptions {
81 /**
82 * Number of lines that are allowed to differ before rejecting a patch.
83 * @default 0
84 */
85 fuzzFactor?: number;
86
87 /**
88 * Callback used to compare to given lines to determine if they should be considered equal when patching.
89 * Should return `false` if the lines should be rejected.
90 *
91 * @default strict equality
92 */
93 compareLine?: (
94 lineNumber: number,
95 line: string,
96 operation: '-' | ' ',
97 patchContent: string
98 ) => boolean;
99}
100
101export interface ApplyPatchesOptions extends ApplyPatchOptions {
102 loadFile(index: ParsedDiff, callback: (err: any, data: string) => void): void;
103 patched(index: ParsedDiff, content: string, callback: (err: any) => void): void;
104 complete(err: any): void;
105}
106
107export interface Change {
108 count?: number;
109 /**
110 * Text content.
111 */
112 value: string;
113 /**
114 * `true` if the value was inserted into the new string.
115 */
116 added?: boolean;
117 /**
118 * `true` if the value was removed from the old string.
119 */
120 removed?: boolean;
121}
122
123export interface ArrayChange<T> {
124 value: T[];
125 count?: number;
126 added?: boolean;
127 removed?: boolean;
128}
129
130export interface ParsedDiff {
131 index?: string;
132 oldFileName?: string;
133 newFileName?: string;
134 oldHeader?: string;
135 newHeader?: string;
136 hunks: Hunk[];
137}
138
139export interface Hunk {
140 oldStart: number;
141 oldLines: number;
142 newStart: number;
143 newLines: number;
144 lines: string[];
145 linedelimiters: string[];
146}
147
148export interface BestPath {
149 newPos: number;
150 componenets: Change[];
151}
152
153export class Diff {
154 diff(
155 oldString: string,
156 newString: string,
157 options?: Callback | (ArrayOptions<any, any> & Partial<CallbackOptions>)
158 ): Change[];
159
160 pushComponent(components: Change[], added: boolean, removed: boolean): void;
161
162 extractCommon(
163 basePath: BestPath,
164 newString: string,
165 oldString: string,
166 diagonalPath: number
167 ): number;
168
169 equals(left: any, right: any): boolean;
170
171 removeEmpty(array: any[]): any[];
172
173 castInput(value: any): any;
174
175 join(chars: string[]): string;
176
177 tokenize(value: string): any; // return types are string or string[]
178}
179
180/**
181 * Diffs two blocks of text, comparing character by character.
182 *
183 * @returns A list of change objects.
184 */
185export function diffChars(oldStr: string, newStr: string, options?: BaseOptions): Change[];
186export function diffChars(
187 oldStr: string,
188 newStr: string,
189 options: Callback | (BaseOptions & CallbackOptions)
190): void;
191
192/**
193 * Diffs two blocks of text, comparing word by word, ignoring whitespace.
194 *
195 * @returns A list of change objects.
196 */
197export function diffWords(oldStr: string, newStr: string, options?: WordsOptions): Change[];
198export function diffWords(
199 oldStr: string,
200 newStr: string,
201 options: Callback | (WordsOptions & CallbackOptions)
202): void;
203
204/**
205 * Diffs two blocks of text, comparing word by word, treating whitespace as significant.
206 *
207 * @returns A list of change objects.
208 */
209export function diffWordsWithSpace(
210 oldStr: string,
211 newStr: string,
212 options?: WordsOptions
213): Change[];
214export function diffWordsWithSpace(
215 oldStr: string,
216 newStr: string,
217 options: Callback | (WordsOptions & CallbackOptions)
218): void;
219
220/**
221 * Diffs two blocks of text, comparing line by line.
222 *
223 * @returns A list of change objects.
224 */
225export function diffLines(oldStr: string, newStr: string, options?: LinesOptions): Change[];
226export function diffLines(
227 oldStr: string,
228 newStr: string,
229 options: Callback | (LinesOptions & CallbackOptions)
230): void;
231
232/**
233 * Diffs two blocks of text, comparing line by line, ignoring leading and trailing whitespace.
234 *
235 * @returns A list of change objects.
236 */
237export function diffTrimmedLines(oldStr: string, newStr: string, options?: LinesOptions): Change[];
238export function diffTrimmedLines(
239 oldStr: string,
240 newStr: string,
241 options: Callback | (LinesOptions & CallbackOptions)
242): void;
243
244/**
245 * Diffs two blocks of text, comparing sentence by sentence.
246 *
247 * @returns A list of change objects.
248 */
249export function diffSentences(oldStr: string, newStr: string, options?: BaseOptions): Change[];
250export function diffSentences(
251 oldStr: string,
252 newStr: string,
253 options: Callback | (BaseOptions & CallbackOptions)
254): void;
255
256/**
257 * Diffs two blocks of text, comparing CSS tokens.
258 *
259 * @returns A list of change objects.
260 */
261export function diffCss(oldStr: string, newStr: string, options?: BaseOptions): Change[];
262export function diffCss(
263 oldStr: string,
264 newStr: string,
265 options: Callback | (BaseOptions & CallbackOptions)
266): void;
267
268/**
269 * Diffs two JSON objects, comparing the fields defined on each. The order of fields, etc does not matter
270 * in this comparison.
271 *
272 * @returns A list of change objects.
273 */
274export function diffJson(
275 oldObj: string | object,
276 newObj: string | object,
277 options?: JsonOptions
278): Change[];
279export function diffJson(
280 oldObj: string | object,
281 newObj: string | object,
282 options: Callback | (JsonOptions & CallbackOptions)
283): void;
284
285/**
286 * Diffs two arrays, comparing each item for strict equality (`===`).
287 *
288 * @returns A list of change objects.
289 */
290export function diffArrays<TOld, TNew>(
291 oldArr: TOld[],
292 newArr: TNew[],
293 options?: ArrayOptions<TOld, TNew>
294): Array<ArrayChange<TOld | TNew>>;
295
296/**
297 * Creates a unified diff patch.
298 *
299 * @param oldFileName String to be output in the filename section of the patch for the removals.
300 * @param newFileName String to be output in the filename section of the patch for the additions.
301 * @param oldStr Original string value.
302 * @param newStr New string value.
303 * @param oldHeader Additional information to include in the old file header.
304 * @param newHeader Additional information to include in the new file header.
305 */
306export function createTwoFilesPatch(
307 oldFileName: string,
308 newFileName: string,
309 oldStr: string,
310 newStr: string,
311 oldHeader?: string,
312 newHeader?: string,
313 options?: PatchOptions
314): string;
315
316/**
317 * Creates a unified diff patch.
318 * Just like `createTwoFilesPatch()`, but with `oldFileName` being equal to `newFileName`.
319 *
320 * @param fileName String to be output in the filename section.
321 * @param oldStr Original string value.
322 * @param newStr New string value.
323 * @param oldHeader Additional information to include in the old file header.
324 * @param newHeader Additional information to include in the new file header.
325 */
326export function createPatch(
327 fileName: string,
328 oldStr: string,
329 newStr: string,
330 oldHeader?: string,
331 newHeader?: string,
332 options?: PatchOptions
333): string;
334
335/**
336 * This method is similar to `createTwoFilesPatch()`, but returns a data structure suitable for further processing.
337 * Parameters are the same as `createTwoFilesPatch()`.
338 *
339 * @param oldFileName String to be output in the `oldFileName` hunk property.
340 * @param newFileName String to be output in the `newFileName` hunk property.
341 * @param oldStr Original string value.
342 * @param newStr New string value.
343 * @param oldHeader Additional information to include in the `oldHeader` hunk property.
344 * @param newHeader Additional information to include in the `newHeader` hunk property.
345 * @returns An object with an array of hunk objects.
346 */
347export function structuredPatch(
348 oldFileName: string,
349 newFileName: string,
350 oldStr: string,
351 newStr: string,
352 oldHeader?: string,
353 newHeader?: string,
354 options?: PatchOptions
355): ParsedDiff;
356
357/**
358 * Applies a unified diff patch.
359 *
360 * @param patch May be a string diff or the output from the `parsePatch()` or `structuredPatch()` methods.
361 * @returns A string containing new version of provided data.
362 */
363export function applyPatch(
364 source: string,
365 patch: string | ParsedDiff | [ParsedDiff],
366 options?: ApplyPatchOptions
367): string;
368
369/**
370 * Applies one or more patches.
371 * This method will iterate over the contents of the patch and apply to data provided through callbacks.
372 *
373 * The general flow for each patch index is:
374 *
375 * 1. `options.loadFile(index, callback)` is called. The caller should then load the contents of the file
376 * and then pass that to the `callback(err, data)` callback. Passing an `err` will terminate further patch execution.
377 * 2. `options.patched(index, content, callback)` is called once the patch has been applied. `content` will be
378 * the return value from `applyPatch()`. When it's ready, the caller should call `callback(err)` callback.
379 * Passing an `err` will terminate further patch execution.
380 * 3. Once all patches have been applied or an error occurs, the `options.complete(err)` callback is made.
381 */
382export function applyPatches(patch: string | ParsedDiff[], options: ApplyPatchesOptions): void;
383
384/**
385 * Parses a patch into structured data.
386 *
387 * @returns A JSON object representation of the a patch, suitable for use with the `applyPatch()` method.
388 */
389export function parsePatch(diffStr: string, options?: { strict?: boolean }): ParsedDiff[];
390
391/**
392 * Converts a list of changes to a serialized XML format.
393 */
394export function convertChangesToXML(changes: Change[]): string;
395
396/**
397 * Converts a list of changes to [DMP](http://code.google.com/p/google-diff-match-patch/wiki/API) format.
398 */
399export function convertChangesToDMP(changes: Change[]): Array<[1 | 0 | -1, string]>;
400
401export function merge(mine: string, theirs: string, base: string): ParsedDiff;
402
403export function canonicalize(obj: any, stack: any[], replacementStack: any[]): any;