Registry / serialization / character-parser

character-parser

library4.0.0jsnpmunverified

`character-parser` is a focused JavaScript utility library designed for parsing JavaScript code snippets, particularly within template languages like EJS or Jade. Its primary function is to robustly handle bracket nesting, strings, and comments, allowing for the reliable extraction of delimited JavaScript sections without performing a full syntax validation or abstract syntax tree (AST) generation. The current stable version is 4.0.0, which introduced significant changes including native ES module support and updated package export configurations. This library differentiates itself by offering a lightweight, character-by-character parsing mechanism and state management, providing functions to parse entire strings or single characters, track nesting depth, and find code segments based on custom delimiters while intelligently ignoring content within nested structures or comments. It does not aim to be a comprehensive JavaScript parser but rather a precise tool for template-driven code extraction.

serialization

npm install character-parser

github ↗package ↗

INSTALL

IMPORT

SIG · CHARACTER-PARSER

character-parser

serializationjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'character-parser'

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

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

✓ import { parseUntil } from 'character-parser'

✗ import parseUntil from 'character-parser/parseUntil'

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

✓ import { defaultState } from 'character-parser'

✗ const { defaultState } = require('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.

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!');

Debug

Known issues

breakingVersion 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.

affects: >=4.0.0

breakingThe `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.

affects: >=4.0.0

gotchaAll 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.

affects: >=1.0.0

gotchaWhen 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);`.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_PACKAGE_PATH_NOT_EXPORTED

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

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

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.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ForbesLindesay/character-parser ↗

packagehttps://www.npmjs.com/package/character-parser ↗