@croct/json5-parser

JSON5 Parser
A lossless JSON5 tokenizer and parser for Node.js that maintains indentation, spacing, and comments.

📦 Releases · 🐞 Report Bug · ✨ Request Feature

Overview

This library provides an API for working with JSON and JSON5 documents while preserving their original structure and formatting. Unlike traditional JSON parsers that use an Abstract Syntax Tree (AST) and discard formatting, this library leverages a Concrete Syntax Tree (CST) to retain every detail—comments, indentation, and whitespace.

Ideal for editing configuration files (e.g., package.json, tsconfig.json) or any user-generated JSON5 content, this library ensures that formatting remains intact throughout modifications.

Key features

• Preserve formatting – Read, modify, and write JSON5 files without losing comments, indentation, or spacing.
• Style learning – Automatically applies the document's existing formatting style to new entries.
• Reformatting – Customize output formatting with flexible options.
• Type Safety – Fully typed API for working with JSON5 documents.

Installation

Install via NPM:

npm install @croct/json5-parser

Usage

The library provides a simple API for parsing, manipulating, and serializing JSON5 documents.

Lexing

Usually, you don't need to interact with the lexer directly. However, you can use it to tokenize a JSON5 document:

import {JsonLexer} from '@croct/json5-parser';

const tokens = JsonLexer.tokenize(
    `{
        // Comment
        "name": "John Doe",
        "age": 42,
    }`
);

Parsing

To parse a JSON5 document:

import {JsonParser} from '@croct/json5-parser';

const node = JsonParser.parse(
    `{
        // Comment
        "name": "John Doe",
        "age": 42,
    }`
);

Optionally, specify the expected root node type to narrow down the result:

import {JsonParser, JsonObjectNode} from '@croct/json5-parser';

const node = JsonParser.parse(
    `{
        // Comment
        "name": "John Doe",
        "age": 42,
    }`,
    JsonObjectNode
);

Manipulation

Modify values while preserving formatting:

// Get the value of a property
const name = node.get('name').toJSON();

// Update a property
node.set('age', 43);

console.log(node.toString());

New entries adopt the document's existing style:

node.set('country', 'USA');

console.log(node.toString());

Output:

{
    // Comment
    "name": "John Doe",
    "age": 43,
    "country": "USA",
}

Formatting is applied at a block level, handling different styles within the same document:

{
  "name": "My Project",
  "version": "1.0.0",
  "keywords": ["json5", "parser"],
}

Adding an array entry keeps the existing format:

node.set('stack', ['react', 'typescript']);

Output:

{
  "name": "My Project",
  "version": "1.0.0",
  "keywords": ["json5", "parser"],
  "stack": ["react", "typescript"],
}

To reset formatting and apply a new style:

node.reset();

console.log(node.toString({ indentationLevel: 2 }));

Output:

{
  "name": "My Project",
  "version": "1.0.0",
  "keywords": [
    "json5",
    "parser"
  ],
  "stack": [
    "react",
    "typescript"
  ]
}

To update the document while preserving formatting, use the update method:

node.update({
    ...node.toJSON(),
    "version": "2.0.0",
});

The update method reconciles the new content with the existing document, preserving comments, indentation, and spacing.

For single updates, prefer the set method for better performance:

node.set('version', '2.0.0');

To merge two documents while preserving comments and formatting from both, use the merge method:

const destinationCode = `{
  // Destination pre-foo comment
  "foo": "value",
  // Destination post-foo comment
  "baz": [1, 2, 3]
}
`;

const sourceCode = `{
  /* Source pre-bar comment */
  "bar": 123, /* Inline comment */
  /* Source post-bar comment */
  "baz": true /* Another inline comment */
}
`;

const source = JsonParser.parse(sourceCode, JsonObjectNode);
const destination = JsonParser.parse(destinationCode, JsonObjectNode);

destination.merge(source)

console.log(destination.toString());

Output:

{
  // Destination pre-foo comment
  "foo": "value",
  /* Source pre-bar comment */
  "bar": 123, /* Inline comment */
  /* Source post-bar comment */
  "baz": true /* Another inline comment */
}

Contributing

Contributions are welcome!

• Report issues on the issue tracker.
• For major changes, open an issue first to discuss.
• Ensure test coverage is updated accordingly.

Testing

Install dependencies:

npm install

Run tests:

npm run test

Lint code to check for style issues:

npm run lint