Package Exports

next-json
next-json/dist/cjs/index.js
next-json/dist/es/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (next-json) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

NJSON - next-json

Next JSON format

Why this package?

Because JSON is awesome, but...

JSON is awesome mainly for two reasons:

it offers an easy way to serialize and deserialize complex data;
a valid JSON encoded string can be pasted in a JavaScript source file, a really awesome feature while developing / debugging.

... but it has some limitations:

do not supports undefined values,
do not supports BigInt numbers,
do not supports many other features...

This package is intended to offer something as great as JSON... trying to add something more.

NJSON Features

☑ extends JSON
☑ supports C style comments
☑ supports undefined
☑ supports -0, NaN and Infinity
☑ supports BigInt
☑ supports Date
☑ supports Map
☑ supports RegExp
☑ supports Set
☑ supports URL
☐ supports Error
☐ supports circular references

NJSON extends JSON

This doesn't mean it's 100% compliant: due its higher number of supported features the result string of the serialization through NJSON.stringify may differs from the result of the serialization through JSON.stringify.

On the other hand, the result of the deserialization of a valid JSON encoded string through NJSON.parse will produce a value deep equal to the value produced by JSON.parse and the reviver function will be called the same amount of times, with the same parameters and in the same order.

Taken the result of a JSON.parse call (i.e. a value which contains only valid JSON values), if serialized through JSON.stringify or NJSON.stringify produces two equal strings and the replacer function will be called the same amount of times, with the same parameters and in the same order.

Installation

With npm:

npm install --save next-json

Usage

JavaScript

import { NJSON, NjsonParseOptions, NjsonStringifyOptions } from "next-json";

const serialized = NJSON.stringify({ some: "value" });
const deserialized = NJSON.parse(serialized);

TypeScript

import { NJSON, NjsonParseOptions, NjsonStringifyOptions } from "next-json";

const serialized: string = NJSON.stringify({ some: "value" });
const deserialized: { some: string } = NJSON.parse<{ some: string }>(serialized);

API

NJSON.parse(text[, reviver])

Just for compatibility with JSON.parse. Alias for:

NJSON.parse(text, { reviver });

NJSON.parse(text[, options])

text <string> The text to deserialize.
options <NjsonParseOptions> Deserialization options.
Returns: <unknown> The value result of the deserialization of the NJSON encoded text.

NJSON.stringify(value[, replacer[, space]])

Just for compatibility with JSON.stringify. Alias for:

NJSON.stringify(value, { replacer, space });

NJSON.stringify(value[, options])

value <unknown> The value to serialize.
options <NjsonStringifyOptions> Serialization options.
Returns: <string> The NJSON encoded serialized form of value.

interface NjsonParseOptions

numberKey: <boolean> Alters the type of the key argument for reviver. Default: false.
reviver: <Function> Alters the behavior of the deserialization process. Default: null.

NjsonParseOptions.numberKey

If true, the reviver function, for Array elements, will be called with the key argument in a Number form.

NjsonParseOptions.reviver

As the reviver parameter of JSON.parse. See also replacer / reviver for NJSON specific details.

interface NjsonStringifyOptions

date: <string> Specifies Dates conversion method. Default: "time".
numberKey: <boolean> Alters the type of the key argument for replacer. Default: false.
replacer: <Function> | <Array> Alters the behavior of the serialization process. Default: null.
space: <number> | <string> Specifies the indentation. Default: null.
undef: <boolean> Specifies the undefined behavior. Default: true.

NjsonStringifyOptions.date

Specifies the method of Date objects used to serialize them. Follows the list of the allowed values and the relative method used.

"iso": Date.toISOString()
"string": Date.toString()
"time": Date.getTime() - the default
"utc": Date.toUTCString()

NjsonStringifyOptions.numberKey

If true, the replacer function, for Array elements, will be called with the key argument in a Number form.

NjsonStringifyOptions.replacer

As the replacer parameter of JSON.serialize. See also replacer / reviver for NJSON specific details.

NjsonStringifyOptions.space

As the space parameter of JSON.serialize.

NjsonStringifyOptions.undef

For default NJSON.stringify serializes undefined values as well. If set to false, undefined values are treated as JSON.stringify does.

replacer / reviver

Even if Date, Error, RegExp and URL are Objects, they are treated as native values i.e. replacer and reviver will be never called with one of them as this context.
For Arrays the key argument is obviously a positive integer, but in a String form for JSON compatibility. This can be altered (i.e. in a Number) form the numberKey option can be used.
For Sets the key argument is obviously a positive integer as well, but it is only passed in a Number form.
For Maps the key argument is once again a positive integer in a Number form and the value argument is the entry in the form [mapKey, mapValue].

Compatibility

Requires Node.js v14.

The package is tested under all Node.js versions currently supported accordingly to Node.js Release.

TypeScript

TypeScript types are distributed with the package itself.

License

MIT License

Bugs

Do not hesitate to report any bug or inconsistency @github.

Donating

If you find useful this package, please consider the opportunity to donate some satoshis to this bitcoin address: 1Md9WFAHrXTb3yPBwQWmUfv2RmzrtbHioB