@rushstack/node-core-library - npm Package Compare versions

Comparing version 3.51.0 to 3.51.1

lib/index.d.ts

@@ -18,3 +18,3 @@ /**
 export { InternalError } from './InternalError';
-export { JsonObject, JsonFile, JsonNull, IJsonFileSaveOptions, IJsonFileStringifyOptions } from './JsonFile';
+export { JsonObject, JsonNull, JsonSyntax, IJsonFileParseOptions, IJsonFileLoadAndValidateOptions, IJsonFileStringifyOptions, IJsonFileSaveOptions, JsonFile } from './JsonFile';
 export { JsonSchema, IJsonSchemaErrorInfo, IJsonSchemaValidateOptions, IJsonSchemaFromFileOptions } from './JsonSchema';
@@ -21,0 +21,0 @@ export { LockFile } from './LockFile';

lib/index.js

@@ -5,3 +5,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypeUuid = exports.StringBufferTerminalProvider = exports.ConsoleTerminalProvider = exports.TerminalProviderSeverity = exports.TextAttribute = exports.ColorValue = exports.Colors = exports.Terminal = exports.SubprocessTerminator = exports.StringBuilder = exports.LegacyAdapters = exports.FileWriter = exports.FileSystem = exports.AlreadyExistsBehavior = exports.Sort = exports.NewlineKind = exports.Text = exports.Encoding = exports.Path = exports.PackageNameParser = exports.PackageName = exports.PackageJsonLookup = exports.ProtectableMap = exports.PosixModeBits = exports.MapExtensions = exports.LockFile = exports.JsonSchema = exports.JsonFile = exports.InternalError = exports.Import = exports.FileError = exports.Executable = exports.EnvironmentMap = exports.Enum = exports.FolderConstants = exports.FileConstants = exports.Async = exports.AnsiEscape = exports.AlreadyReportedError = void 0;
+exports.TypeUuid = exports.StringBufferTerminalProvider = exports.ConsoleTerminalProvider = exports.TerminalProviderSeverity = exports.TextAttribute = exports.ColorValue = exports.Colors = exports.Terminal = exports.SubprocessTerminator = exports.StringBuilder = exports.LegacyAdapters = exports.FileWriter = exports.FileSystem = exports.AlreadyExistsBehavior = exports.Sort = exports.NewlineKind = exports.Text = exports.Encoding = exports.Path = exports.PackageNameParser = exports.PackageName = exports.PackageJsonLookup = exports.ProtectableMap = exports.PosixModeBits = exports.MapExtensions = exports.LockFile = exports.JsonSchema = exports.JsonFile = exports.JsonSyntax = exports.InternalError = exports.Import = exports.FileError = exports.Executable = exports.EnvironmentMap = exports.Enum = exports.FolderConstants = exports.FileConstants = exports.Async = exports.AnsiEscape = exports.AlreadyReportedError = void 0;
 /**
@@ -34,2 +34,3 @@ * Core libraries that every NodeJS toolchain project should use.
 var JsonFile_1 = require("./JsonFile");
+Object.defineProperty(exports, "JsonSyntax", { enumerable: true, get: function () { return JsonFile_1.JsonSyntax; } });
 Object.defineProperty(exports, "JsonFile", { enumerable: true, get: function () { return JsonFile_1.JsonFile; } });
@@ -36,0 +37,0 @@ var JsonSchema_1 = require("./JsonSchema");

lib/JsonFile.d.ts

@@ -30,6 +30,87 @@ import { JsonSchema, IJsonSchemaErrorInfo, IJsonSchemaValidateOptions } from './JsonSchema';
 /**
- * Options for JsonFile.stringify()
+ * Specifies the variant of JSON syntax to be used.
  *
  * @public
  */
+export declare enum JsonSyntax {
+    /**
+     * Specifies the exact RFC 8259 format as implemented by the `JSON.parse()` system API.
+     * This format was designed for machine generated inputs such as an HTTP payload.
+     * It is not a recommend choice for human-authored files, because it does not support
+     * code comments.
+     *
+     * @remarks
+     *
+     * A well-known quote from Douglas Crockford, the inventor of JSON:
+     *
+     * "I removed comments from JSON because I saw people were using them to hold parsing directives,
+     * a practice which would have destroyed interoperability.  I know that the lack of comments makes
+     * some people sad, but it shouldn't.  Suppose you are using JSON to keep configuration files,
+     * which you would like to annotate.  Go ahead and insert all the comments you like.
+     * Then pipe it through JSMin before handing it to your JSON parser."
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc8259 | RFC 8259}
+     */
+    Strict = "strict",
+    /**
+     * `JsonSyntax.JsonWithComments` is the recommended format for human-authored config files.
+     * It is a minimal extension to `JsonSyntax.Strict` adding support for code comments
+     * using `//` and `/*`.
+     *
+     * @remarks
+     *
+     * VS Code calls this format `jsonc`, but it should not be confused with unrelated file formats
+     * and libraries that also use the name "JSONC".
+     *
+     * To fix VS Code syntax highlighting, add this setting:
+     * `"files.associations": { "*.json": "jsonc" }`
+     *
+     * To fix GitHub syntax highlighting, add this to your `.gitattributes`:
+     * `*.json linguist-language=JSON-with-Comments`
+     */
+    JsonWithComments = "jsonWithComments",
+    /**
+     * JSON5 is a project that proposes a JSON-like format supplemented with ECMAScript 5.1
+     * notations for objects, numbers, comments, and more.
+     *
+     * @remarks
+     * Files using this format should use the `.json5` file extension instead of `.json`.
+     *
+     * JSON5 has substantial differences from JSON: object keys may be unquoted, trailing commas
+     * are allowed, and strings may span multiple lines.  Whereas `JsonSyntax.JsonWithComments` can
+     * be cheaply converted to standard JSON by stripping comments, parsing JSON5 requires a
+     * nontrivial algorithm that may not be easily available in some contexts or programming languages.
+     *
+     * @see {@link https://json5.org/ | JSON5 project website}
+     */
+    Json5 = "json5"
+}
+/**
+ * Options for {@link JsonFile.parseString}, {@link JsonFile.load}, and {@link JsonFile.loadAsync}.
+ *
+ * @public
+ */
+export interface IJsonFileParseOptions {
+    /**
+     * Specifies the variant of JSON syntax to be used.
+     *
+     * @defaultValue
+     * `JsonSyntax.Json5`
+     *
+     * NOTE: This default will be changed to `JsonSyntax.JsonWithComments` in a future release.
+     */
+    jsonSyntax?: JsonSyntax;
+}
+/**
+ * Options for {@link JsonFile.loadAndValidate} and {@link JsonFile.loadAndValidateAsync}
+ *
+ * @public
+ */
+export interface IJsonFileLoadAndValidateOptions extends IJsonFileParseOptions, IJsonSchemaValidateOptions {
+}
+/**
+ * Options for {@link JsonFile.stringify}
+ *
+ * @public
+ */
 export interface IJsonFileStringifyOptions {
@@ -41,4 +122,15 @@ /**
     /**
-     * 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.
+     * By default, `JsonFile.stringify()` validates that the object does not contain any
+     * keys whose value is `undefined`.  To disable this validation, set `ignoreUndefinedValues=true`
+     * which causes such keys to be silently discarded, consistent with the system `JSON.stringify()`.
+     *
+     * @remarks
+     *
+     * The JSON file format can represent `null` values ({@link JsonNull}) but not `undefined` values.
+     * In ECMAScript code however, we generally avoid `null` and always represent empty states
+     * as `undefined`, because it is the default value of missing/uninitialized variables.
+     * (In practice, distinguishing "null" versus "uninitialized" has more drawbacks than benefits.)
+     * This poses a problem when serializing ECMAScript objects that contain `undefined` members.
+     * As a safeguard, `JsonFile` will report an error if any `undefined` values are encountered
+     * during serialization.  Set `ignoreUndefinedValues=true` to disable this safeguard.
      */
@@ -61,3 +153,3 @@ ignoreUndefinedValues?: boolean;
 /**
- * Options for JsonFile.saveJsonFile()
+ * Options for {@link JsonFile.save} and {@link JsonFile.saveAsync}.
  *
@@ -97,19 +189,19 @@ * @public
      */
-    static load(jsonFilename: string): JsonObject;
+    static load(jsonFilename: string, options?: IJsonFileParseOptions): JsonObject;
     /**
      * An async version of {@link JsonFile.load}.
      */
-    static loadAsync(jsonFilename: string): Promise<JsonObject>;
+    static loadAsync(jsonFilename: string, options?: IJsonFileParseOptions): Promise<JsonObject>;
     /**
      * Parses a JSON file's contents.
      */
-    static parseString(jsonContents: string): JsonObject;
+    static parseString(jsonContents: string, options?: IJsonFileParseOptions): JsonObject;
     /**
      * Loads a JSON file and validate its schema.
      */
-    static loadAndValidate(jsonFilename: string, jsonSchema: JsonSchema, options?: IJsonSchemaValidateOptions): JsonObject;
+    static loadAndValidate(jsonFilename: string, jsonSchema: JsonSchema, options?: IJsonFileLoadAndValidateOptions): JsonObject;
     /**
      * An async version of {@link JsonFile.loadAndValidate}.
      */
-    static loadAndValidateAsync(jsonFilename: string, jsonSchema: JsonSchema, options?: IJsonSchemaValidateOptions): Promise<JsonObject>;
+    static loadAndValidateAsync(jsonFilename: string, jsonSchema: JsonSchema, options?: IJsonFileLoadAndValidateOptions): Promise<JsonObject>;
     /**
@@ -120,7 +212,7 @@ * Loads a JSON file and validate its schema, reporting errors using a callback
      */
-    static loadAndValidateWithCallback(jsonFilename: string, jsonSchema: JsonSchema, errorCallback: (errorInfo: IJsonSchemaErrorInfo) => void): JsonObject;
+    static loadAndValidateWithCallback(jsonFilename: string, jsonSchema: JsonSchema, errorCallback: (errorInfo: IJsonSchemaErrorInfo) => void, options?: IJsonFileLoadAndValidateOptions): JsonObject;
     /**
      * An async version of {@link JsonFile.loadAndValidateWithCallback}.
      */
-    static loadAndValidateWithCallbackAsync(jsonFilename: string, jsonSchema: JsonSchema, errorCallback: (errorInfo: IJsonSchemaErrorInfo) => void): Promise<JsonObject>;
+    static loadAndValidateWithCallbackAsync(jsonFilename: string, jsonSchema: JsonSchema, errorCallback: (errorInfo: IJsonSchemaErrorInfo) => void, options?: IJsonFileLoadAndValidateOptions): Promise<JsonObject>;
     /**
@@ -160,3 +252,4 @@ * Serializes the specified JSON object to a string buffer.
     private static _formatJsonHeaderComment;
+    private static _buildJjuParseOptions;
 }
 //# sourceMappingURL=JsonFile.d.ts.map

lib/JsonFile.js

@@ -28,3 +28,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.JsonFile = void 0;
+exports.JsonFile = exports.JsonSyntax = void 0;
 const os = __importStar(require("os"));
@@ -34,2 +34,61 @@ const jju = __importStar(require("jju"));
 const FileSystem_1 = require("./FileSystem");
+/**
+ * Specifies the variant of JSON syntax to be used.
+ *
+ * @public
+ */
+var JsonSyntax;
+(function (JsonSyntax) {
+    /**
+     * Specifies the exact RFC 8259 format as implemented by the `JSON.parse()` system API.
+     * This format was designed for machine generated inputs such as an HTTP payload.
+     * It is not a recommend choice for human-authored files, because it does not support
+     * code comments.
+     *
+     * @remarks
+     *
+     * A well-known quote from Douglas Crockford, the inventor of JSON:
+     *
+     * "I removed comments from JSON because I saw people were using them to hold parsing directives,
+     * a practice which would have destroyed interoperability.  I know that the lack of comments makes
+     * some people sad, but it shouldn't.  Suppose you are using JSON to keep configuration files,
+     * which you would like to annotate.  Go ahead and insert all the comments you like.
+     * Then pipe it through JSMin before handing it to your JSON parser."
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc8259 | RFC 8259}
+     */
+    JsonSyntax["Strict"] = "strict";
+    /**
+     * `JsonSyntax.JsonWithComments` is the recommended format for human-authored config files.
+     * It is a minimal extension to `JsonSyntax.Strict` adding support for code comments
+     * using `//` and `/*`.
+     *
+     * @remarks
+     *
+     * VS Code calls this format `jsonc`, but it should not be confused with unrelated file formats
+     * and libraries that also use the name "JSONC".
+     *
+     * To fix VS Code syntax highlighting, add this setting:
+     * `"files.associations": { "*.json": "jsonc" }`
+     *
+     * To fix GitHub syntax highlighting, add this to your `.gitattributes`:
+     * `*.json linguist-language=JSON-with-Comments`
+     */
+    JsonSyntax["JsonWithComments"] = "jsonWithComments";
+    /**
+     * JSON5 is a project that proposes a JSON-like format supplemented with ECMAScript 5.1
+     * notations for objects, numbers, comments, and more.
+     *
+     * @remarks
+     * Files using this format should use the `.json5` file extension instead of `.json`.
+     *
+     * JSON5 has substantial differences from JSON: object keys may be unquoted, trailing commas
+     * are allowed, and strings may span multiple lines.  Whereas `JsonSyntax.JsonWithComments` can
+     * be cheaply converted to standard JSON by stripping comments, parsing JSON5 requires a
+     * nontrivial algorithm that may not be easily available in some contexts or programming languages.
+     *
+     * @see {@link https://json5.org/ | JSON5 project website}
+     */
+    JsonSyntax["Json5"] = "json5";
+})(JsonSyntax = exports.JsonSyntax || (exports.JsonSyntax = {}));
 const DEFAULT_ENCODING = 'utf8';
@@ -44,6 +103,7 @@ /**
      */
-    static load(jsonFilename) {
+    static load(jsonFilename, options) {
         try {
             const contents = FileSystem_1.FileSystem.readFile(jsonFilename);
-            return jju.parse(contents);
+            const parseOptions = JsonFile._buildJjuParseOptions(options);
+            return jju.parse(contents, parseOptions);
         }
@@ -64,6 +124,7 @@ catch (error) {
      */
-    static async loadAsync(jsonFilename) {
+    static async loadAsync(jsonFilename, options) {
         try {
             const contents = await FileSystem_1.FileSystem.readFileAsync(jsonFilename);
-            return jju.parse(contents);
+            const parseOptions = JsonFile._buildJjuParseOptions(options);
+            return jju.parse(contents, parseOptions);
         }
@@ -84,4 +145,5 @@ catch (error) {
      */
-    static parseString(jsonContents) {
-        return jju.parse(jsonContents);
+    static parseString(jsonContents, options) {
+        const parseOptions = JsonFile._buildJjuParseOptions(options);
+        return jju.parse(jsonContents, parseOptions);
     }
@@ -92,3 +154,3 @@ /**
     static loadAndValidate(jsonFilename, jsonSchema, options) {
-        const jsonObject = JsonFile.load(jsonFilename);
+        const jsonObject = JsonFile.load(jsonFilename, options);
         jsonSchema.validateObject(jsonObject, jsonFilename, options);
@@ -101,3 +163,3 @@ return jsonObject;
     static async loadAndValidateAsync(jsonFilename, jsonSchema, options) {
-        const jsonObject = await JsonFile.loadAsync(jsonFilename);
+        const jsonObject = await JsonFile.loadAsync(jsonFilename, options);
         jsonSchema.validateObject(jsonObject, jsonFilename, options);
@@ -111,4 +173,4 @@ return jsonObject;
      */
-    static loadAndValidateWithCallback(jsonFilename, jsonSchema, errorCallback) {
-        const jsonObject = JsonFile.load(jsonFilename);
+    static loadAndValidateWithCallback(jsonFilename, jsonSchema, errorCallback, options) {
+        const jsonObject = JsonFile.load(jsonFilename, options);
         jsonSchema.validateObjectWithCallback(jsonObject, errorCallback);
@@ -120,4 +182,4 @@ return jsonObject;
      */
-    static async loadAndValidateWithCallbackAsync(jsonFilename, jsonSchema, errorCallback) {
-        const jsonObject = await JsonFile.loadAsync(jsonFilename);
+    static async loadAndValidateWithCallbackAsync(jsonFilename, jsonSchema, errorCallback, options) {
+        const jsonObject = await JsonFile.loadAsync(jsonFilename, options);
         jsonSchema.validateObjectWithCallback(jsonObject, errorCallback);
@@ -347,2 +409,21 @@ return jsonObject;
     }
+    static _buildJjuParseOptions(options) {
+        if (!options) {
+            options = {};
+        }
+        const parseOptions = {};
+        switch (options.jsonSyntax) {
+            case JsonSyntax.Strict:
+                parseOptions.mode = 'json';
+                break;
+            case JsonSyntax.JsonWithComments:
+                parseOptions.mode = 'cjson';
+                break;
+            case JsonSyntax.Json5:
+            default:
+                parseOptions.mode = 'json5';
+                break;
+        }
+        return parseOptions;
+    }
 }
@@ -349,0 +430,0 @@ exports.JsonFile = JsonFile;

package.json

 {
   "name": "@rushstack/node-core-library",
-  "version": "3.51.0",
+  "version": "3.51.1",
   "description": "Core libraries that every NodeJS toolchain project should use",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1031727

increased by1.91%

Lines of code

13547

increased by2.02%

No dependency changes