@brillout/json-serializer 0.5.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2022-present Romuald Brillout
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/cjs/parse.d.ts

@@ -0,0 +1,2 @@
+export { parse };
+declare function parse(str: string): unknown;

package/dist/cjs/parse.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parse = void 0;
+const types_1 = require("./types");
+function parse(str) {
+    // We don't use the reviver option in `JSON.parse(str, reviver)` because it doesn't support `undefined` values
+    const value = JSON.parse(str);
+    return modifier(value);
+}
+exports.parse = parse;
+function modifier(value) {
+    if (typeof value === 'string') {
+        return reviver(value);
+    }
+    if (typeof value === 'object' && value !== null) {
+        Object.entries(value).forEach(([key, val]) => {
+            ;
+            value[key] = modifier(val);
+        });
+    }
+    return value;
+}
+function reviver(value) {
+    for (const { match, deserialize } of types_1.types) {
+        if (match(value)) {
+            return deserialize(value, parse);
+        }
+    }
+    return value;
+}

package/dist/cjs/stringify.d.ts

@@ -0,0 +1,7 @@
+export { stringify };
+declare function stringify(value: unknown, { forbidReactElements, space, valueName, sortObjectKeys }?: {
+    forbidReactElements?: boolean;
+    space?: number;
+    valueName?: string;
+    sortObjectKeys?: boolean;
+}): string;

package/dist/cjs/stringify.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringify = void 0;
+const types_1 = require("./types");
+const isReactElement_1 = require("./utils/isReactElement");
+const isCallable_1 = require("./utils/isCallable");
+const isObject_1 = require("./utils/isObject");
+function stringify(value, { forbidReactElements, space, valueName = 'value', sortObjectKeys } = {}) {
+    const path = [];
+    // The only error `JSON.stringify()` can throw is `TypeError "cyclic object value"`.
+    // - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#exceptions
+    // - This means we have total of 3 possible errors while serializing:
+    //    - Cyclic references
+    //    - Functions
+    //    - React elements
+    const serializer = (val) => JSON.stringify(val, replacer, space);
+    return serializer(value);
+    function replacer(key, value) {
+        if (key !== '') {
+            path.push(key);
+        }
+        if (forbidReactElements && (0, isReactElement_1.isReactElement)(value)) {
+            throw new Error(genErrMsg('React element'));
+        }
+        if ((0, isCallable_1.isCallable)(value)) {
+            const functionName = value.name;
+            throw new Error(genErrMsg('function', path.length === 0 ? functionName : undefined));
+        }
+        const valueOriginal = this[key];
+        for (const { is, serialize } of types_1.types.slice().reverse()) {
+            if (is(valueOriginal)) {
+                //@ts-ignore
+                return serialize(valueOriginal, serializer);
+            }
+        }
+        if (sortObjectKeys && (0, isObject_1.isObject)(value)) {
+            const copy = {};
+            Object.keys(value)
+                .sort()
+                .forEach((key) => {
+                copy[key] = value[key];
+            });
+            value = copy;
+        }
+        return value;
+    }
+    function genErrMsg(valueType, valName) {
+        const name = valName ? ' `' + valName + '`' : '';
+        const location = path.length === 0 ? '' : ` ${name ? 'at ' : ''}\`${valueName}[${path.map((p) => `'${p}'`).join('][')}]\``;
+        const fallback = name === '' && location === '' ? ` ${valueName}` : '';
+        return `Cannot serialize${name}${location}${fallback} because it is a ${valueType} (https://github.com/brillout/json-s)`;
+    }
+}
+exports.stringify = stringify;

package/dist/cjs/types.d.ts

@@ -0,0 +1,8 @@
+export { types };
+declare const types: readonly [Type<undefined, unknown>, Type<number, unknown>, Type<number, unknown>, Type<number, unknown>, Type<Date, any>, Type<BigInt, any>, Type<RegExp, any>, Type<Map<any, any>, any[]>, Type<Set<unknown>, unknown[]>, Type<string, any>];
+declare type Type<T, IntermediateType> = {
+    is: (val: unknown) => asserts val is T;
+    match: (str: string) => boolean;
+    serialize: (val: T, serializer: (val: IntermediateType) => string) => string;
+    deserialize: (str: string, deserializer: (str: string) => IntermediateType) => T;
+};

package/dist/cjs/types.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.types = void 0;
+const types = [
+    ts({
+        is: (val) => val === undefined,
+        match: (str) => str === '!undefined',
+        serialize: () => '!undefined',
+        deserialize: () => undefined
+    }),
+    ts({
+        is: (val) => val === Infinity,
+        match: (str) => str === '!Infinity',
+        serialize: () => '!Infinity',
+        deserialize: () => Infinity
+    }),
+    ts({
+        is: (val) => val === -Infinity,
+        match: (str) => str === '!-Infinity',
+        serialize: () => '!-Infinity',
+        deserialize: () => -Infinity
+    }),
+    ts({
+        is: (val) => typeof val === 'number' && isNaN(val),
+        match: (str) => str === '!NaN',
+        serialize: () => '!NaN',
+        deserialize: () => NaN
+    }),
+    ts({
+        is: (val) => val instanceof Date,
+        match: (str) => str.startsWith('!Date:'),
+        serialize: (val) => '!Date:' + val.toISOString(),
+        deserialize: (str) => new Date(str.slice('!Date:'.length))
+    }),
+    ts({
+        is: (val) => typeof val === 'bigint',
+        match: (str) => str.startsWith('!BigInt:'),
+        serialize: (val) => '!BigInt:' + val.toString(),
+        deserialize: (str) => {
+            if (typeof BigInt === 'undefined') {
+                throw new Error('Your JavaScript environement does not support BigInt. Consider adding a polyfill.');
+            }
+            return BigInt(str.slice('!BigInt:'.length));
+        }
+    }),
+    ts({
+        is: (val) => val instanceof RegExp,
+        match: (str) => str.startsWith('!RegExp:'),
+        serialize: (val) => '!RegExp:' + val.toString(),
+        deserialize: (str) => {
+            str = str.slice('!RegExp:'.length);
+            // const args: string[] = str.match(/\/(.*?)\/([gimy])?$/)!
+            const args = str.match(/\/(.*)\/(.*)?/);
+            const pattern = args[1];
+            const flags = args[2];
+            return new RegExp(pattern, flags);
+        }
+    }),
+    ts({
+        is: (val) => val instanceof Map,
+        match: (str) => str.startsWith('!Map:'),
+        serialize: (val, serializer) => '!Map:' + serializer(Array.from(val.entries())),
+        deserialize: (str, deserializer) => new Map(deserializer(str.slice('!Map:'.length)))
+    }),
+    ts({
+        is: (val) => val instanceof Set,
+        match: (str) => str.startsWith('!Set:'),
+        serialize: (val, serializer) => '!Set:' + serializer(Array.from(val.values())),
+        deserialize: (str, deserializer) => new Set(deserializer(str.slice('!Set:'.length)))
+    }),
+    // Avoid collisions with the special strings defined above
+    ts({
+        is: (val) => typeof val === 'string' && val.startsWith('!'),
+        match: (str) => str.startsWith('!'),
+        serialize: (val) => '!' + val,
+        deserialize: (str) => str.slice(1)
+    })
+];
+exports.types = types;
+// Type check
+function ts(t) {
+    return t;
+}

package/dist/cjs/utils/isCallable.d.ts

@@ -0,0 +1 @@
+export declare function isCallable<T extends (...args: unknown[]) => unknown>(thing: T | unknown): thing is T;

package/dist/cjs/utils/isCallable.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCallable = void 0;
+function isCallable(thing) {
+    return thing instanceof Function || typeof thing === 'function';
+}
+exports.isCallable = isCallable;

package/dist/cjs/utils/isObject.d.ts

@@ -0,0 +1,3 @@
+export { isObject };
+declare type Object = Record<string, unknown>;
+declare function isObject(value: unknown): value is Object;

package/dist/cjs/utils/isObject.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isObject = void 0;
+function isObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return false;
+    }
+    return true;
+}
+exports.isObject = isObject;

package/dist/cjs/utils/isReactElement.d.ts

@@ -0,0 +1 @@
+export declare function isReactElement(value: unknown): boolean;

package/dist/cjs/utils/isReactElement.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isReactElement = void 0;
+function isReactElement(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        String(value['$$typeof']) === 'Symbol(react.element)');
+}
+exports.isReactElement = isReactElement;

package/dist/esm/parse.d.ts

@@ -0,0 +1,2 @@
+export { parse };
+declare function parse(str: string): unknown;

package/dist/esm/parse.js

@@ -0,0 +1,27 @@
+export { parse };
+import { types } from './types';
+function parse(str) {
+    // We don't use the reviver option in `JSON.parse(str, reviver)` because it doesn't support `undefined` values
+    const value = JSON.parse(str);
+    return modifier(value);
+}
+function modifier(value) {
+    if (typeof value === 'string') {
+        return reviver(value);
+    }
+    if (typeof value === 'object' && value !== null) {
+        Object.entries(value).forEach(([key, val]) => {
+            ;
+            value[key] = modifier(val);
+        });
+    }
+    return value;
+}
+function reviver(value) {
+    for (const { match, deserialize } of types) {
+        if (match(value)) {
+            return deserialize(value, parse);
+        }
+    }
+    return value;
+}

package/dist/esm/stringify.d.ts

@@ -0,0 +1,7 @@
+export { stringify };
+declare function stringify(value: unknown, { forbidReactElements, space, valueName, sortObjectKeys }?: {
+    forbidReactElements?: boolean;
+    space?: number;
+    valueName?: string;
+    sortObjectKeys?: boolean;
+}): string;

package/dist/esm/stringify.js

@@ -0,0 +1,51 @@
+export { stringify };
+import { types } from './types';
+import { isReactElement } from './utils/isReactElement';
+import { isCallable } from './utils/isCallable';
+import { isObject } from './utils/isObject';
+function stringify(value, { forbidReactElements, space, valueName = 'value', sortObjectKeys } = {}) {
+    const path = [];
+    // The only error `JSON.stringify()` can throw is `TypeError "cyclic object value"`.
+    // - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#exceptions
+    // - This means we have total of 3 possible errors while serializing:
+    //    - Cyclic references
+    //    - Functions
+    //    - React elements
+    const serializer = (val) => JSON.stringify(val, replacer, space);
+    return serializer(value);
+    function replacer(key, value) {
+        if (key !== '') {
+            path.push(key);
+        }
+        if (forbidReactElements && isReactElement(value)) {
+            throw new Error(genErrMsg('React element'));
+        }
+        if (isCallable(value)) {
+            const functionName = value.name;
+            throw new Error(genErrMsg('function', path.length === 0 ? functionName : undefined));
+        }
+        const valueOriginal = this[key];
+        for (const { is, serialize } of types.slice().reverse()) {
+            if (is(valueOriginal)) {
+                //@ts-ignore
+                return serialize(valueOriginal, serializer);
+            }
+        }
+        if (sortObjectKeys && isObject(value)) {
+            const copy = {};
+            Object.keys(value)
+                .sort()
+                .forEach((key) => {
+                copy[key] = value[key];
+            });
+            value = copy;
+        }
+        return value;
+    }
+    function genErrMsg(valueType, valName) {
+        const name = valName ? ' `' + valName + '`' : '';
+        const location = path.length === 0 ? '' : ` ${name ? 'at ' : ''}\`${valueName}[${path.map((p) => `'${p}'`).join('][')}]\``;
+        const fallback = name === '' && location === '' ? ` ${valueName}` : '';
+        return `Cannot serialize${name}${location}${fallback} because it is a ${valueType} (https://github.com/brillout/json-s)`;
+    }
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,8 @@
+export { types };
+declare const types: readonly [Type<undefined, unknown>, Type<number, unknown>, Type<number, unknown>, Type<number, unknown>, Type<Date, any>, Type<BigInt, any>, Type<RegExp, any>, Type<Map<any, any>, any[]>, Type<Set<unknown>, unknown[]>, Type<string, any>];
+declare type Type<T, IntermediateType> = {
+    is: (val: unknown) => asserts val is T;
+    match: (str: string) => boolean;
+    serialize: (val: T, serializer: (val: IntermediateType) => string) => string;
+    deserialize: (str: string, deserializer: (str: string) => IntermediateType) => T;
+};

package/dist/esm/types.js

@@ -0,0 +1,80 @@
+export { types };
+const types = [
+    ts({
+        is: (val) => val === undefined,
+        match: (str) => str === '!undefined',
+        serialize: () => '!undefined',
+        deserialize: () => undefined
+    }),
+    ts({
+        is: (val) => val === Infinity,
+        match: (str) => str === '!Infinity',
+        serialize: () => '!Infinity',
+        deserialize: () => Infinity
+    }),
+    ts({
+        is: (val) => val === -Infinity,
+        match: (str) => str === '!-Infinity',
+        serialize: () => '!-Infinity',
+        deserialize: () => -Infinity
+    }),
+    ts({
+        is: (val) => typeof val === 'number' && isNaN(val),
+        match: (str) => str === '!NaN',
+        serialize: () => '!NaN',
+        deserialize: () => NaN
+    }),
+    ts({
+        is: (val) => val instanceof Date,
+        match: (str) => str.startsWith('!Date:'),
+        serialize: (val) => '!Date:' + val.toISOString(),
+        deserialize: (str) => new Date(str.slice('!Date:'.length))
+    }),
+    ts({
+        is: (val) => typeof val === 'bigint',
+        match: (str) => str.startsWith('!BigInt:'),
+        serialize: (val) => '!BigInt:' + val.toString(),
+        deserialize: (str) => {
+            if (typeof BigInt === 'undefined') {
+                throw new Error('Your JavaScript environement does not support BigInt. Consider adding a polyfill.');
+            }
+            return BigInt(str.slice('!BigInt:'.length));
+        }
+    }),
+    ts({
+        is: (val) => val instanceof RegExp,
+        match: (str) => str.startsWith('!RegExp:'),
+        serialize: (val) => '!RegExp:' + val.toString(),
+        deserialize: (str) => {
+            str = str.slice('!RegExp:'.length);
+            // const args: string[] = str.match(/\/(.*?)\/([gimy])?$/)!
+            const args = str.match(/\/(.*)\/(.*)?/);
+            const pattern = args[1];
+            const flags = args[2];
+            return new RegExp(pattern, flags);
+        }
+    }),
+    ts({
+        is: (val) => val instanceof Map,
+        match: (str) => str.startsWith('!Map:'),
+        serialize: (val, serializer) => '!Map:' + serializer(Array.from(val.entries())),
+        deserialize: (str, deserializer) => new Map(deserializer(str.slice('!Map:'.length)))
+    }),
+    ts({
+        is: (val) => val instanceof Set,
+        match: (str) => str.startsWith('!Set:'),
+        serialize: (val, serializer) => '!Set:' + serializer(Array.from(val.values())),
+        deserialize: (str, deserializer) => new Set(deserializer(str.slice('!Set:'.length)))
+    }),
+    // Avoid collisions with the special strings defined above
+    ts({
+        is: (val) => typeof val === 'string' && val.startsWith('!'),
+        match: (str) => str.startsWith('!'),
+        serialize: (val) => '!' + val,
+        deserialize: (str) => str.slice(1)
+    })
+];
+// Type check
+function ts(t) {
+    return t;
+}

package/dist/esm/utils/isCallable.d.ts

@@ -0,0 +1 @@
+export declare function isCallable<T extends (...args: unknown[]) => unknown>(thing: T | unknown): thing is T;

package/dist/esm/utils/isCallable.js

@@ -0,0 +1,3 @@
+export function isCallable(thing) {
+    return thing instanceof Function || typeof thing === 'function';
+}

package/dist/esm/utils/isObject.d.ts

@@ -0,0 +1,3 @@
+export { isObject };
+declare type Object = Record<string, unknown>;
+declare function isObject(value: unknown): value is Object;

package/dist/esm/utils/isObject.js

@@ -0,0 +1,10 @@
+export { isObject };
+function isObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return false;
+    }
+    return true;
+}

package/dist/esm/utils/isReactElement.d.ts

@@ -0,0 +1 @@
+export declare function isReactElement(value: unknown): boolean;

package/dist/esm/utils/isReactElement.js

@@ -0,0 +1,5 @@
+export function isReactElement(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        String(value['$$typeof']) === 'Symbol(react.element)');
+}

package/index.js

@@ -0,0 +1 @@
+throw new Error("Module `@brillout/json-serializer` doesn't exist anymore: load `@brillout/json-serializer/parse` and `@brillout/json-serializer/stringify` instead.")

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@brillout/json-serializer",
+  "version": "0.5.1",
+  "description": "Same as JSON but with added support for `Date`, `undefined`, `Map`, `Set`, and more.",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./parse": {
+      "require": "./dist/cjs/parse.js",
+      "import": "./dist/esm/parse.js"
+    },
+    "./stringify": {
+      "require": "./dist/cjs/stringify.js",
+      "import": "./dist/esm/stringify.js"
+    }
+  },
+  "scripts": {
+    "dev": "pnpm run tsc:watch:cjs",
+    "build": "pnpm run clean && pnpm run tsc:esm && pnpm run tsc:cjs",
+    "test": "self-import && node test/",
+    "docs": "mdocs",
+    "tsc:esm": "tsc",
+    "tsc:cjs": "tsc --project ./tsconfig.cjs.json",
+    "tsc:watch:esm": "tsc --incremental --watch",
+    "tsc:watch:cjs": "tsc --incremental --watch --project ./tsconfig.cjs.json",
+    "clean": "rm -rf dist/",
+    "reset": "git clean -Xdf && pnpm install && pnpm build",
+    "release": "release-me patch"
+  },
+  "devDependencies": {
+    "@brillout/mdocs": "^0.1.30",
+    "@brillout/release-me": "^0.0.5",
+    "@types/node": "17.0.13",
+    "lodash.isequal": "^4.5.0",
+    "react": "^17.0.2",
+    "self-import": "^1.0.1",
+    "typescript": "^4.8.2"
+  },
+  "files": [
+    "dist/",
+    "*.d.ts",
+    "*.js"
+  ],
+  "repository": "github:brillout/json-serializer",
+  "packageManager": "pnpm@7.9.5",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/parse.d.ts

@@ -0,0 +1,2 @@
+// Help TS's resolver until it supports `package.json#exports`
+export { parse } from './dist/esm/parse'

package/parse.js

@@ -0,0 +1,8 @@
+// Some tools don't support `package.json#exports`, such as:
+//  - Nuxt v2
+//  - Expo/Metro
+//  - ESLint
+// prettier-ignore
+'use strict';
+// prettier-ignore
+exports.parse = require('./dist/cjs/parse.js').parse;

package/readme.md

@@ -0,0 +1,325 @@
+<!---
+
+
+
+
+
+
+    WARNING, READ THIS.
+    This is a computed file. Do not edit.
+    Instead, edit `/readme.template.md` and run `npm run docs` (or `yarn docs`).
+
+
+
+
+
+
+
+
+
+
+
+
+    WARNING, READ THIS.
+    This is a computed file. Do not edit.
+    Instead, edit `/readme.template.md` and run `npm run docs` (or `yarn docs`).
+
+
+
+
+
+
+
+
+
+
+
+
+    WARNING, READ THIS.
+    This is a computed file. Do not edit.
+    Instead, edit `/readme.template.md` and run `npm run docs` (or `yarn docs`).
+
+
+
+
+
+
+
+
+
+
+
+
+    WARNING, READ THIS.
+    This is a computed file. Do not edit.
+    Instead, edit `/readme.template.md` and run `npm run docs` (or `yarn docs`).
+
+
+
+
+
+
+
+
+
+
+
+
+    WARNING, READ THIS.
+    This is a computed file. Do not edit.
+    Instead, edit `/readme.template.md` and run `npm run docs` (or `yarn docs`).
+
+
+
+
+
+
+-->
+# `@brillout/json-serializer`
+
+Same as JSON but with added support for:
+ - `Date`
+ - `undefined`
+ - `Set`
+ - `Map`
+ - `BigInt`
+ - `RegExp`
+ - `NaN`
+ - `Infinity`
+
+JSON is a good serializer for JavaScript values but
+is lacking some JavaScript types such as `Date`:
+
+~~~js
+const assert = require('assert')
+
+let obj = {
+  time: new Date('2042-01-01')
+}
+
+// JSON converts dates to strings
+assert(obj.time.constructor === Date)
+obj = JSON.parse(JSON.stringify(obj))
+assert(obj.time.constructor === String)
+assert(obj.time === '2042-01-01T00:00:00.000Z')
+~~~
+
+Whereas with `@brillout/json-serializer`:
+
+~~~js
+const assert = require('assert')
+const { parse } = require('@brillout/json-serializer/parse')
+const { stringify } = require('@brillout/json-serializer/stringify')
+
+let obj = {
+  time: new Date('2042-01-01')
+}
+
+// `@brillout/json-serializer` preserves Date
+assert(obj.time.constructor === Date)
+obj = parse(stringify(obj))
+assert(obj.time.constructor === Date)
+assert(obj.time.getTime() === new Date('2042-01-01').getTime())
+~~~
+
+<br/>
+
+#### Contents
+
+ - [Usage](#usage)
+ - [Full Example](#full-example)
+ - [How it Works](#how-it-works)
+
+
+<br/>
+
+### Usage
+
+~~~js
+// npm install @brillout/json-serializer
+const { parse } = require('@brillout/json-serializer/parse')
+const { stringify } = require('@brillout/json-serializer/stringify')
+
+const obj = {
+  hello: 'from the future',
+  time: new Date('2042-01-01')
+}
+
+// Serialize with @brillout/json-serializer
+const obj_serialized = stringify(obj)
+
+// Deserialize a @brillout/json-serializer string
+const obj_deserialized = parse(obj_serialized)
+~~~
+
+<br/>
+
+### Full Example
+
+Example exposing all differences between JSON and `@brillout/json-serializer`.
+
+~~~js
+// /examples/json-serializer.js
+
+const assert = require('assert')
+
+const { parse } = require('@brillout/json-serializer/parse')
+const { stringify } = require('@brillout/json-serializer/stringify')
+
+const obj = {
+  date: new Date(),
+  undefined: undefined,
+  NaN: NaN,
+  Infinity: Infinity,
+  regexp: /^\d+$/g
+}
+
+// All of `obj` can be serialized with @brillout/json-serializer
+const obj2 = parse(stringify(obj))
+assert(obj2.date.getTime() === obj.date.getTime())
+assert(obj2.undefined === undefined && 'undefined' in obj2)
+assert(isNaN(obj2.NaN))
+assert(obj2.Infinity === Infinity)
+assert(obj2.regexp.toString() === obj.regexp.toString())
+
+// JSON cannot serialize any of `obj`
+const obj3 = JSON.parse(JSON.stringify(obj))
+// JSON converts dates to strings
+assert(obj3.constructor !== Date)
+// JSON removes properties with a value of `undefined`
+assert(!('undefined' in obj3))
+// JSON converts `NaN` to `null`
+assert(obj3.NaN === null)
+// JSON converts `Infinity` to `null`
+assert(obj3.Infinity === null)
+// JSON converts RegExp to an empty object
+assert(obj3.regexp.constructor === Object && Object.keys(obj3.regexp).length === 0)
+~~~
+
+To run the example:
+
+~~~shell
+$ git clone git@github.com:brillout/json-serializer
+$ cd json-serializer
+$ npm install
+$ npm run self-link
+$ node ./examples/json-serializer.js
+~~~
+
+The `npm run self-link` is required to be able to self `require('@brillout/json-serializer')`.
+
+<br/>
+
+### How it Works
+
+Let's see how `@brillout/json-serializer` serializes an object:
+
+~~~js
+// /examples/inspect.js
+
+const { stringify } = require('@brillout/json-serializer/stringify')
+
+const obj = {
+  date: new Date(),
+  undefined: undefined,
+  collision: '!undefined',
+  NaN: NaN,
+  Infinity: Infinity,
+  regexp: /^\d+$/g
+}
+
+console.log(stringify(obj, undefined, 2))
+// Prints:
+/*
+{
+  "date": "!Date:2021-01-12T22:15:56.319Z",
+  "undefined": "!undefined",
+  "collision": "!!undefined"
+  "NaN": "!NaN",
+  "Infinity": "!Infinity",
+  "regexp": "!RegExp:/^\\d+$/g"
+}
+*/
+~~~
+
+`@brillout/json-serializer` is based on JSON while using prefixed strings for unsupported types.
+
+`@brillout/json-serializer` uses the native `JSON.parse` and `JSON.stringify` functions while modifying the serialization of unsupported types.
+
+<!---
+
+
+
+
+
+
+    WARNING, READ THIS.
+    This is a computed file. Do not edit.
+    Instead, edit `/readme.template.md` and run `npm run docs` (or `yarn docs`).
+
+
+
+
+
+
+
+
+
+
+
+
+    WARNING, READ THIS.
+    This is a computed file. Do not edit.
+    Instead, edit `/readme.template.md` and run `npm run docs` (or `yarn docs`).
+
+
+
+
+
+
+
+
+
+
+
+
+    WARNING, READ THIS.
+    This is a computed file. Do not edit.
+    Instead, edit `/readme.template.md` and run `npm run docs` (or `yarn docs`).
+
+
+
+
+
+
+
+
+
+
+
+
+    WARNING, READ THIS.
+    This is a computed file. Do not edit.
+    Instead, edit `/readme.template.md` and run `npm run docs` (or `yarn docs`).
+
+
+
+
+
+
+
+
+
+
+
+
+    WARNING, READ THIS.
+    This is a computed file. Do not edit.
+    Instead, edit `/readme.template.md` and run `npm run docs` (or `yarn docs`).
+
+
+
+
+
+
+-->

package/readme.template.md

@@ -0,0 +1,77 @@
+# `@brillout/json-serializer`
+
+Same as JSON but with added support for:
+ - `Date`
+ - `undefined`
+ - `Set`
+ - `Map`
+ - `BigInt`
+ - `RegExp`
+ - `NaN`
+ - `Infinity`
+
+JSON is a good serializer for JavaScript values but
+is lacking some JavaScript types such as `Date`:
+
+~~~js
+!INLINE /examples/date_json.js --hide-source-path
+~~~
+
+Whereas with `@brillout/json-serializer`:
+
+~~~js
+!INLINE /examples/date_json-serializer.js --hide-source-path
+~~~
+
+<br/>
+
+#### Contents
+
+ - [Usage](#usage)
+ - [Full Example](#full-example)
+ - [How it Works](#how-it-works)
+
+
+<br/>
+
+### Usage
+
+~~~js
+!INLINE /examples/simple.js --hide-source-path
+~~~
+
+<br/>
+
+### Full Example
+
+Example exposing all differences between JSON and `@brillout/json-serializer`.
+
+~~~js
+!INLINE /examples/json-serializer.js
+~~~
+
+To run the example:
+
+~~~shell
+$ git clone git@github.com:brillout/json-serializer
+$ cd json-serializer
+$ npm install
+$ npm run self-link
+$ node ./examples/json-serializer.js
+~~~
+
+The `npm run self-link` is required to be able to self `require('@brillout/json-serializer')`.
+
+<br/>
+
+### How it Works
+
+Let's see how `@brillout/json-serializer` serializes an object:
+
+~~~js
+!INLINE /examples/inspect.js
+~~~
+
+`@brillout/json-serializer` is based on JSON while using prefixed strings for unsupported types.
+
+`@brillout/json-serializer` uses the native `JSON.parse` and `JSON.stringify` functions while modifying the serialization of unsupported types.

package/stringify.d.ts

@@ -0,0 +1,2 @@
+// Help TS's resolver until it supports `package.json#exports`
+export { stringify } from './dist/esm/stringify'

package/stringify.js

@@ -0,0 +1,8 @@
+// Some tools don't support `package.json#exports`, such as:
+//  - Nuxt v2
+//  - Expo/Metro
+//  - ESLint
+// prettier-ignore
+'use strict';
+// prettier-ignore
+exports.stringify = require('./dist/cjs/stringify.js').stringify;