Character Parser for Template Snippets

Common errors

• ERR_PACKAGE_PATH_NOT_EXPORTED

  cause Attempting to import a module from an internal path (e.g., `character-parser/lib/util`) instead of the main package export.
  fix Change the import path to reference only the main package: `import { someExport } from 'character-parser'`.

• TypeError: parse is not a function

  cause Trying to use CommonJS `require()` for named exports in a context where `character-parser@4.0.0` is resolved as an ES Module, or attempting a default import for a named export.
  fix Use ES module named imports: `import { parse, parseUntil } from 'character-parser'`. Ensure your environment supports ES Modules or transpile accordingly.

• CHARACTER_PARSER:UNTERMINATED_STRING

  cause The input JavaScript snippet contains an unclosed string literal.
  fix Review the input string for syntax errors, specifically ensuring all string delimiters (single quotes, double quotes, backticks) are properly matched and escaped where necessary.

Warnings

• breaking Version 4.0.0 removed official support for Flow types. While the library itself is written in TypeScript and ships with TypeScript types, Flow users will need to manage their own type definitions or downgrade.
  Fix: Migrate to TypeScript for type safety, or rely on custom Flow definitions if still using Flow.
• breaking The `package.json` now includes an `exports` field, which restricts available imports to only the main entry point (`'character-parser'`). Importing arbitrary internal files (e.g., `character-parser/lib/some-internal-file`) is no longer supported and will result in module resolution errors in environments that respect the `exports` field.
  Fix: Ensure all imports are from the main package path: `import { NamedExport } from 'character-parser'`. Do not attempt to import from internal directories.
• gotcha All parsing methods (`parse`, `parseUntil`, `parseChar`) may throw exceptions in case of syntax errors (e.g., unclosed brackets or strings). These exceptions contain a `code` property prefixed with `CHARACTER_PARSER:` for specific error identification.
  Fix: Wrap parsing operations in `try...catch` blocks to gracefully handle and identify syntax errors. Inspect the `error.code` property for specific error types.
• gotcha When using `parse()` to process a string in multiple sections, it is critical to pass the `state` object returned by the previous `parse()` call to the subsequent call. Failing to do so will reset the parser's internal state (e.g., stack of open brackets, in-string status), leading to incorrect parsing results.
  Fix: Always chain `parse()` calls by passing the state: `let state = parse(firstPart); state = parse(secondPart, state);`.

Install

• npm install character-parser npm
• yarn add character-parser yarn
• pnpm add character-parser pnpm

Imports

• parse
  wrong:

  const parse = require('character-parser').parse

  correct:

  import { parse } from 'character-parser'

  Since v4.0.0, the package primarily supports ES Modules. CommonJS require() is not officially supported via the package.json exports field for named exports.
• parseUntil
  wrong:

  import parseUntil from 'character-parser/parseUntil'

  correct:

  import { parseUntil } from 'character-parser'

  The v4.0.0 update introduced an 'exports' field in package.json, restricting imports to only the main entry point 'character-parser'. Direct imports of internal files are no longer supported.
• defaultState
  wrong:

  const { defaultState } = require('character-parser')

  correct:

  import { defaultState } from 'character-parser'

  TypeScript types are included, ensuring strong typing when used in TypeScript projects. ES module imports are the recommended way to use the library.

Quickstart

This quickstart demonstrates how to use `character-parser` to find delimited expressions and manage parsing state across multiple string segments, including handling nested structures and escaped characters.

import { parseUntil, parse } from 'character-parser';
import assert from 'assert';

console.log('--- Custom Delimited Expressions (EJS-style) ---');
// Example 1: Parsing up to a custom delimiter (EJS-style)
const ejsSnippet = 'foo.bar("%>\").baz%> bing bong';
const section1 = parseUntil(ejsSnippet, '%>');
assert.strictEqual(section1.start, 0);
assert.strictEqual(section1.end, 18);
assert.strictEqual(section1.src, 'foo.bar("%>\").baz');
console.log(`Parsed section 1: "${section1.src}" (Start: ${section1.start}, End: ${section1.end})`);

const ejsSnippetOffset = '<%foo.bar("%>\").baz%> bing bong';
const section2 = parseUntil(ejsSnippetOffset, '%>', { start: 2 });
assert.strictEqual(section2.start, 2);
assert.strictEqual(section2.end, 20);
assert.strictEqual(section2.src, 'foo.bar("%>\").baz');
console.log(`Parsed section 2 with offset: "${section2.src}" (Start: ${section2.start}, End: ${section2.end})`);

console.log('\n--- Parsing Depth Changes ---');
// Example 2: Parsing depth changes with state management
let state = parse('foo(arg1, arg2, {\n  foo: [a, b\n');
console.log('Initial stack after first parse:', state.stack);
assert.deepStrictEqual(state.stack, [')', '}', ']']);

state = parse('    c, d]\n  })', state);
console.log('Final stack after second parse:', state.stack);
assert.deepStrictEqual(state.stack, []);

console.log('\nAll assertions passed!');