# @brillout/json-serializer

> Same as JSON but with added support for `Date`, `undefined`, `Map`, `Set`, and more.

Latest version **0.5.27** (published 2026-09-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @brillout/json-serializer
pnpm add @brillout/json-serializer
yarn add @brillout/json-serializer
bun add @brillout/json-serializer
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.5.27 |
| Published | 2026-09-30 |
| First published | 2022-09-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 27.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 52 |
| Maintainers | brillout |

## Links

- npm: https://www.npmjs.com/package/@brillout/json-serializer
- Repository: https://github.com/brillout/json-serializer
- Homepage: https://github.com/brillout/json-serializer#readme
- Issues: https://github.com/brillout/json-serializer/issues
- npm.io page: https://npm.io/package/@brillout/json-serializer

## Recent versions

- 0.5.27 (latest) — 2026-09-30
- 0.5.26 — 2026-09-30
- 0.5.25 — 2026-06-08
- 0.5.24 — 2026-06-08
- 0.5.23-commit-8c863db — 2026-06-08
- 0.5.23-commit-49a656b — 2026-06-08
- 0.5.23 — 2026-04-24
- 0.5.22 — 2026-02-22
- 0.5.21 — 2025-09-12
- 0.5.20 — 2025-08-21
- 0.5.19-commit-8a9605c — 2025-08-21
- 0.5.19 — 2025-08-20
- 0.5.18 — 2025-08-20
- 0.5.17 — 2025-08-04
- 0.5.16 — 2025-07-07
- … 15 more at https://npm.io/package/@brillout/json-serializer/versions

## README

<!---






    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`
 - `Uint8Array`
 - `NaN`
 - `Infinity`

JSON is a good serializer for JavaScript values but
is lacking some JavaScript types such as `Date`:

~~~js
import assert from '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
import { parse } from '@brillout/json-serializer/parse'
import { stringify } from '@brillout/json-serializer/stringify'
import assert from 'assert'

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
import { parse } from '@brillout/json-serializer/parse'
import { stringify } from '@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

import { parse } from '@brillout/json-serializer/parse'
import { stringify } from '@brillout/json-serializer/stringify'
import assert from 'assert'

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

import { stringify } from '@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`).






-->

---
_Source: https://npm.io/package/@brillout/json-serializer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._