jsonc-parser

jsonc-parser is Microsoft’s scanner and parser for JSONC — JSON extended with JavaScript-style comments and trailing commas — originally built to power JSON language support in VS Code. It exposes a low-level tokenizing scanner, a fault-tolerant parse() function that still returns a best-effort result on invalid input (while reporting errors separately), a SAX-style visit() callback API, and a parseTree() function that builds a hierarchical DOM with source offsets for every node.

Beyond parsing, the package includes format() and modify() APIs that compute textual edit operations for reformatting a document or inserting/removing/replacing a property or array item, plus applyEdits() to apply them — enabling tools to make targeted, whitespace-preserving edits to a JSON/JSONC file rather than re-serializing the whole document.

What You Get

• A low-level createScanner() tokenizer that yields tokens with offsets, line, and column information
• A fault-tolerant parse() function that returns a best-effort JS value plus a separate list of errors
• A SAX-style visit() API with callbacks for object/array boundaries, properties, literals, and comments
• parseTree() to build a hierarchical DOM (Node tree) with offsets, plus findNodeAtLocation/findNodeAtOffset/getLocation helpers to navigate it
• format() and modify() APIs that compute textual edit operations instead of requiring full re-serialization
• stripComments() utility to convert JSONC to plain JSON

Common Use Cases

• Parsing configuration files (tsconfig.json, VS Code settings/tasks/launch configs) that allow comments
• Building editor tooling — syntax highlighting, outline views, or diagnostics — over JSON/JSONC documents using the scanner or visitor APIs
• Programmatically inserting or updating a single property in a JSON config file while preserving existing formatting and comments
• Implementing IntelliSense or path-based navigation over JSON documents via getLocation/findNodeAtLocation

Under The Hood

Architecture — the package is layered around src/impl/scanner.ts (a character-level tokenizer emitting SyntaxKind tokens with offsets/line/column), src/impl/parser.ts (which drives the scanner to implement both the SAX-style visit() callbacks and the higher-level parse()/parseTree() entry points), src/impl/edit.ts (computes textual edit operations for modify()), and src/impl/format.ts (computes formatting edits); main.ts re-exports the public surface. Because parseTree()/parse() are both built on the same underlying scanner/parser pass, offset and line/column information stays consistent whether consumers want a full DOM or a lightweight streaming visit. Tech Stack — pure TypeScript compiled to an ESM-only package (type: module, single exports entry pointing at compiled lib/esm), with zero runtime dependencies; built with tsc, linted with the flat-config ESLint + @typescript-eslint, tested via Node’s built-in --test runner rather than a separate test framework. Code Quality — src/test/ has dedicated suites for JSON parsing (json.test.ts), editing (edit.test.ts), formatting (format.test.ts), and the string-interning optimization (string-intern.test.ts); the prepack script enforces compile+test+lint before any publish, and a string-intern.ts module exists specifically to reduce allocation overhead for repeated property-name strings during parsing of large documents. API Design — the API separates concerns cleanly (scan vs. visit vs. parse vs. parseTree vs. edit) so consumers only pull in as much machinery as they need; fault tolerance is explicit rather than implicit — parse() takes an optional errors output array so callers must consciously choose to inspect parse errors, and JSDoc comments on every exported function/interface make the library usable directly from editor tooltips without external docs.