lossless-json

To generate a bundled and minified ES5 library (including an ES module and a UMD bundle for browsers and Node.js), follow these steps:

1. Install dependencies: npm install
2. Run the build command: npm run build

The output will be located in the ./.lib folder.

To release a new version of the package, use the release command. This automation performs linting, testing, building, version incrementing, git tagging, and publishing to npm.

To preview the changes and the release process without actually publishing to npm, use the dry run command.

# Perform a full release
npm run release

# Preview the release without publishing
npm run release-dry-run

Use parse and stringify from lossless-json to ensure that large numbers and specific numeric formatting are preserved during the serialization/deserialization process. This prevents the precision loss common with native JSON.parse when dealing with long values or extremely large/small exponents.

import { parse, stringify } from 'lossless-json'

const text = '{"decimal":2.370,"long":9123372036854000123,"big":2.3e+500}'

// LosslessJSON.parse will preserve all numbers and even the formatting:
const json = parse(text)
console.log(stringify(json))
// '{"decimal":2.370,"long":9123372036854000123,"big":2.3e+500}'

Install the library using npm to begin parsing JSON without losing numeric precision.

npm install lossless-json

You can use the reviveDate helper as a reviver function in parse() to automatically convert ISO 8601 strings into JavaScript Date objects.

Warning: This is not enabled by default because it might accidentally convert non-date text fields into Date objects.

import { parse, reviveDate } from 'lossless-json';

const data = parse('["2022-08-25T09:39:19.288Z"]', reviveDate);
// output: [ new Date('2022-08-25T09:39:19.288Z') ]

If you want to parse JSON into regular JavaScript number types but want to ensure no precision is lost, use a custom numberParser combined with the isSafeNumber utility. If a number is found that cannot be safely represented as a native number, you can throw an error.

import { parse, isSafeNumber } from 'lossless-json'

const options = {
  parseNumber: (value) => {
    if (!isSafeNumber(value)) {
      throw new Error(`Cannot safely convert value '${value}' into a number`)
    }
    return parseFloat(value)
  }
}

// Success if all values are safe
let json = parse('[1,2,3]', undefined, options)

// Throws error for unsafe values
try {
  let json = parse('[1,2e+500,3]', undefined, options)
} catch (err) {
  console.log(err) // throws Error 'Cannot safely convert value '2e+500' into a number'
}

Use LosslessJSON.parse(text [, reviver [, options]]) to parse a JSON string. Unlike native JSON.parse, this function defaults to parsing all numeric values into LosslessNumber objects to prevent precision loss.

Parameters:

• text: The JSON string to parse.
• reviver (optional): A function (key, value) => unknown to transform values after parsing.
• options (optional): An object to customize number parsing and duplicate key handling.

Throws: SyntaxError if the string is not valid JSON.

import { parse } from 'lossless-json';

const data = parse('{"number": "123.456"}');
// data.number is a LosslessNumber instance

To use lossless-json with external BigNumber libraries, you must define both a parseNumber function for parse() and a custom stringifier for stringify(). The stringifier requires a test function to identify the type and a stringify function to convert it back to a string.

import { parse, stringify } from 'lossless-json'
import Decimal from 'decimal.js'

const parseDecimal = (value) => new Decimal(value)

const decimalStringifier = {
  test: (value) => Decimal.isDecimal(value),
  stringify: (value) => value.toString()
}

const text = '{"value":2.3e500}'
const json = parse(text, undefined, { parseNumber: parseDecimal })

const output = {
  result: json.value.times(2)
}

const str = stringify(output, undefined, undefined, [decimalStringifier])
// '{"result":4.6e500}'

You can customize how numbers are parsed by providing a numberParser in the options object. A common pattern is to parse integer values into native JavaScript bigint and other values into regular number types. You can use utility functions like isInteger to implement this logic.

import { parse, isInteger } from 'lossless-json'

const options = {
  // parse integer values into a bigint, and use a regular number otherwise
  numberParser: (value) => {
    return isInteger(value) ? BigInt(value) : parseFloat(value)
  }
}

const text = '[123456789123456789123456789, 2.3, 123]'
const json = parse(text, null, options)
// output: [123456789123456789123456789n, 2.3, 123n]