npm package: @mainnet-pat/json-bigint
Description: JSON with BigInt support
Author: mainnet-pat
Latest version: 1.0.0

# @mainnet-pat/json-bigint

A lightweight JSON parser and stringifier with native BigInt literal support.

## Features

- **Strict JSON compliant** - Fully backwards compatible with the JSON specification
- **BigInt literals** - Parse and stringify BigInt values using the `123n` syntax
- **Drop-in replacement** - API mirrors native `JSON.parse()` and `JSON.stringify()`
- **Small footprint** - ~2.1 KB gzipped
- **TypeScript** - Written in TypeScript with full type definitions
- **Zero dependencies**

## Installation

```sh
yarn add @mainnet-pat/json-bigint
```

## Usage

### ESM

```js
import JSONBigInt from '@mainnet-pat/json-bigint'

// Parse JSON with BigInt literals
JSONBigInt.parse('{"value": 123n}')
// => { value: 123n }

// Parse large integers that exceed Number.MAX_SAFE_INTEGER
JSONBigInt.parse('{"big": 9007199254740993n}')
// => { big: 9007199254740993n }

// Stringify objects containing BigInt values
JSONBigInt.stringify({ count: 42n })
// => '{"count":42n}'
```

### CommonJS

```js
const JSONBigInt = require('@mainnet-pat/json-bigint')

JSONBigInt.parse('{"n": 999999999999999999n}')
// => { n: 999999999999999999n }
```

## API

The API is compatible with the native [JSON API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON).

### JSONBigInt.parse(text[, reviver])

Parses a JSON string with BigInt literal support.

**Parameters:**
- `text` - The string to parse as JSON
- `reviver` - Optional function to transform parsed values

**Returns:** The parsed JavaScript value

```js
// Basic parsing
JSONBigInt.parse('{"a": 1, "b": 2n}')
// => { a: 1, b: 2n }

// With reviver
JSONBigInt.parse('{"a": 1}', (key, value) =>
  typeof value === 'number' ? value * 2 : value
)
// => { a: 2 }
```

### JSONBigInt.stringify(value[, replacer[, space]])

Converts a JavaScript value to a JSON string with BigInt literal support.

**Parameters:**
- `value` - The value to stringify
- `replacer` - Optional function or array to filter/transform values
- `space` - Optional indentation (number of spaces or string)

**Returns:** A JSON string

```js
// Basic stringification
JSONBigInt.stringify({ x: 5n, y: 10 })
// => '{"x":5n,"y":10}'

// With indentation
JSONBigInt.stringify({ a: 1n }, null, 2)
// => '{\n  "a": 1n\n}'

// With replacer array
JSONBigInt.stringify({ a: 1, b: 2, c: 3 }, ['a', 'c'])
// => '{"a":1,"c":3}'
```

## Strict JSON Compliance

This library follows the JSON specification strictly. It does **not** support:

- Comments (`//` or `/* */`)
- Trailing commas (`[1, 2,]`)
- Unquoted property names (`{foo: 1}`)
- Single-quoted strings (`'hello'`)
- Hexadecimal numbers (`0xFF`)
- Infinity, -Infinity, NaN
- Leading/trailing decimal points (`.5` or `5.`)

The only extension to standard JSON is BigInt literal support (`123n`).

## Why?

JavaScript's `Number` type loses precision for integers larger than `Number.MAX_SAFE_INTEGER` (2^53 - 1). This is problematic when working with:

- Database IDs (e.g., Twitter/X snowflake IDs)
- Blockchain data (transaction hashes, token amounts)
- Financial systems requiring precise large integers
- Any system using 64-bit integers

```js
// Native JSON loses precision
JSON.parse('{"id": 9007199254740993}')
// => { id: 9007199254740992 } ❌ Wrong!

// json-bigint preserves precision
JSONBigInt.parse('{"id": 9007199254740993n}')
// => { id: 9007199254740993n } ✓ Correct!
```

## TypeScript

Full TypeScript definitions are included:

```ts
import JSONBigInt from '@mainnet-pat/json-bigint'

const data: { value: bigint } = JSONBigInt.parse('{"value": 123n}')
```

## Benchmark

Performance comparison with native `JSON` (operations per second, higher is better):

| Operation | Test Case | JSONBigInt | Native JSON | Ratio |
|-----------|-----------|------------|-------------|-------|
| Parse | Small object (37b) | 575K/s | 2,294K/s | 4.0x |
| Parse | Large object (9KB) | 10K/s | 19K/s | 1.9x |
| Stringify | Small object (37b) | 551K/s | 5,391K/s | 9.8x |
| Stringify | Large object (9KB) | 5K/s | 31K/s | 6.3x |

Native JSON is implemented in optimized C++ in V8. JSONBigInt is pure JavaScript with BigInt literal support.

Run benchmarks locally: `yarn benchmark`

## License

MIT