{"id":11314,"library":"micromark-util-events-to-acorn","title":"micromark events to Acorn parser utility","description":"micromark-util-events-to-acorn is a core utility within the micromark ecosystem, specifically designed to bridge micromark's low-level parsing events with acorn's robust JavaScript parsing capabilities. It takes an array of micromark events and attempts to construct an Abstract Syntax Tree (AST) using an acorn parser instance. This package is crucial for handling MDX expressions and similar constructs where embedded JavaScript needs to be parsed and validated. The current stable version is 2.0.3. While it doesn't have an independent, fixed release cadence, its updates are typically coordinated with major and minor releases of related micromark extensions, such as micromark-extension-mdx-expression. A key differentiator is its specialized role in the micromark architecture, providing a performant and integrated way to parse JavaScript directly from event streams, requiring the acorn parser and its options to be passed explicitly rather than being a direct dependency. It is ESM-only, requiring Node.js 16 or later.","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/micromark/micromark-extension-mdx-expression#main","tags":["javascript","expression","factory","micromark","mdx","typescript"],"install":[{"cmd":"npm install micromark-util-events-to-acorn","lang":"bash","label":"npm"},{"cmd":"yarn add micromark-util-events-to-acorn","lang":"bash","label":"yarn"},{"cmd":"pnpm add micromark-util-events-to-acorn","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The `acorn` parser instance is a required option for `eventsToAcorn` to parse event streams into an ESTree. It must be provided by the consuming application.","package":"acorn","optional":false},{"reason":"This package is a utility for projects using `micromark` (v3+), which generate the low-level events consumed by `eventsToAcorn`.","package":"micromark","optional":true}],"imports":[{"note":"This package is ESM-only since v2.0.0 and requires Node.js 16+. CommonJS `require` will result in an `ERR_REQUIRE_ESM` error.","wrong":"const { eventsToAcorn } = require('micromark-util-events-to-acorn')","symbol":"eventsToAcorn","correct":"import { eventsToAcorn } from 'micromark-util-events-to-acorn'"},{"note":"TypeScript type for the configuration object passed to `eventsToAcorn`.","symbol":"Options","correct":"import type { Options } from 'micromark-util-events-to-acorn'"},{"note":"TypeScript type for the return value of `eventsToAcorn`, which contains the parsed `estree` or an `error`.","symbol":"Result","correct":"import type { Result } from 'micromark-util-events-to-acorn'"}],"quickstart":{"code":"import { eventsToAcorn } from 'micromark-util-events-to-acorn';\nimport * as acorn from 'acorn'; // acorn must be installed and provided\n\n// Mock micromark events representing a simple MDX expression `{1 + 1}`.\n// In a real micromark application, these events would be generated by a tokenizer\n// parsing Markdown/MDX content.\nconst sampleEvents = [\n  { type: 'mdxExpressionText', start: { line: 1, column: 2, offset: 1 }, end: { line: 1, column: 7, offset: 6 } }\n];\n\nconst mockAcornOptions = { ecmaVersion: 2024, sourceType: 'module' };\n\n// Attempt to parse the micromark events into an ESTree AST using acorn.\nconst result = eventsToAcorn(sampleEvents, {\n  acorn: {\n    parse: acorn.parse,\n    parseExpressionAt: acorn.parseExpressionAt,\n  },\n  tokenTypes: ['mdxExpressionText'], // Essential since v2.0.0: list micromark token types that represent code data\n  acornOptions: mockAcornOptions,\n  start: { line: 1, column: 1, offset: 0 }, // Start position for source mapping\n  expression: true, // Indicate that we are parsing an expression\n  allowEmpty: false, // Do not allow empty expressions\n  prefix: '',\n  suffix: ''\n});\n\nif (result.error) {\n  console.error('Failed to parse expression:', result.error.message);\n} else if (result.estree) {\n  console.log('Successfully parsed ESTree expression:');\n  console.log(JSON.stringify(result.estree.body[0], null, 2));\n  // Expected output will be an ESTree node for '1 + 1'.\n} else {\n  console.log('Parsing completed, but no ESTree generated (e.g., empty expression allowed).');\n}","lang":"javascript","description":"Demonstrates how to use `eventsToAcorn` to parse a mock stream of `micromark` events into an `ESTree` using `acorn`."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer to ensure compatibility and receive security updates.","message":"Version 2.0.0 and later require Node.js 16 or higher. Older Node.js versions are no longer supported, aligning with the `unified` collective's compatibility policy.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `options.tokenTypes` is provided as an array of `TokenType` strings, for example, `tokenTypes: ['mdxExpressionText']` for MDX expressions.","message":"The `eventsToAcorn` function now explicitly requires the `tokenTypes` option to be passed. This array of strings specifies which `micromark` token types should be concatenated to form the source text that `acorn` will parse.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your project is configured for ESM and use `import` statements. If using Node.js, add `\"type\": \"module\"` to your `package.json` or use `.mjs` file extensions.","message":"This package is ESM-only. Attempting to `require()` it in a CommonJS module will result in a runtime error.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always explicitly specify `ecmaVersion` (e.g., `ecmaVersion: 2015`) in your `acornOptions` if you need a version other than the default `2024` to maintain consistent parsing behavior.","message":"While `micromark-util-events-to-acorn` itself accepts `acornOptions`, the parent `micromark-extension-mdx-expression@3.0.0` changed its default `ecmaVersion` to 2024. If using this utility in an MDX context, ensure your `acornOptions` are explicitly set if you require a different ECMAScript version.","severity":"gotcha","affected_versions":">=3.0.0 (for related extension)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Pass `tokenTypes: ['someTokenType']` as an option to `eventsToAcorn`, where 'someTokenType' are the micromark token types containing the code to be parsed.","cause":"The `tokenTypes` option was not provided to `eventsToAcorn` or was not an array of strings, which is a required parameter since v2.0.0 for processing the event stream.","error":"TypeError: Cannot read properties of undefined (reading 'includes')"},{"fix":"Refactor your code to use ES Modules (e.g., `import { eventsToAcorn } from 'micromark-util-events-to-acorn'`) and ensure your project is configured for ESM.","cause":"You attempted to `require()` this ESM-only package (`micromark-util-events-to-acorn`) in a CommonJS environment (e.g., in a `.js` file without `\"type\": \"module\"` in `package.json`).","error":"ERR_REQUIRE_ESM"},{"fix":"Install `acorn` (e.g., `npm install acorn`) and ensure you provide an `acorn` object with `parse` and `parseExpressionAt` methods in the `options` object.","cause":"The `acorn` parser library is a required peer/external dependency that must be installed and explicitly passed to `eventsToAcorn`, but it was not found.","error":"Error: Cannot find module 'acorn'"}],"ecosystem":"npm"}