forked from microsoft/rushstack
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathJsonFile.ts
More file actions
476 lines (416 loc) · 14.9 KB
/
Copy pathJsonFile.ts
File metadata and controls
476 lines (416 loc) · 14.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.
import * as os from 'os';
import * as jju from 'jju';
import { JsonSchema, IJsonSchemaErrorInfo, IJsonSchemaValidateOptions } from './JsonSchema';
import { Text, NewlineKind } from './Text';
import { FileSystem } from './FileSystem';
/**
* Represents a JSON-serializable object whose type has not been determined yet.
*
* @remarks
*
* This type is similar to `any`, except that it communicates that the object is serializable JSON.
*
* @public
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type JsonObject = any;
/**
* The Rush Stack lint rules discourage usage of `null`. However, JSON parsers always return JavaScript's
* `null` to keep the two syntaxes consistent. When creating interfaces that describe JSON structures,
* use `JsonNull` to avoid triggering the lint rule. Do not use `JsonNull` for any other purpose.
*
* @remarks
* If you are designing a new JSON file format, it's a good idea to avoid `null` entirely. In most cases
* there are better representations that convey more information about an item that is unknown, omitted, or disabled.
*
* To understand why `null` is deprecated, please see the `@rushstack/eslint-plugin` documentation here:
*
* {@link https://www.npmjs.com/package/@rushstack/eslint-plugin#rushstackno-null}
*
* @public
*/
// eslint-disable-next-line @rushstack/no-new-null
export type JsonNull = null;
/**
* Options for JsonFile.stringify()
*
* @public
*/
export interface IJsonFileStringifyOptions {
/**
* If provided, the specified newline type will be used instead of the default `\r\n`.
*/
newlineConversion?: NewlineKind;
/**
* If true, conforms to the standard behavior of JSON.stringify() when a property has the value `undefined`.
* Specifically, the key will be dropped from the emitted object.
*/
ignoreUndefinedValues?: boolean;
/**
* If true, then the "jju" library will be used to improve the text formatting.
* Note that this is slightly slower than the native JSON.stringify() implementation.
*/
prettyFormatting?: boolean;
/**
* If specified, this header will be prepended to the start of the file. The header must consist
* of lines prefixed by "//" characters.
* @remarks
* When used with {@link IJsonFileSaveOptions.updateExistingFile}
* or {@link JsonFile.updateString}, the header will ONLY be added for a newly created file.
*/
headerComment?: string;
}
/**
* Options for JsonFile.saveJsonFile()
*
* @public
*/
export interface IJsonFileSaveOptions extends IJsonFileStringifyOptions {
/**
* If there is an existing file, and the contents have not changed, then
* don't write anything; this preserves the old timestamp.
*/
onlyIfChanged?: boolean;
/**
* Creates the folder recursively using FileSystem.ensureFolder()
* Defaults to false.
*/
ensureFolderExists?: boolean;
/**
* If true, use the "jju" library to preserve the existing JSON formatting: The file will be loaded
* from the target filename, the new content will be merged in (preserving whitespace and comments),
* and then the file will be overwritten with the merged contents. If the target file does not exist,
* then the file is saved normally.
*/
updateExistingFile?: boolean;
}
const DEFAULT_ENCODING: 'utf8' = 'utf8';
/**
* Utilities for reading/writing JSON files.
* @public
*/
export class JsonFile {
/**
* @internal
*/
public static _formatPathForError: (path: string) => string = (path: string) => path;
/**
* Loads a JSON file.
*/
public static load(jsonFilename: string): JsonObject {
try {
const contents: string = FileSystem.readFile(jsonFilename);
return jju.parse(contents);
} catch (error) {
if (FileSystem.isNotExistError(error as Error)) {
throw error;
} else {
throw new Error(
`Error reading "${JsonFile._formatPathForError(jsonFilename)}":` +
os.EOL +
` ${(error as Error).message}`
);
}
}
}
/**
* An async version of {@link JsonFile.load}.
*/
public static async loadAsync(jsonFilename: string): Promise<JsonObject> {
try {
const contents: string = await FileSystem.readFileAsync(jsonFilename);
return jju.parse(contents);
} catch (error) {
if (FileSystem.isNotExistError(error as Error)) {
throw error;
} else {
throw new Error(
`Error reading "${JsonFile._formatPathForError(jsonFilename)}":` +
os.EOL +
` ${(error as Error).message}`
);
}
}
}
/**
* Parses a JSON file's contents.
*/
public static parseString(jsonContents: string): JsonObject {
return jju.parse(jsonContents);
}
/**
* Loads a JSON file and validate its schema.
*/
public static loadAndValidate(
jsonFilename: string,
jsonSchema: JsonSchema,
options?: IJsonSchemaValidateOptions
): JsonObject {
const jsonObject: JsonObject = JsonFile.load(jsonFilename);
jsonSchema.validateObject(jsonObject, jsonFilename, options);
return jsonObject;
}
/**
* An async version of {@link JsonFile.loadAndValidate}.
*/
public static async loadAndValidateAsync(
jsonFilename: string,
jsonSchema: JsonSchema,
options?: IJsonSchemaValidateOptions
): Promise<JsonObject> {
const jsonObject: JsonObject = await JsonFile.loadAsync(jsonFilename);
jsonSchema.validateObject(jsonObject, jsonFilename, options);
return jsonObject;
}
/**
* Loads a JSON file and validate its schema, reporting errors using a callback
* @remarks
* See JsonSchema.validateObjectWithCallback() for more info.
*/
public static loadAndValidateWithCallback(
jsonFilename: string,
jsonSchema: JsonSchema,
errorCallback: (errorInfo: IJsonSchemaErrorInfo) => void
): JsonObject {
const jsonObject: JsonObject = JsonFile.load(jsonFilename);
jsonSchema.validateObjectWithCallback(jsonObject, errorCallback);
return jsonObject;
}
/**
* An async version of {@link JsonFile.loadAndValidateWithCallback}.
*/
public static async loadAndValidateWithCallbackAsync(
jsonFilename: string,
jsonSchema: JsonSchema,
errorCallback: (errorInfo: IJsonSchemaErrorInfo) => void
): Promise<JsonObject> {
const jsonObject: JsonObject = await JsonFile.loadAsync(jsonFilename);
jsonSchema.validateObjectWithCallback(jsonObject, errorCallback);
return jsonObject;
}
/**
* Serializes the specified JSON object to a string buffer.
* @param jsonObject - the object to be serialized
* @param options - other settings that control serialization
* @returns a JSON string, with newlines, and indented with two spaces
*/
public static stringify(jsonObject: JsonObject, options?: IJsonFileStringifyOptions): string {
return JsonFile.updateString('', jsonObject, options);
}
/**
* Serializes the specified JSON object to a string buffer.
* @param jsonObject - the object to be serialized
* @param options - other settings that control serialization
* @returns a JSON string, with newlines, and indented with two spaces
*/
public static updateString(
previousJson: string,
newJsonObject: JsonObject,
options?: IJsonFileStringifyOptions
): string {
if (!options) {
options = {};
}
if (!options.ignoreUndefinedValues) {
// Standard handling of `undefined` in JSON stringification is to discard the key.
JsonFile.validateNoUndefinedMembers(newJsonObject);
}
let stringified: string;
if (previousJson !== '') {
// NOTE: We don't use mode=json here because comments aren't allowed by strict JSON
stringified = jju.update(previousJson, newJsonObject, {
mode: 'cjson',
indent: 2
});
} else if (options.prettyFormatting) {
stringified = jju.stringify(newJsonObject, {
mode: 'json',
indent: 2
});
if (options.headerComment !== undefined) {
stringified = JsonFile._formatJsonHeaderComment(options.headerComment) + stringified;
}
} else {
stringified = JSON.stringify(newJsonObject, undefined, 2);
if (options.headerComment !== undefined) {
stringified = JsonFile._formatJsonHeaderComment(options.headerComment) + stringified;
}
}
// Add the trailing newline
stringified = Text.ensureTrailingNewline(stringified);
if (options && options.newlineConversion) {
stringified = Text.convertTo(stringified, options.newlineConversion);
}
return stringified;
}
/**
* Saves the file to disk. Returns false if nothing was written due to options.onlyIfChanged.
* @param jsonObject - the object to be saved
* @param jsonFilename - the file path to write
* @param options - other settings that control how the file is saved
* @returns false if ISaveJsonFileOptions.onlyIfChanged didn't save anything; true otherwise
*/
public static save(jsonObject: JsonObject, jsonFilename: string, options?: IJsonFileSaveOptions): boolean {
if (!options) {
options = {};
}
// Do we need to read the previous file contents?
let oldBuffer: Buffer | undefined = undefined;
if (options.updateExistingFile || options.onlyIfChanged) {
try {
oldBuffer = FileSystem.readFileToBuffer(jsonFilename);
} catch (error) {
if (!FileSystem.isNotExistError(error as Error)) {
throw error;
}
}
}
let jsonToUpdate: string = '';
if (options.updateExistingFile && oldBuffer) {
jsonToUpdate = oldBuffer.toString(DEFAULT_ENCODING);
}
const newJson: string = JsonFile.updateString(jsonToUpdate, jsonObject, options);
const newBuffer: Buffer = Buffer.from(newJson, DEFAULT_ENCODING);
if (options.onlyIfChanged) {
// Has the file changed?
if (oldBuffer && Buffer.compare(newBuffer, oldBuffer) === 0) {
// Nothing has changed, so don't touch the file
return false;
}
}
FileSystem.writeFile(jsonFilename, newBuffer.toString(DEFAULT_ENCODING), {
ensureFolderExists: options.ensureFolderExists
});
// TEST CODE: Used to verify that onlyIfChanged isn't broken by a hidden transformation during saving.
/*
const oldBuffer2: Buffer = FileSystem.readFileToBuffer(jsonFilename);
if (Buffer.compare(buffer, oldBuffer2) !== 0) {
console.log('new:' + buffer.toString('hex'));
console.log('old:' + oldBuffer2.toString('hex'));
throw new Error('onlyIfChanged logic is broken');
}
*/
return true;
}
/**
* An async version of {@link JsonFile.save}.
*/
public static async saveAsync(
jsonObject: JsonObject,
jsonFilename: string,
options?: IJsonFileSaveOptions
): Promise<boolean> {
if (!options) {
options = {};
}
// Do we need to read the previous file contents?
let oldBuffer: Buffer | undefined = undefined;
if (options.updateExistingFile || options.onlyIfChanged) {
try {
oldBuffer = await FileSystem.readFileToBufferAsync(jsonFilename);
} catch (error) {
if (!FileSystem.isNotExistError(error as Error)) {
throw error;
}
}
}
let jsonToUpdate: string = '';
if (options.updateExistingFile && oldBuffer) {
jsonToUpdate = oldBuffer.toString(DEFAULT_ENCODING);
}
const newJson: string = JsonFile.updateString(jsonToUpdate, jsonObject, options);
const newBuffer: Buffer = Buffer.from(newJson, DEFAULT_ENCODING);
if (options.onlyIfChanged) {
// Has the file changed?
if (oldBuffer && Buffer.compare(newBuffer, oldBuffer) === 0) {
// Nothing has changed, so don't touch the file
return false;
}
}
await FileSystem.writeFileAsync(jsonFilename, newBuffer.toString(DEFAULT_ENCODING), {
ensureFolderExists: options.ensureFolderExists
});
// TEST CODE: Used to verify that onlyIfChanged isn't broken by a hidden transformation during saving.
/*
const oldBuffer2: Buffer = await FileSystem.readFileToBufferAsync(jsonFilename);
if (Buffer.compare(buffer, oldBuffer2) !== 0) {
console.log('new:' + buffer.toString('hex'));
console.log('old:' + oldBuffer2.toString('hex'));
throw new Error('onlyIfChanged logic is broken');
}
*/
return true;
}
/**
* Used to validate a data structure before writing. Reports an error if there
* are any undefined members.
*/
public static validateNoUndefinedMembers(jsonObject: JsonObject): void {
return JsonFile._validateNoUndefinedMembers(jsonObject, []);
}
// Private implementation of validateNoUndefinedMembers()
private static _validateNoUndefinedMembers(jsonObject: JsonObject, keyPath: string[]): void {
if (!jsonObject) {
return;
}
if (typeof jsonObject === 'object') {
for (const key of Object.keys(jsonObject)) {
keyPath.push(key);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const value: any = jsonObject[key];
if (value === undefined) {
const fullPath: string = JsonFile._formatKeyPath(keyPath);
throw new Error(`The value for ${fullPath} is "undefined" and cannot be serialized as JSON`);
}
JsonFile._validateNoUndefinedMembers(value, keyPath);
keyPath.pop();
}
}
}
// Given this input: ['items', '4', 'syntax', 'parameters', 'string "with" symbols", 'type']
// Return this string: items[4].syntax.parameters["string \"with\" symbols"].type
private static _formatKeyPath(keyPath: string[]): string {
let result: string = '';
for (const key of keyPath) {
if (/^[0-9]+$/.test(key)) {
// It's an integer, so display like this: parent[123]
result += `[${key}]`;
} else if (/^[a-z_][a-z_0-9]*$/i.test(key)) {
// It's an alphanumeric identifier, so display like this: parent.name
if (result) {
result += '.';
}
result += `${key}`;
} else {
// It's a freeform string, so display like this: parent["A path: \"C:\\file\""]
// Convert this: A path: "C:\file"
// To this: A path: \"C:\\file\"
const escapedKey: string = key
.replace(/[\\]/g, '\\\\') // escape backslashes
.replace(/["]/g, '\\'); // escape quotes
result += `["${escapedKey}"]`;
}
}
return result;
}
private static _formatJsonHeaderComment(headerComment: string): string {
if (headerComment === '') {
return '';
}
const lines: string[] = headerComment.split('\n');
const result: string[] = [];
for (const line of lines) {
if (!/^\s*$/.test(line) && !/^\s*\/\//.test(line)) {
throw new Error(
'The headerComment lines must be blank or start with the "//" prefix.\n' +
'Invalid line' +
JSON.stringify(line)
);
}
result.push(Text.replaceAll(line, '\r', ''));
}
return lines.join('\n') + '\n';
}
}