chore(release): release v2.0.0 [skip ci]

CHANGELOG.md

@@ -1,3 +1,22 @@
+## [2.0.0](https://github.com/Kit-p/json-kit/compare/v1.1.1...v2.0.0) (2023-07-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* **signature:** CHANGES
+
+### Features
+
+* **serialize:** add generic type and typeGuard parameter to serialize and deserialize ([6542bf6](https://github.com/Kit-p/json-kit/commit/6542bf6afee31b8066cc8ff66320a7986e2e482d))
+* **serialize:** serialize and deserialize ([#42](https://github.com/Kit-p/json-kit/issues/42)) ([0c008fe](https://github.com/Kit-p/json-kit/commit/0c008fefcea5fb49b93c2e1aae45fab2e674abd7))
+* **signature:** provide overloads for stringify and parse ([95ef4b8](https://github.com/Kit-p/json-kit/commit/95ef4b86b74195c5651784e54d471dfe12ce7a93))
+
+
+### Bug Fixes
+
+* **serialize:** add missing return type ([04577d3](https://github.com/Kit-p/json-kit/commit/04577d35dcbe2a68b22b4c86897bd8e14d3e7525))
+* **types:** use namespace export for better consumption ([759eaa7](https://github.com/Kit-p/json-kit/commit/759eaa7024a0d4d91f7d4682f78626a7878d92e9))
+
 ## [1.1.1](https://github.com/Kit-p/json-kit/compare/v1.1.0...v1.1.1) (2023-03-25)
 
 ### Bug Fixes

docs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

docs/README.md

@@ -0,0 +1,96 @@
+@kit-p/json-kit / [Exports](modules.md)
+
+<h1 align="center">json-kit</h1>
+
+<div align="center">
+  <a href="https://www.npmjs.com/package/@kit-p/json-kit">
+    <img
+      src="https://img.shields.io/npm/v/%40kit-p/json-kit"
+      alt="npm: @kit-p/json-kit"
+    />
+  </a>
+  <a>
+    <img
+      src="https://img.shields.io/github/languages/top/Kit-p/json-kit"
+      alt="languages: github.com/Kit-p/json-kit"
+    />
+  </a>
+  <a href="https://github.com/semantic-release/semantic-release">
+    <img
+      src="https://img.shields.io/badge/semantic--release-conventionalcommits-e10079?logo=semantic-release"
+      alt="semantic-release: conventionalcommits"
+    />
+  </a>
+  <a href="https://gitpod.io/#https://github.com/Kit-p/json-kit">
+    <img
+      src="https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod"
+      alt="Contribute with Gitpod"
+    />
+  </a>
+</div>
+
+<h3 align="center">JSON Toolkit for (de)serialization | (un)minification | (de)compression</h3>
+
+---
+
+## Project State
+
+> This project is in **maintenance** state. The APIs are stable.
+
+## Installation
+
+### For Node.js:
+
+- `npm install @kit-p/json-kit`
+- `yarn add @kit-p/json-kit`
+- `pnpm add @kit-p/json-kit`
+
+#### _CommonJS_
+
+```js
+const { JsonKit } = require("@kit-p/json-kit");
+```
+
+#### _ESM_
+
+```js
+import { JsonKit } from "@kit-p/json-kit";
+```
+
+### For browsers:
+
+#### _CommonJS_
+
+- ```html
+  <script src="https://cdn.jsdelivr.net/npm/@kit-p/json-kit"></script>
+  <script>
+    console.log(JsonKit);
+  </script>
+  ```
+- ```html
+  <script src="https://unpkg.com/@kit-p/json-kit"></script>
+  <script>
+    console.log(JsonKit);
+  </script>
+  ```
+
+#### _ESM_
+
+- ```html
+  <script type="module">
+    import { JsonKit } from "https://cdn.jsdelivr.net/npm/@kit-p/json-kit/+esm";
+  </script>
+  ```
+- ```html
+  <script type="module">
+    import { JsonKit } from "https://unpkg.com/@kit-p/json-kit?module";
+  </script>
+  ```
+
+## Usage
+
+See [the documentation site](https://kit-p.github.io/json-kit/modules.html) or [the repository Wiki page](https://github.com/Kit-p/json-kit/wiki/Exports) or `docs/modules.md`.
+
+## License
+
+[MIT](https://github.com/Kit-p/json-kit/blob/main/LICENSE)

docs/modules.md

@@ -0,0 +1,11 @@
+[@kit-p/json-kit - v2.0.0](README.md) / Exports
+
+# @kit-p/json-kit - v2.0.0
+
+A library to work with JSON and EJSON (Extended JSON).
+
+## Table of contents
+
+### Namespaces
+
+- [JsonKit](modules/JsonKit.md)

docs/modules/JsonKit.Parse.md

@@ -0,0 +1,215 @@
+[@kit-p/json-kit - v2.0.0](../README.md) / [Exports](../modules.md) / [JsonKit](JsonKit.md) / Parse
+
+# Namespace: Parse
+
+[JsonKit](JsonKit.md).Parse
+
+## Table of contents
+
+### Type Aliases
+
+- [ParseOptions](JsonKit.Parse.md#parseoptions)
+- [ParseReviverFunction](JsonKit.Parse.md#parsereviverfunction)
+
+### Functions
+
+- [decompressString](JsonKit.Parse.md#decompressstring)
+- [parse](JsonKit.Parse.md#parse)
+
+## Type Aliases
+
+### ParseOptions
+
+Ƭ **ParseOptions**: `Object`
+
+Type for the `options` parameter of [parse](JsonKit.Parse.md#parse).
+
+#### Type declaration
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `decompress?` | `boolean` \| { `enable`: `boolean`  } | Specifies if the input string is compressed with [`lz4js.compress()`](https://github.com/Benzinga/lz4js/blob/73728a9c3c6a417ab9ce622fa112dc1cf04b00fd/lz4.js#L557). **`Remarks`** Will automatically disable if the decompression fails. **`Default Value`** `true` |
+| `extended?` | `boolean` \| { `enable`: `boolean` ; `relaxed?`: `boolean`  } | Specifies if the input string is in JSON or EJSON format, additional options to be passed into [`bson.EJSON.parse()`](https://github.com/mongodb/js-bson#ejsonparsetext-options) can be supplied with the long form (only effective if `enable` is `true`. **`Default Value`** `false` |
+| `unminify?` | `boolean` \| { `enable`: `boolean` ; `keyMap?`: `Record`<`string`, `string`\>  } | Specifies if the input string is created with the `minify` option enabled in [stringify](JsonKit.Stringify.md#stringify), a custom key map (shortened:original) can be supplied with the long form (only effective if `enable` is `true`. **`Remarks`** Will automatically disable if the unminifcation fails. **`Default Value`** `true` |
+
+#### Defined in
+
+[parse.ts:22](https://github.com/Kit-p/json-kit/blob/af9e51f/src/parse.ts#L22)
+
+___
+
+### ParseReviverFunction
+
+Ƭ **ParseReviverFunction**: (`this`: `any`, `key`: `string`, `value`: `any`) => `any`
+
+#### Type declaration
+
+▸ (`this`, `key`, `value`): `any`
+
+Type for the `reviver` parameter of [parse](JsonKit.Parse.md#parse).
+Refer to [the MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#the_reviver_parameter) for more details.
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `this` | `any` |
+| `key` | `string` |
+| `value` | `any` |
+
+##### Returns
+
+`any`
+
+#### Defined in
+
+[parse.ts:12](https://github.com/Kit-p/json-kit/blob/af9e51f/src/parse.ts#L12)
+
+## Functions
+
+### decompressString
+
+▸ **decompressString**(`str`): `string`
+
+Decompresses a string with [`lz4js.decompress()`](https://github.com/Benzinga/lz4js/blob/73728a9c3c6a417ab9ce622fa112dc1cf04b00fd/lz4.js#L538).
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `str` | `string` | The input string |
+
+#### Returns
+
+`string`
+
+str - The decompressed string
+
+#### Defined in
+
+[parse.ts:352](https://github.com/Kit-p/json-kit/blob/af9e51f/src/parse.ts#L352)
+
+___
+
+### parse
+
+▸ **parse**<`T`\>(`text`, `reviver?`, `options?`, `typeGuard?`): `T`
+
+Turns the input string into an object.
+
+**`Remarks`**
+
+With the custom options, the input string can be either
+ - a JSON string (identical to [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse))
+ - an EJSON string (identical to [`bson.EJSON.parse()`](https://github.com/mongodb/js-bson#ejsonparsetext-options))
+ - a minified version of either of the above, where some or specified keys are replaced with a shorter identifier
+ - a compressed version (by [`lz4js.compress()`](https://github.com/Benzinga/lz4js/blob/73728a9c3c6a417ab9ce622fa112dc1cf04b00fd/lz4.js#L557)) of either of the above
+
+**`Example`**
+
+```ts
+type Foo {
+  long_key: string
+}
+
+parse<Foo>(
+  "{\"lk\":\"A Large Object\"}",
+  (key, val) => {
+    if (key === "lk") {
+      return "A Modified Large Object"
+    }
+    return val
+  },
+  {
+    extended: false,
+    unminify: { enable: true, keyMap: { "lk": "long_key" } },
+    decompress: false
+  },
+  (obj: any): obj is Foo => {
+    const _obj: Partial<Foo> | null | undefined = obj
+    return typeof _obj?.long_key === "string"
+  }
+)
+```
+
+#### Type parameters
+
+| Name | Description |
+| :------ | :------ |
+| `T` | Type of the output object |
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `text` | `string` | The input string |
+| `reviver?` | ``null`` \| [`ParseReviverFunction`](JsonKit.Parse.md#parsereviverfunction) | The `reviver` parameter of [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#the_reviver_parameter) |
+| `options?` | ``null`` \| [`ParseOptions`](JsonKit.Parse.md#parseoptions) | The custom options, refer to [ParseOptions](JsonKit.Parse.md#parseoptions) for details |
+| `typeGuard?` | [`TypeGuardFunction`](JsonKit.Types.md#typeguardfunction)<`T`\> | The type guard function, ensures that the output object is of the expected type, refer to [TypeGuardFunction](JsonKit.Types.md#typeguardfunction) for an example. |
+
+#### Returns
+
+`T`
+
+The output object
+
+#### Defined in
+
+[parse.ts:185](https://github.com/Kit-p/json-kit/blob/af9e51f/src/parse.ts#L185)
+
+▸ **parse**<`T`\>(`text`, `options?`, `typeGuard?`): `T`
+
+Turns the input string into an object.
+
+**`Remarks`**
+
+With the custom options, the input string can be either
+ - a JSON string (identical to [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse))
+ - an EJSON string (identical to [`bson.EJSON.parse()`](https://github.com/mongodb/js-bson#ejsonparsetext-options))
+ - a minified version of either of the above, where some or specified keys are replaced with a shorter identifier
+ - a compressed version (by [`lz4js.compress()`](https://github.com/Benzinga/lz4js/blob/73728a9c3c6a417ab9ce622fa112dc1cf04b00fd/lz4.js#L557)) of either of the above
+
+**`Example`**
+
+```ts
+type Foo {
+  long_key: string
+}
+
+parse<Foo>(
+  "{\"lk\":\"A Large Object\"}",
+  {
+    extended: false,
+    unminify: { enable: true, keyMap: { "lk": "long_key" } },
+    decompress: false
+  },
+  (obj: any): obj is Foo => {
+    const _obj: Partial<Foo> | null | undefined = obj
+    return typeof _obj?.long_key === "string"
+  }
+)
+```
+
+#### Type parameters
+
+| Name | Description |
+| :------ | :------ |
+| `T` | Type of the output object |
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `text` | `string` | The input string |
+| `options?` | ``null`` \| [`ParseOptions`](JsonKit.Parse.md#parseoptions) | The custom options, refer to [ParseOptions](JsonKit.Parse.md#parseoptions) for details |
+| `typeGuard?` | [`TypeGuardFunction`](JsonKit.Types.md#typeguardfunction)<`T`\> | The type guard function, ensures that the output object is of the expected type, refer to [TypeGuardFunction](JsonKit.Types.md#typeguardfunction) for an example. |
+
+#### Returns
+
+`T`
+
+The output object
+
+#### Defined in
+
+[parse.ts:230](https://github.com/Kit-p/json-kit/blob/af9e51f/src/parse.ts#L230)