# @whi/json

> A helper library for serializing objects to JSON, JSON-bytes, or a JSON-like string for debugging

Latest version **0.2.1** (published 2025-05-20) · ISC license · 0 weekly downloads

## Install

```sh
npm install @whi/json
pnpm add @whi/json
yarn add @whi/json
bun add @whi/json
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.1 |
| Published | 2025-05-20 |
| First published | 2021-06-13 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 65.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Matthew Brisebois |
| Maintainers | brisebom |

## Links

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

## Dependencies (1)

- [@whi/object-walk](https://npm.io/package/@whi/object-walk.md) ^0.4.2

## Recent versions

- 0.2.1 (latest) — 2025-05-20
- 0.2.0 — 2025-05-20
- 0.1.9 — 2024-09-04
- 0.1.8 — 2024-07-04
- 0.1.7 — 2023-08-03
- 0.1.6 — 2022-08-17
- 0.1.5 — 2022-05-20
- 0.1.4 — 2022-03-16
- 0.1.3 — 2021-06-30
- 0.1.2 — 2021-06-22
- 0.1.1 — 2021-06-13
- 0.1.0 — 2021-06-13

## README

[![](https://img.shields.io/npm/v/@whi/json/latest?style=flat-square)](http://npmjs.com/package/@whi/json)

# Extending `JSON` functionality
This module is intended to extend the built-in JSON object with easier support for bytes,
key-ordering, and debugging.

[![](https://img.shields.io/github/issues-raw/mjbrisebois/js-json?style=flat-square)](https://github.com/mjbrisebois/js-json/issues)
[![](https://img.shields.io/github/issues-closed-raw/mjbrisebois/js-json?style=flat-square)](https://github.com/mjbrisebois/js-json/issues?q=is%3Aissue+is%3Aclosed)
[![](https://img.shields.io/github/issues-pr-raw/mjbrisebois/js-json?style=flat-square)](https://github.com/mjbrisebois/js-json/pulls)


## Overview
Existing JSON libraries

- `json-stable-stringify` - doesn't make use of the native `JSON.stringify`
- `fast-safe-stringify` - only addresses the circular reference issue
- `json-serializer` - lack of support/documentation and hasn't been touched since 2018
- `json-serialize` - lack of support/features and hasn't been touched since 2015

Some of these libraries would have been fine for what they do, but it would have been inefficient to
let each library walk the entire object just to do there 1 thing.


### Features

- Serialize/deserialize to JSON string
- Serialize/deserialize to JSON byte array (`Uint8Array`)
- Serialize/deserialize handles [Typed Array Views](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays#typed_array_views) & Buffer
- Serialize/deserialize handles `Date` objects
- Object key ordering for deterministic serializing
- Debugging format for displaying human-readable JSON-like object dumps
- Debugging formatter handles circular references


## Install

```bash
npm i @whi/json
```

## Usage

```javascript
import json from '@whi/json';

let input = {
    id: Buffer.from("Hello World")
};

json.stringify( input );
// '{"id":{"data":[72,101,108,108,111,32,87,111,114,108,100],"type":"Buffer"}}'

json.debug( input );
// '{
//     "id": <Buffer 48 65 6c 6c 6f 20 57 6f 72 6c 64>
// }'

json.serialize( input );
// Uint8Array(74) [
//   123,  34, 105, 100, 34, 58, 123,  34, 100,  97, 116,  97,
//    34,  58,  91,  55, 50, 44,  49,  48,  49,  44,  49,  48,
//    56,  44,  49,  48, 56, 44,  49,  49,  49,  44,  51,  50,
//    44,  56,  55,  44, 49, 49,  49,  44,  49,  49,  52,  44,
//    49,  48,  56,  44, 49, 48,  48,  93,  44,  34, 116, 121,
//   112, 101,  34,  58, 34, 66, 117, 102, 102, 101, 114,  34,
//   125, 125
// ]

let str = json.stringify( input );
let bytes = json.serialize( input );

// Parse can take JSON or JSON-bytes
json.parse( str );
// { id: <Buffer 48 65 6c 6c 6f 20 57 6f 72 6c 64> }
json.parse( bytes );
// { id: <Buffer 48 65 6c 6c 6f 20 57 6f 72 6c 64> }

json.deserialize( bytes );
// { id: <Buffer 48 65 6c 6c 6f 20 57 6f 72 6c 64> }

// Deserialize can only take bytes
json.deserialize( str );
// TypeError [ERR_INVALID_ARG_TYPE]: The "input" argument must be an instance of ArrayBuffer or ArrayBufferView. Received type string ('{"id":{"data":[72,101,10...)
```

### API Reference

See [docs/API.md](docs/API.md)

### Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

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