# json-stringifier

> Alternative to JSON.stringify() that supports altering the behavior of the stringification process at string level

Latest version **0.1.0** (published 2018-12-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install json-stringifier
pnpm add json-stringifier
yarn add json-stringifier
bun add json-stringifier
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.0 |
| Published | 2018-12-24 |
| First published | 2018-12-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 13.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Daniel Lytkin |
| Maintainers | aikoven |
| Keywords | json, stringify, stringifier, memoize, cache, custom |

## Links

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

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.1.0 (latest) — 2018-12-24

## README

# json-stringifier [![npm version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url]

Alternative to `JSON.stringify()` that supports altering the behavior of the
stringification process at string level.

## Rationale

It's common to use objects in immutable fashion. We could optimize the
serialization of these objects by caching their JSON representation. However,
there's no way to achieve this using built-in `JSON.stringify()` function: its
[`replacer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter)
parameter only allows substituting serialized values, but not resulting strings.
`stringify()` function provided by this library accepts a `stringifier`
parameter that lets us override the stringification of values in the object
tree. See [Memoization](#Memoization) example.

Another use case is when you have a strict schema for some objects inside your
object tree. With this library you can use
[`fast-json-stringify`](https://github.com/fastify/fast-json-stringify) for
these objects and the regular stringification for the rest.

## Installation

    $ npm install json-stringifier

## Examples

### Memoization

Custom stringifier that memoizes JSON representations of objects:

```js
import {stringify} from 'json-stringifier';

const cache = new WeakMap();

function memoizedStringify(value) {
  if (value !== null && typeof value === 'object') {
    if (cache.has(value)) {
      return cache.get(value);
    } else {
      const json = stringify(value, memoizedStringify);

      cache.set(value, json);

      return json;
    }
  }

  return stringify(value, memoizedStringify);
}

let state = {
  obj: {a: 1},
  arr: [1, 2, 3],
};

memoizedStringify(state); // '{"obj":{"a":1},"arr":[1,2,3]}'

state = {
  ...state,
  arr: [4, 5, 6],
};

memoizedStringify(state); // state.obj stringification is bypassed
```

### Handling Circular References

Custom stringifier that handles circular references:

```js
function safeStringify(value, seen) {
  if (value !== null && typeof value === 'object') {
    if (seen && seen.has(value)) {
      return '"<circular>"';
    }

    if (seen == null) {
      seen = new Set();
    }
    seen.add(value);

    const json = stringify(value, child => safeStringify(child, seen));

    seen.delete(value);

    return json;
  }

  return stringify(value);
}

const obj = {};
obj.self = obj;
obj.child = {parent: obj};

safeStringify(obj); // '{"self":"<circular>","child":{"parent":"<circular>"}}'
```

### Support Additional Structures

Custom stringifier that supports Sets and Maps:

```js
function customStringify(value) {
  if (value instanceof Set) {
    return stringify({'@@type': 'Set', values: [...value]}, customStringify);
  }

  if (value instanceof Map) {
    return stringify({'@@type': 'Map', entries: [...value]}, customStringify);
  }

  return stringify(value, customStringify);
}

customStringify({
  set: new Set([1, 2, 3]),
  map: new Map([[1, 'a'], [2, 'b'], [3, 'c']])),
});
// '{"set":{"@@type":"Set","values":[1,2,3]},"map":{"@@type":"Map","entries":[[1,"a"],[2,"b"],[3,"c"]]}}'
```

## API

`stringifier(value, stringify = stringifier)`

- `value` — The value to convert to a JSON string.
- `stringify` (optional) — A function that is called to get the JSON string for
  each property value when `value` is an object, or each element when `value` is
  an array. `stringify` is called with a single argument — the property value or
  array element and must return a string or `undefined`. Note that `stringify`
  is not called with the `value` itself. Defaults to `stringifier`, which gives
  recursive stringification.
- Returns a JSON string representing the given value or `undefined` if `value`
  is `undefined`, a function or a symbol.

## Comparison with JSON.stringify()

`stringify(value)` behaves mostly the same as `JSON.stringify(value)` with few
exceptions:

- [`toJSON()`](<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior>)
  is always called with no arguments.
- Primitive wrapper types `Boolean`, `Number` and `String` are not supported
  (yet).

[npm-image]: https://badge.fury.io/js/json-stringifier.svg
[npm-url]: https://badge.fury.io/js/json-stringifier
[travis-image]: https://travis-ci.org/aikoven/json-stringifier.svg?branch=master
[travis-url]: https://travis-ci.org/aikoven/json-stringifier

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