JsonSuperSet

Extended JSON serialization supporting Date, RegExp, Error, undefined, Map, Set, and circular references.

Installation

``bash
npm install jsonsuperset
`

Quick Start

`javascript
const jss = require('jsonsuperset')

const data = {
created: new Date(),
pattern: /hello/gi,
items: new Set([1, 2, 3]),
config: new Map([['key', 'value']])
}

const json = jss.stringify(data)
const restored = jss.parse(json)

restored.created // Date object
restored.pattern // RegExp /hello/gi
restored.items // Set {1, 2, 3}
restored.config // Map {'key' => 'value'}
`

Supported Types

| Type | Description |
|------|-------------|
| Date | Preserved as Date objects |
| RegExp | Pattern and flags preserved |
| Error | Type, message, and stack preserved |
| undefined | Preserved (normally lost in JSON) |
| Map | Key-value pairs preserved |
| Set | Unique values preserved |
| Circular refs | Self-references and shared objects maintained |

API

$3

Serializes an object to a JSON string with type information.

`javascript
jss.stringify({ date: new Date('2025-01-01') })
// '{"date":1735689600000}'
`

$3

Deserializes a JSON string back to an object with types restored.

`javascript
jss.parse('{"date":1735689600000}')
// { date: Date('2025-01-01') }
`

$3

Low-level functions for inspecting the tagged format without JSON stringification.

`javascript
const encoded = jss.encode({ d: new Date(), s: new Set([1, 2]) })
// { "d": 1234567890, "s": [1, 2] }

const decoded = jss.decode(encoded)
// { d: Date, s: Set }
`

$3

Register a custom type handler.

`javascript
jss.custom('B', {
check: (key, value) => typeof value === 'bigint',
encode: (path, key, value, context) => value.toString(),
decode: (value, path, context) => BigInt(value)
})

jss.stringify({ big: 9007199254740993n })
// '{"big":"9007199254740993"}'
`

Examples

$3

`javascript
const error = new TypeError('Invalid input')
error.code = 'ERR_INVALID'

const result = jss.parse(jss.stringify({ err: error }))
result.err instanceof TypeError // true
result.err.message // 'Invalid input'
result.err.stack // original stack trace
`

$3

`javascript
const obj = { name: 'root' }
obj.self = obj

const result = jss.parse(jss.stringify(obj))
result.self === result // true
`

$3

`javascript
const shared = { value: 42 }
const data = { a: shared, b: shared }

const result = jss.parse(jss.stringify(data))
result.a === result.b // true (same object reference)
`

Wire Format

Properties with special types are tagged using suffix:

`
key → Date (stored as timestamp)
key → RegExp (stored as "/pattern/flags")
key → Error (stored as [name, message, stack])
key → undefined (stored as null)
key → Map (stored as object)
key → Set (stored as array)
key → Pointer (circular reference path)
`

Arrays with typed elements use compound tags: arr or shorthand arr` for homogeneous arrays.