@gmb/bitmark-parser

@gmb/bitmark-parser

A high-performance parser for bitmark, powered by WebAssembly. Provides both a programmatic API and a CLI for converting between bitmark markup and JSON.

Installation

npm install @gmb/bitmark-parser

Programmatic API (Node.js)

import { convert, parse, lex, breakscapeText, unbreakscapeText, info, version } from "@gmb/bitmark-parser";

// Convert bitmark to JSON (auto-detects input format)
const json = convert("[.article]\nHello **bold**", { warnings: true });
const parsedJson = JSON.parse(json);
console.log(parsedJson[0].bit.type);
console.log(parsedJson[0].parser.warnings);
console.log(parsedJson[0].bitmark);

// Parse bitmark to JSON (same as convert for bitmark input)
const parsed = parse("[.article]\nHello **bold**", { mode: "full" });

// Lex bitmark to token dump
const tokens = lex("[.article]\nHello **bold**");

// Lex with a specific stage
const tokenJson = lex("[.article]\nHello **bold**", { stage: "lex-json" });

// Breakscape / unbreakscape text
const escaped = breakscapeText("[!example]", "bitmark++", "body");
const unescaped = unbreakscapeText(escaped, "bitmark++", "body");

// Query supported bit types
const bitInfo = info({ infoType: "list", format: "text" });

// Get library version
console.log(version());

API

convert(input: string, options?: ConvertOptions): string

Auto-detect input format and convert between bitmark and JSON.

Options (passed as a JSON string):

• mode — "optimized" (default) or "full"
• warnings — include validation warnings (default: false)
• plainText — output text as plain text (default: false)
• pretty — prettify JSON output (default: false)
• indent — indent size for pretty JSON (default: 2)

For bitmark input, output is a JSON array of entries with:

• bit — serialized bit payload
• parser — parser metadata and warnings
• bitmark — source bitmark text

parse(input: string, options?: ParseOptions): string

Parse bitmark text and return structured JSON entries (bit, parser, bitmark).

lex(input: string, stage?: string): string

Lex bitmark text and return one token per line.

Stages:

• "lex" — Unified lexer token stream (default)
• "lex-json" — Unified lexer token stream as JSON

breakscapeText(input: string, options?: BreakscapeOptions): string

Breakscape text (escape bitmark special characters).

• format — "bitmark++" (default) or "plainText"
• location — "body" (default) or "tag"

unbreakscapeText(input: string, options?: BreakscapeOptions): string

Unbreakscape text (unescape bitmark special characters).

• format — "bitmark++" (default) or "plainText"
• location — "body" (default) or "tag"

info(options?: InfoOptions): string

Query information about supported bit types.

• infoType — "list" (default), "bit", "all", or "deprecated"
• format — "text" (default) or "json"
• bit — filter to a specific bit type (when infoType is "bit")
• pretty — prettify JSON output (default: false)
• indent — indent size for pretty JSON (default: 2)

version(): string

Return the library version string.

generate(json: string): string

Generate bitmark text from JSON. Not yet implemented — throws an error.

CLI

The CLI binary is bitmark-parser-wasm.

# Convert bitmark to JSON (auto-detects format)
bitmark-parser-wasm convert input.bitmark
bitmark-parser-wasm convert input.bitmark -o output.json

# Convert JSON to bitmark
bitmark-parser-wasm convert input.json -o output.bitmark

# Convert with options
bitmark-parser-wasm convert input.bitmark --mode full --pretty --warnings

# Parse a bitmark file to JSON
bitmark-parser-wasm parse input.bitmark
bitmark-parser-wasm parse input.bitmark -o output.json
bitmark-parser-wasm parse input.bitmark --mode full

# Lex instead of parse
bitmark-parser-wasm parse --stage=lex input.bitmark

# Available stages: all (default), lex
bitmark-parser-wasm parse --stage=lex input.bitmark

# Breakscape / unbreakscape text
bitmark-parser-wasm breakscape input.txt
bitmark-parser-wasm breakscape input.txt --format plainText --location tag
bitmark-parser-wasm unbreakscape input.txt

# Query bit type information
bitmark-parser-wasm info
bitmark-parser-wasm info all -f json --pretty
bitmark-parser-wasm info bit --bit article

# Generate bitmark from JSON (not yet implemented)
bitmark-parser-wasm generate input.json output.bitmark

All commands support -o, --output <file> and -a, --append flags. Commands that accept input support file paths, literal strings, or stdin (when no arguments are given).

Browser Usage

The package includes pre-built browser bundles with the WASM module.

CDN (jsdelivr / unpkg)

<script type="module">
  import init, { parse } from "https://cdn.jsdelivr.net/npm/@gmb/bitmark-parser@latest/dist/browser/bitmark-parser.min.js";

  await init();

  const json = parse("[.article]\nHello **bold**");
  console.log(json);
</script>

Bundler (webpack / vite)

import init, { parse, lex } from "@gmb/bitmark-parser/browser";

await init();
const json = parse("[.article]\nHello");

License

ISC — © 2023–2026 Get More Brain Ltd.