lrcx-parser

TypeScript parser and serializer for the LRCX v1.0 lyric format, with strictness-aware recovery modes and a preview playground.

Project Architecture

• packages/: library source for parser, serializer, exported types, and shared utilities.
• scripts/: local build wrappers and preview/build orchestration for TypeScript and Vite.
• tests/: Jest coverage for parser diagnostics, serialization, and showcase compliance.
• playground/: Vite-based preview UI for inspecting parsed output and timing behavior.
• builds/packages/: compiled library output published to npm.
• dist/playground/: static playground bundle for GitHub Pages.

Playground

Parser Playground: https://lrcx-dev.github.io/lrcx-parser-ts/

Local preview:

npm install
npm run dev

Get Started

Install:

npm install lrcx-parser

Parse with the default Standard mode:

import { LyricResolveMode, parseLRCX } from "lrcx-parser";

const result = parseLRCX(sourceText, LyricResolveMode.Standard);

Collect diagnostics from an explicit parser instance:

import { LRCXLooseParser } from "lrcx-parser";

const parser = new LRCXLooseParser(sourceText);
const document = parser.parse();
const errors = parser.getErrors();
const warnings = parser.getWarnings();

The library supports three parsing modes:

Mode	Typical behavior	Result status on recoverable issues
Strict	Fails fast on invalid or conflicting content.	Abort
Standard	Keeps useful output but stops at the point where correctness is no longer guaranteed.	Partial
Loose	Preserves as much observable content as possible for preview, migration, or repair workflows.	Fragment

Development

Install dependencies:

npm install

Common commands:

Command	Description
npm run clean	Remove stale library sourcemaps and delete the generated playground bundle.
npm run build	Build the publishable library artifact: .d.ts via tsc, minified .js via Vite lib mode.
npm run build:watch	Keep the local TypeScript compiler in watch mode for playground-oriented iteration.
npm run build:playground	Rebuild the library and emit the static playground bundle to dist/playground/.
npm run dev	Build once, then run the library watcher and the playground dev server together.
npm test	Rebuild the publish artifact and run the Jest suite in-band.

npm run dev does three things in order:

1. Removes stale sourcemaps from the previous library build.
2. Runs one TypeScript build into builds/packages/.
3. Starts tsc --watch and the Vite dev server for playground/.

scripts/run-tsc.mjs is only a thin wrapper around the locally installed TypeScript CLI. It resolves typescript from node_modules and forwards the arguments unchanged.

For npm publishing, npm run build uses a different pipeline:

1. tsc --emitDeclarationOnly writes .d.ts files into builds/packages/.
2. Vite lib mode rebuilds packages/index.ts into minified ESM JavaScript in the same output directory.

Test

Test coverage is organized around the public library surface:

• tests/lrcx-parser.mode-diagnostics.test.mjs: strict/standard/loose recovery semantics.
• tests/lrcx-parser.serialize.test.mjs: serialization behavior.
• tests/lrcx-parser.baseline-errors.test.mjs: baseline syntax and tag validation.
• tests/lrcx-parser.showcase.test.mjs: end-to-end compliance against the showcase draft.

For packaging, npm pack and npm publish trigger prepack, which rebuilds the minified publish artifact before files are collected.

License

MIT