micromark-factory-mdx-expression

micromark-factory-mdx-expression is a low-level parsing subroutine used across the micromark/MDX ecosystem to tokenize MDX expression syntax — the curly-brace {...} blocks that let markdown embed JavaScript expressions in flow content, text, and JSX attributes. It isn’t installed and used directly by application code; instead it’s the shared building block that micromark-extension-mdx-expression, micromark-extension-mdx-jsx, and other parsers in the MDX toolchain call into whenever they encounter an expression to tokenize.

The factory handles the hard edge cases of expression tokenization: balancing nested braces so {a ? {b} : c} isn’t closed early, detecting lazy continuation across container boundaries like blockquotes and lists, and optionally handing the raw expression text to Acorn for a full JavaScript AST via micromark-util-events-to-acorn. It also supports a spread-only mode for parsing {...props}-style JSX attribute spreads, and produces detailed VFileMessage errors — each linked to a specific documentation anchor — when parsing fails.

What You Get

• A reusable factoryMdxExpression tokenizer factory for building MDX-expression-aware micromark extensions
• Brace-balancing logic that correctly tracks nested {} inside an expression
• Optional Acorn integration via micromark-util-events-to-acorn for full JavaScript AST extraction
• A dedicated spread-only mode for parsing JSX attribute spreads ({...props})
• Descriptive VFileMessage errors with links to the relevant micromark-extension-mdx-expression documentation section

Common Use Cases

• Building a custom micromark extension that needs to parse {} expressions in markdown
• Powering MDX compilers (like @mdx-js/mdx) that need low-level expression tokenization
• Implementing a new flavor of JSX-in-markdown syntax that reuses the same expression grammar
• Validating and surfacing syntax errors in MDX expressions with precise source positions

Under The Hood

Architecture The package is a single-file module (dev/index.js, compiled to a production index.js) exporting one function, factoryMdxExpression, structured as a micromark tokenizer-state-machine factory: it returns a start state that transitions through before, inside, and eolAfter closures per micromark’s effects/State convention. It composes with a private helper, mdxExpressionParse, which wraps micromark-util-events-to-acorn’s eventsToAcorn to bridge micromark token events into an Acorn-parsed ESTree AST. There are no classes or dependency injection — plain closures capturing effects and the tokenizer’s self context, consistent with sibling micromark packages. As a leaf utility, it has no internal layering, but downstream extensions like micromark-extension-mdx-expression and micromark-extension-mdx-jsx call directly into this single function as their integration point, so any change to its state-machine contract or parameter order ripples into every consumer.

Tech Stack Plain modern ESM JavaScript ("type": "module"), with no application build step beyond micromark-build, the monorepo’s own tool for producing dev/production dual exports via the exports.development/exports.default package.json fields (assertions are present in dev, stripped in production). Runtime dependencies are almost entirely sibling micromark/unist packages — devlop (dev-only assertions), micromark-factory-space, micromark-util-character, micromark-util-events-to-acorn, micromark-util-symbol, micromark-util-types, unist-util-position-from-estree, and vfile-message — plus @types/estree for types. There is no database or web framework involved; this is a parsing primitive consumed transitively by markdown/MDX toolchains. Linting is handled by xo (ESLint-based) with Prettier, type-checking by tsc against JSDoc annotations, and coverage by c8, all configured at the monorepo root.

Code Quality Tests live at the monorepo root (/test/index.js, a single ~53KB file) rather than per-package, exercising this factory indirectly through micromark-extension-mdx-expression’s own end-to-end test suite rather than via a dedicated unit-test file scoped to this package alone. Error handling is explicit and typed: parse failures produce VFileMessage instances carrying a ruleId, source place, and a url pointing to a specific documentation anchor, rather than being swallowed or thrown as bare Errors. Naming follows established micromark conventions (effects, ok/nok, Tokenizer/State). Type safety is enforced through JSDoc annotations plus a type-coverage gate requiring 100% strict coverage, checked in CI via .github/workflows/main.yml.

API Design The public API is a single function with eleven positional parameters — implicit tokenizer context via this, effects, ok, three token-type strings, acorn, acornOptions, and four booleans — which is powerful but low-level, and easy to misuse without reading the JSDoc closely; the tradeoff buys extension authors precise control over token typing and parsing behavior. Documentation is thorough: every parameter is JSDoc’d with its type and default, the readme covers compatibility, security, and contribution guidance, and every thrown error links to a documentation anchor describing that specific failure mode. Boilerplate is minimal for authors already working inside the micromark tokenizer convention — they call factoryMdxExpression.call(self, ...) and return the resulting State — but the package is not meaningfully usable outside that specific tokenizer context.