Added maxIndent, noIndent, and propertyFilter stringification options. (#15)

* Added `maxIndent`, `noIndent`, and `propertyFilter` stringification options.
* Added `context` callback parameter for both replacers and revivers with `context.holder` and `context.stack` values.
* The above results in a breaking change from 5.x versions of JSON-Z, where the third parameter of a replacer/reviver callback _might_ be expected, _depending on context_, to be a holder object. This change results in a more consistent callback paradigm.

Author: kshetline

CHANGELOG.md

@@ -1,3 +1,9 @@
+### 6.0.0
+
+* Added `maxIndent`, `noIndent`, and `propertyFilter` stringification options.
+* Added `context` callback parameter for both replacers and revivers with `context.holder` and `context.stack` values.
+* The above results in a breaking change from 5.x versions of JSON-Z, where the third parameter of a replacer/reviver callback _might_ be expected, _depending on context_, to be a holder object. This change results in a more consistent callback paradigm.
+
 ### 5.2.0
 
 * Added `JSON.EXCISE` return value for replacers and revivers, allowing array items to be conveniently deleted along with their slot in an array.

GRAMMAR.md

@@ -107,7 +107,7 @@ explicit-octal = "0o", octal-digit, { [ "_" ], octal-digit } ;
 
 implied-octal = "0", octal-digit, { [ "_" ], octal-digit } ;
 
-decimal = "0", [ decimal-sequence, [ "_" ] ], { non-octal-sequence }-, [ "_" ], [ decimal-sequence ] | non-zero-digit, [ [ "_" ], decimal-sequence ] ;
+decimal = "0",  [ "_" ], [ decimal-sequence, [ "_" ] ], { non-octal-sequence }-, [ "_" ], [ decimal-sequence ] | non-zero-digit, [ [ "_" ], decimal-sequence ] ;
 
 decimal-sequence = decimal-digit, { [ "_" ], decimal-digit } ;
 
@@ -139,7 +139,7 @@ binary (* JSON-Z *) = "0b", { binary-digit}- ;
 
 octal (* JSON-Z *) = "0o", { octal-digit }- ;
 
-decimal = { decimal-digit }- ;
+decimal = 0 | non-zero-digit, { decimal-digit } ;
 
 hex (* JSON5 *) = "0x", { hex-digit }- ;
 
@@ -187,7 +187,7 @@ comment (* JSONC *) = block-comment | line-comment ;
 
 block-comment = "/*", ? any characters not containing the sequence "*/" ?, "*/";
 
-line-comment = "//", ? any characters other than \n, \r, \u2028, or \u2029 ?, ( "\n" | "\r\n" | "\r" | ? LINE SEPARATOR ? (* JSON5 *) | ? PARAGRAPH SEPARATOR ? (* JSON5 *) ) ;
+line-comment = "//", ? any characters other than \n, \r, \u2028, or \u2029 ?, ( "\n" | "\r\n" | "\r"  |? end of input ? | ? LINE SEPARATOR ? (* JSON5 *) | ? PARAGRAPH SEPARATOR ? (* JSON5 *) ) ;
 
 @endebnf
 ```

README.md

@@ -12,7 +12,7 @@ JSON-Z is a superset of [JSON] (and of [JSONC] and [JSON5] as well) which aims t
 
 JSON-Z is designed to increase flexibility when parsing while, by default, maintaining maximum compatibility with standard JSON when stringifying data (unless the user, through optional settings, eschews this compatibility).
 
-JSON-Z output, like JSON and JSON5, is also valid JavaScript (with two *optional* exceptions).
+JSON-Z output, like JSON and JSON5, is also valid JavaScript (with two *optional* exceptions). JSON-Z output can be valid JSON with the right optional setttings.
 
 Even when the additional grammar features of JSON-Z are not needed, this library's replacer functions, reviver functions, and formatting capabilities provide additional capabilities which can be useful when dealing JSON and JSON5.
 
@@ -210,14 +210,16 @@ This works very much like [`JSON.parse`](https://developer.mozilla.org/en-US/doc
 
 A JSON-Z reviver function is a callback that works much like the not-quite-yet-standard `JSON.parse` reviver function from this proposal: https://github.com/tc39/proposal-json-parse-with-source, a proposal which has already been widely implemented.
 
-The third argument passed to a JSON-Z reviver *might* be different from what a `JSON.parse` reviver receives, according to the above proposal. There is a forth argument that clarifies the difference.
+The `context` argument passed to a JSON-Z reviver differs in that in provides two extra values described below.
 
-> `reviver(key, value[, extra[, noContext]])`
+> `reviver(key, value[, context])`
 > 
 > - `key`: The object key (or array index) of the value being parsed. The `key` is an empty string if the `value` is the root value.
 > - `value`: A value as originally parsed, which should be returned by the reviver as-is if the reviver is not modifying the original value.
-> - `extra`: This is either a `context` object containing a `source` string, as described at the link above, or the holder of the value, i.e., the object or array, if any, which contains the given key/value pair.
-> - `noContext`: if `true`, `extra` is the `holder` object or array which contains the current key/value pair. Otherwise, `value` is a primitive value, and `extra` functions like the (nearly) standard `context` object, containing a `source` string, but also containing a `holder` value as well.
+> - `context`:
+>   - `context.source`: A `source` string, as described at the link above, providing the original text from which a primitive value has been parsed. No `source` is provided for object or array values.
+>   - `context.holder`: The object or array, if any, which contains a given key/value pair.
+>   - `context.stack`: An array containing the heirarchy of keys/array indices leading up to the given value. For example, when parsing `"[0, 1, {foo: 77}]"`, and a reviver receives the value `77`, `context.stack` will be `['2', 'foo']`.
 > 
 > Returns: Either the original `value`, `JSONZ.DELETE`, `JSONZ.EXCISE`, or a modified value (using `JSONZ.UNDEFINED` to change a value to `undefined`).
 
@@ -245,18 +247,21 @@ This works very much like [`JSON.stringify`](https://developer.mozilla.org/en-US
 - `value`: The value to convert to a JSON-Z string.
 - `replacer`: A function which alters the behavior of the stringification process, or an array of String and Number objects that serve as an allowlist for selecting/filtering the properties of the value object to be included in the JSON-Z string. If this value is null or not provided, all properties of the object are included in the resulting JSON-Z string.
 
-  When using the standard `JSON.stringify()`, a replacer function is called with two arguments: `key` and `value`. JSON-Z adds a third argument, `holder`. This value is already available to standard replacer `function`s as `this`, but `this` won't be bound the holder when using an anonymous (arrow) function as a replacer. The JSON-Z third argument (which can be ignored if not needed) provides alternative access to the holder value.<br><br>
-  > `replacer(key, value[, holder])`
+  When using the standard `JSON.stringify()`, a replacer function is called with two arguments: `key` and `value`. JSON-Z adds a third argument, `context`. The `context` argument here (which can be dropped if not needed) is similar to the JSON-Z reviver `context` argument, albeit with no `context.source` value.<br><br>
+  > `replacer(key, value[, context])`
 
   <br>Please note that if you want to shrink the size of a parent array when using a replacer to delete an array element, return `JSONZ.EXCISE`. If you return `JSONZ.DELETE` from the replacer function, the result will be a sparse parent array, retaining its original length and containing an empty slot.
 
 - `space`: A string or number used to insert whitespace into the output JSON-Z string for readability purposes. If this is a number, it indicates the number of space characters to use as whitespace; this number is capped at 10. Values less than 1 indicate that no space should be used. If `space` is a string, that string (or the first 10 characters of the string if it's longer) is used as white space. A single space adds white space without adding indentation. If this parameter is not provided (or is null), no whitespace is added. If indenting white space is used, trailing commas can optionally appear in objects and arrays.
 - `options`: This can either be an `OptionSet` value (see [below](#jsonzsetoptionsoptions-additionaloptions)), or an object with the following properties:
   - `extendedPrimitives`: If `true` (the default is `false`) this enables direct stringification of `Infinity`, `-Infinity`, `NaN`, and `undefined`. Otherwise, these values become `null`.
   - `extendedTypes`: If `JSONZ.ExtendedTypeMode.AS_FUNCTIONS` or `JSONZ.ExtendedTypeMode.AS_OBJECTS` (the default is `JSONZ.ExtendedTypeMode.OFF`), this enables special representation of additional data types, such as `_Date("2019-07-28T08:49:58.202Z")`, which can be parsed directly as a JavaScript `Date` object, or `{"_$_": "Date", "_$_value": "2019-07-28T08:49:58.202Z"}`, which can be automatically rendered as a `Date` object by a built-in replacer.
-  - `primitiveBigDecimal`: 🧪 If `true` (the default is `false`) this enables direct stringification of arbitrary-precision big decimals using the '`m`' suffix. Otherwise, big decimals must be provided as quoted strings or extended types. _(Note: The '`m`' suffix can't be parsed as current valid JavaScript, but it is potentially a future valid standard notation.)_
+  - `maxIndent`: If a non-zero integer, this option limits levels of indentation, deeper than which object content will be rendered on a single line.
+  - `oneLiners`: An list of property names, the values for which should be rendered on a single line. This argument can be provided as an array, a `Set`, or a comma-delimited string of property names.
+  - `primitiveBigDecimal`: 🧪 If `true` (the default is `false`) this enables direct stringification of arbitrary-precision big decimals using the '`m`' suffix. Otherwise, big decimals must be provided as quoted strings or extended types. _(Note: The '`m`' suffix cannot be parsed as valid JavaScript, making this notation a deviation from JavaScript parsing compatibility.)_
   - `primitiveBigInt`: If `true` (the default is `false`) this enables direct stringification of big integers using the '`n`' suffix. Otherwise, big integers are provided as quoted strings or extended types.
-  - `primitiveDecimal`: 🧪 If `true` (the default is `false`) this enables direct stringification of fixed-precision big decimals using the '`d`' suffix. Otherwise, big decimals must be provided as quoted strings or extended types. _(Note: The '`d`' suffix can't be parsed as current valid JavaScript, but it is potentially a future valid standard notation.)_
+  - `primitiveDecimal`: 🧪 If `true` (the default is `false`) this enables direct stringification of fixed-precision big decimals using the '`d`' suffix. Otherwise, big decimals must be provided as quoted strings or extended types. _(Note: The '`d`' suffix cannot be parsed as valid JavaScript, making this notation a deviation from JavaScript parsing compatibility.)_
+  - `propertyFilter`: This option provides functionality identical to providing an array of property names for the `replacer`/`options` argument &mdash; only the object properties listed here will be rendered. Using this option allows additional options to be used simultaneously.
   - `quote`: A string representing the quote character to use when serializing strings (single quote `'` or double quote `"`), or one of the following values:
     - `JSONZ.Quote.DOUBLE`: Always quote with double quotes (this is the default).
     - `JSONZ.Quote.SINGLE`: Always quote with single quotes.

docs/numbers.png

@@ -14,8 +14,8 @@ export const enum ExtendedTypeMode {
 }
 
 export type JsonZAllowedKeys = (string | number)[];
-
-export type JsonZReplacer = (holder: any, key: string, value: any) => any;
+export type ReplacerContext = { holder?: any, stack?: string[] };
+export type JsonZReplacer = (key: string, value: any, context?: ReplacerContext) => any;
 
 export const enum OptionSet {
   MAX_COMPATIBILITY,
@@ -26,6 +26,9 @@ export const enum OptionSet {
 export interface JsonZOptions {
   extendedPrimitives?: boolean,
   extendedTypes?: ExtendedTypeMode,
+  maxIndent?: number | '';
+  oneLiners?: string | string[] | Set<string>;
+  propertyFilter?: (string | number | String | Number)[];
   primitiveBigDecimal?: boolean;
   primitiveBigInt?: boolean;
   primitiveDecimal?: boolean;

docs/simplified-numbers.png

@@ -1,7 +1,6 @@
 import { JsonZParseOptions } from './options-manager';
 
-export type JsonZReviver = (key: string, value: any, extra?: (any | { source: string }),
-                            noContext?: boolean) => any;
-
+export type ReviverContext = { source?: string, holder?: any, stack?: string[] };
+export type JsonZReviver = (key: string, value: any, context?: ReviverContext) => any;
 export function parse<T = any>(text: string, options?: JsonZParseOptions): T;
 export function parse<T = any>(text: string, reviver?: JsonZReviver, options?: JsonZParseOptions): T;

lib/options-manager.d.ts

@@ -209,7 +209,7 @@ function parse(text, reviver, newOptions) {
   } while (token.type);
 
   if (reviver) {
-    const result = internalize({ '': root }, '', reviver);
+    const result = internalize({ '': root }, '');
 
     root = (result === util.DELETE || result === util.EXCISE ? undefined : result);
   }
@@ -1334,8 +1334,10 @@ function parse(text, reviver, newOptions) {
     throw invalidChar(read());
   }
 
-  function internalize(holder, name, reviver) {
-    let value = holder[name];
+  function internalize(holder, key, keyStack) {
+    let value = holder[key];
+
+    keyStack = keyStack ? (keyStack.push(key), keyStack) : [];
 
     if (value && typeof value === 'object' && !isBigNumber(value) && !(value instanceof ValueSourceWrapper)) {
       // noinspection JSUnresolvedReference
@@ -1344,40 +1346,48 @@ function parse(text, reviver, newOptions) {
       const isArray = Array.isArray(value);
       let lastLength = value.length;
 
-      for (const key of keys) {
-        const original = unwrap(value[key]);
-        const replacement = internalize(value, key, reviver);
+      for (const subkey of keys) {
+        const original = unwrap(value[subkey]);
+        const replacement = internalize(value, subkey, keyStack);
 
         if (replacement === util.EXCISE && isArray) {
-          value.splice(parseInt(key), 1);
+          value.splice(parseInt(subkey), 1);
           --lastLength;
         }
         else if ((replacement === undefined && original !== undefined) ||
                  replacement === util.DELETE || replacement === util.EXCISE) {
           if (!isArray || lastLength === value.length) {
-            delete value[key];
+            delete value[subkey];
           }
           else {
             lastLength = value.length;
           }
         }
         else {
-          setObjectProperty(value, key, replacement === util.UNDEFINED ? undefined : replacement);
+          setObjectProperty(value, subkey, replacement === util.UNDEFINED ? undefined : replacement);
         }
       }
     }
 
-    let extra = holder;
+    let result;
 
-    if (value instanceof ValueSourceWrapper) {
-      extra = {
-        holder,
-        source: value.source
-      };
-      value = value.value;
+    if (reviver.length < 3) {
+      result = reviver.call(holder, key, value);
     }
+    else {
+      const context = { holder, stack: keyStack };
+
+      if (value instanceof ValueSourceWrapper) {
+        context.source = value.source;
+        value = value.value;
+      }
+
+      result = reviver.call(holder, key, value, context);
+    }
+
+    keyStack.pop();
 
-    return reviver.call(holder, name, value, extra, extra === holder);
+    return result;
   }
 
   function peek() {
@@ -1686,7 +1696,7 @@ function parse(text, reviver, newOptions) {
       let revived;
 
       try {
-        const arg = reviver ? internalize({ '': current.arg }, '', reviver) : current.arg;
+        const arg = reviver ? internalize({ '': current.arg }, '') : current.arg;
 
         revived = optionsMgr.reviveTypeValue(current.name, arg);
       }

lib/parse.d.ts

@@ -16,9 +16,11 @@ try {
 }
 catch (err) {}
 
+const isArrayLike = obj => (obj instanceof Uint8Array) || (obj instanceof Uint8ClampedArray);
+
 const uint8ArrayHandler = {
   name: 'Uint8Array',
-  test: obj => (obj instanceof Uint8Array) || (obj instanceof Uint8ClampedArray),
+  test: isArrayLike,
   creator: fromBase64,
   serializer: toBase64
 };
@@ -76,5 +78,6 @@ module.exports = {
     }
   },
 
-  uint8ArrayHandler
+  uint8ArrayHandler,
+  isArrayLike
 };