npm package: @interaktiv/json
Description: JSON related utilities for Javascript at DIA
Author: die.interaktiven GmbH & Co. KG
Latest version: 1.0.0

# @interaktiv/json

> JSON related utilities for Javascript at [DIA][dia-website]

[![Commitizen friendly][commitizen-badge]][commitizen]
[![Conventional Commits][conventional-commits-badge]][conventional-commits]
[![Semantic Release][semantic-release-badge]][semantic-release]
[![Code of Conduct][coc-badge]][coc] [![MIT License][license-badge]][license]

[![npm latest version][latest-version-badge]][package]
[![npm next version][next-version-badge]][package]

## This Solution

This library includes a high level support for parsing and working with JSON
data.

## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Installation](#markdown-header-installation)
- [API](#markdown-header-api)
  - [cloneJson](#markdown-header-clonejson)
  - [getJsonValuesByName](#markdown-header-getjsonvaluesbyname)
  - [isJson](#markdown-header-isjson)
  - [jsonIncludes](#markdown-header-jsonincludes)
  - [parseJson](#markdown-header-parsejson)
  - [parseJsonMap](#markdown-header-parsejsonmap)
- [References](#markdown-header-references)
- [Other Use Cases](#markdown-header-other-use-cases)
- [Acknowledgements](#markdown-header-acknowledgements)
- [License](#markdown-header-license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation

This module can be installed via [npm][npm-cli] which is bundled with
[Node.js][node] and should be installed as one of your project's
[dependencies][]:

```bash
npm install --save @interaktiv/json
```

## API

### cloneJson

Perform a deep clone of an object or array compatible with JSON stringification.
Object fields that are not compatible with stringification will be omitted.
Array entries that are not compatible with stringification will be censored as
null.

`throws` JsonStringifyError If the object contains circular references or causes
other JSON stringification errors.

```javascript
cloneJson(obj): obj
```

### getJsonValuesByName

Finds all elements with a given name in a JsonMap. Not suitable for use with
object graphs containing circular references. The specification of an
appropriate type that will satisfy all matching element values is the
responsibility of the caller.

```javascript
getJsonValuesByName(json: obj, name: string): obj[]
```

### isJson

Tests wether the given string is a JSON stringified string or not.

```javascript
isJson(str: string): boolean
```

### jsonIncludes

Tests whether an any JSON value contains another any JSON value. This is a
shallow check only and does not recurse deeply into collections.

```javascript
jsonIncludes(json: obj, value: obj): boolean
```

### parseJson

Parse JSON string data.

`throws` JsonParseError If the data contents are empty or the data is invalid.

```javascript
parseJson(data: string, jsonPath?: undefined | string, throwOnEmpty?: boolean): AnyJson
```

### parseJsonMap

Parse JSON string data, expecting the result to be an object.

`throws` JsonParseError If the data contents are empty or the data is invalid.

`throws` JsonDataFormatError If the data contents are not a JsonMap.

```javascript
parseJsonMap(data: string, jsonPath?: undefined | string, throwOnEmpty?: undefined | false | true): obj
```

## References

This library is using custom error types and type narrowing from
[@interaktiv/errors][interaktiv-errors] and
[@interaktiv/types][interaktiv-types].

## Other Use Cases

If you lack some use cases, you are welcome to open a pull request and add it.
We'll come back to you and see how we can support your use case and present it
to all devs.

Please consult the [contribution guides][contributing] before contributing.

## Acknowledgements

This library is inspired by [@salesforce/kit][salesforce-kit]. Thank you 💙

## License

[MIT][license] Copyright © 2019-present [die.interaktiven GmbH & Co.
KG][dia-website]

[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg
[coc]: ./other/CODE_OF_CONDUCT.md
[commitizen]: http://commitizen.github.io/cz-cli
[commitizen-badge]:
  https://img.shields.io/badge/commitizen-friendly-brightgreen.svg
[contributing]: ./CONTRIBUTING.md
[conventional-commits]: https://conventionalcommits.org
[conventional-commits-badge]:
  https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg
[dependencies]:
  https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file
[dia-website]: https://die-interaktiven.de
[downloads-badge]: https://img.shields.io/npm/dw/@interaktiv/json.svg
[downloads-total-badge]: https://img.shields.io/npm/dt/@interaktiv/json.svg
[interaktiv-errors]: https://www.npmjs.com/package/@interaktiv/errors
[interaktiv-types]: https://www.npmjs.com/package/@interaktiv/types
[latest-version-badge]: https://img.shields.io/npm/v/@interaktiv/json/latest.svg
[license]: https://opensource.org/licenses/MIT
[license-badge]: https://img.shields.io/npm/l/@interaktiv/json.svg
[next-version-badge]: https://img.shields.io/npm/v/@interaktiv/json/next.svg
[package]: https://npmjs.com/package/@interaktiv/json
[node]: https://nodejs.org
[npm]: https://www.npmjs.com
[npm-cli]: https://www.npmjs.com/package/npm
[salesforce-kit]: https://www.npmjs.com/package/@salesforce/kit
[semantic-release]: https://github.com/semantic-release/semantic-release
[semantic-release-badge]:
  https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[version-badge]: https://img.shields.io/npm/v/@interaktiv/json.svg