Added a new replacer function feature, JSONZ.LITERALLY_AS. (#1)

Author: kshetline

CHANGELOG.md

@@ -1,3 +1,7 @@
+### 4.1.0
+
+* Added a new replacer function feature, `JSONZ.LITERALLY_AS`, allowing a replacer function to explicitly determine how a value will be rendered when stringified.
+
 ### 4.0.1
 
 Minor documentation tweak.

README.md

@@ -95,6 +95,7 @@ The following features, which are not supported in standard JSON, have been adde
 - Replacer functions can return the special value `JSONZ.DELETE` to indicate that a slot in an array be left empty, creating a sparse array.
 - A global replacer function can be specified.
 - For the benefit of anonymous (arrow) functions, which do not have their own `this` as `functions` do, replacer functions are passed the holder of a key/value pair as a third argument to the function.
+- A replacer can return `JSONZ.LITERALLY_AS(`*string-value*`)` to specify [exactly how a given value will be stringified](#jsonzliterally_as).
 
 ### Reviver functions (JSON-Z specific differences)
 
@@ -400,6 +401,31 @@ This removes all user-added type handlers, and restores all built-in type handle
 
 This restores all built-in type handlers, leaving any user-added type handlers.
 
+### JSONZ.DELETE
+
+Return this value from a replacer function to delete an item from an object or to render a slot in an array as empty.
+
+### JSONZ.UNDEFINED
+
+Return this value from a replacer function (rather than returning `undefined` itself) to change a value to `undefined`.
+
+### JSONZ.LITERALLY_AS()
+
+Return `JSONZ.LITERALLY_AS(`*string-value*`)` from a replacer function to literally and explicitly specify how a particular value should be stringified. In this example:
+
+```javascript
+function showNumbersInHex(k, v) {
+  return typeof v === 'number' && isFinite(v) && !isNaN(v)
+         ? JSONZ.LITERALLY_AS((v < 0 ? '-' : '') +
+             '0x' + Math.abs(v).toString(16).toUpperCase())
+         : v;
+}
+
+JSONZ.stringify({ hexValue: 912559 }, showNumbersInHex)
+```
+
+...`stringify` with return `"{hexValue:0xDECAF}"` as a result.
+
 ### Node.js `require()` JSON-Z files
 
 When using Node.js, you can `require()` JSON-Z files by adding the following

lib/index.js

@@ -17,6 +17,7 @@ const JSONZ = {
   setParseOptions: options.setParseOptions,
   resetParseOptions: options.resetParseOptions,
 
+  LITERALLY_AS: util.LITERALLY_AS,
   DELETE: util.DELETE,
   UNDEFINED: util.UNDEFINED,
 

lib/stringify.js

@@ -1,6 +1,7 @@
 const util = require('./util');
 const big = require('./bignumber-util');
 const optionsMgr = require('./options-manager');
+const { LITERALLY_AS_CLASS } = require('./util');
 
 const escapes = {
   "'": "\\'",
@@ -160,6 +161,10 @@ module.exports = function stringify(value, replacer, space) {
       value = value.valueOf();
     }
 
+    if (value instanceof LITERALLY_AS_CLASS) {
+      return value.value;
+    }
+
     switch (value) {
       case null: return 'null';
       case true: return 'true';

lib/util.js

@@ -1,3 +1,9 @@
+class LITERALLY_AS {
+  constructor(value) {
+    this.value = value;
+  }
+}
+
 module.exports = {
   isSpaceSeparator(c) {
     return !!c && /[\u1680\u2000-\u200A\u202F\u205F\u3000]/.test(c);
@@ -44,9 +50,16 @@ module.exports = {
   },
 
   isTypeContainer(obj) {
-    return obj && typeof obj === 'object' && obj.hasOwnProperty('_$_') && obj.hasOwnProperty('_$_value') && Object.keys(obj).length === 2;
+    return obj && typeof obj === 'object' && obj.hasOwnProperty('_$_') &&
+           obj.hasOwnProperty('_$_value') && Object.keys(obj).length === 2;
+  },
+
+  LITERALLY_AS: function (value) {
+    return new LITERALLY_AS(value);
   },
 
+  LITERALLY_AS_CLASS: LITERALLY_AS,
+
   DELETE: Symbol('DELETE'),
   UNDEFINED: Symbol('UNDEFINED')
 };

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "json-z",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "JSON for everyone.",
   "main": "lib/index.min.js",
   "types": "lib/index.d.ts",