JSONC Simple Parser

Common errors

• SyntaxError: Unexpected token / in JSON at position X

  cause Attempting to parse a JSONC string (with comments) using the native `JSON.parse()` instead of `JSONC.parse()`.
  fix Replace `JSON.parse(jsoncString)` with `JSONC.parse(jsoncString)`.

• TypeError: Cannot read properties of undefined (reading 'parse')

  cause Incorrectly importing or accessing the `parse` method, often when trying to use CommonJS `require` with an ESM-first default export without accessing the `.default` property.
  fix Ensure you are using `import JSONC from 'jsonc-simple-parser';` for ESM, or if in CommonJS, try `const JSONC = require('jsonc-simple-parser').default;` (though ESM `import` is recommended).

• TS2307: Cannot find module 'jsonc-simple-parser' or its corresponding type declarations.

  cause The package is not installed, or TypeScript is unable to resolve the module path or its type definitions.
  fix Run `npm install jsonc-simple-parser` or `yarn add jsonc-simple-parser`. Ensure your `tsconfig.json` has `moduleResolution` set appropriately (e.g., `bundler` or `node16`) and that the module is correctly referenced in your import statements.

Warnings

• breaking Major version 3.0.0 was released, which typically indicates breaking changes. While the README does not explicitly list them, users should consult the package's GitHub releases or changelog for specific migration details.
  Fix: Review the official changelog or release notes for `jsonc-simple-parser` v3.0.0 on its GitHub repository to understand any API changes or behavioral modifications and update your code accordingly.
• gotcha The `JSONC.stringify()` method behaves identically to the native `JSON.stringify()`. This means that any comments or trailing commas that were present in the original JSONC string will be removed during the stringification process.
  Fix: If you need to preserve comments or trailing commas, `jsonc-simple-parser` does not provide this functionality on stringification. Consider alternative approaches or other libraries if comment preservation is a requirement for output.
• gotcha While `jsonc-simple-parser` correctly parses JSON with comments and trailing commas, it is not strictly compliant with the ECMA-404 JSON specification, as the native JSON spec does not allow these features. This is by design, as it implements the 'JSONC' (JSON with Comments) standard.
  Fix: Be aware that output generated by `JSONC.stringify` (which is standard JSON) will lose these non-standard features. Ensure downstream systems expecting strict JSON will not encounter issues if you manually re-introduce comments for human readability.

Install

• npm install jsonc-simple-parser npm
• yarn add jsonc-simple-parser yarn
• pnpm add jsonc-simple-parser pnpm

Imports

• JSONC
  wrong:

  const JSONC = require('jsonc-simple-parser');

  correct:

  import JSONC from 'jsonc-simple-parser';

  The primary API is exposed as a default export, primarily designed for ESM. Direct CommonJS `require` might lead to accessing `.default`.
• parse
  wrong:

  import { parse } from 'jsonc-simple-parser';

  correct:

  import JSONC from 'jsonc-simple-parser';
  const parsed = JSONC.parse(source);

  The `parse` function is a method of the default `JSONC` export, not a named export itself.
• stringify
  wrong:

  import { stringify } from 'jsonc-simple-parser';

  correct:

  import JSONC from 'jsonc-simple-parser';
  const str = JSONC.stringify(data);

  Like `parse`, `stringify` is a method of the default `JSONC` export. It behaves identically to `JSON.stringify`.

Quickstart

Demonstrates parsing a JSONC string containing comments and trailing commas, and then stringifying a plain object back to standard JSON.

import JSONC from 'jsonc-simple-parser';

const source = `
  { // This is an example comment
    "name": "Alice",
    "age": 30,
    /* This is another comment */
    "tags": ["developer", "js", "ts",],
  }
`;

// Parse the JSONC string into a JavaScript object
const parsedObject = JSONC.parse(source);

console.log('Parsed Object:', parsedObject);
/* Expected output:
{
  name: 'Alice',
  age: 30,
  tags: [ 'developer', 'js', 'ts' ]
}
*/

// Stringify a JavaScript object back to a JSON string (comments will be lost)
const dataToSave = { userId: 123, settings: { theme: 'dark' } };
const jsonString = JSONC.stringify(dataToSave, null, 2);

console.log('Stringified JSON:', jsonString);