ESTree to ESAST Transformer

2.0.0 · active · verified Sun Apr 19

esast-util-from-estree is a utility within the unified collective's ecosystem, specifically designed to convert an ESTree-compliant Abstract Syntax Tree (AST) into an esast, which is a unist-compliant AST for ECMAScript. Currently stable at version 2.0.0, this package plays a crucial role in enabling unist utilities to process JavaScript ASTs. It ensures that the transformed nodes are plain JSON objects, incorporates unist positional information, normalizes specific fields like `.bigint`, and prunes discouraged or redundant fields such as `attributes` and `selfClosing` from JSXOpeningFragment nodes to ensure strict unist compatibility. The package maintains the common release cadence of the unified collective, with major versions like v2.0.0 introducing breaking changes such as the shift to ESM-only distribution and requiring Node.js 16 or newer. Its primary differentiator is providing a robust, standard-compliant bridge between the ESTree format, typically generated by parsers like Acorn, and the unist specification.

Common errors

```
ERR_REQUIRE_ESM: require() of ES Module .../node_modules/esast-util-from-estree/index.js from .../my-script.js not supported.
```
cause Attempting to use `require()` to import esast-util-from-estree, which is an ESM-only package since v2.0.0.

fix Convert your file to an ES module using `import { fromEstree } from 'esast-util-from-estree'` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
```
TypeError: Cannot read properties of undefined (reading 'type') at fromEstree (...)
```
cause The `fromEstree` function in v2.0.0+ no longer mutates its input; old code might be implicitly relying on mutation.

fix Ensure you are using the return value: `const esast = fromEstree(estree)`. Do not expect `estree` to be transformed in place.
```
TypeError: (0 , esast_util_from_estree_1.fromEstree) is not a function
```
cause Attempting to import `fromEstree` as a default export or with an incorrect named import.

fix Use a named import as there is no default export: `import { fromEstree } from 'esast-util-from-estree'`.

Warnings

breaking Version 2.0.0 of esast-util-from-estree requires Node.js 16 or higher.
Fix: Upgrade your Node.js environment to version 16 or newer, or stick to an older major version of the package if you must support older Node.js versions.
breaking Since version 2.0.0, this package is ESM-only. CommonJS `require()` is no longer supported.
Fix: Migrate your project to use ES modules (`import` statements) or use dynamic `import()` for this package. Ensure your `package.json` has `"type": "module"` if you're using ESM in Node.js.
breaking As of v2.0.0, the `fromEstree` function no longer mutates the input ESTree. You must use the return value of the function.
Fix: Change your code from `fromEstree(estree)` to `const esast = fromEstree(estree)` to correctly capture the transformed AST.
gotcha The package uses the `exports` field in its `package.json`. Directly importing internal paths (e.g., `esast-util-from-estree/lib/something`) is not supported and may break.
Fix: Only import directly from the package root: `import { fromEstree } from 'esast-util-from-estree'`.

Install

npm install esast-util-from-estree npm
yarn add esast-util-from-estree yarn
pnpm add esast-util-from-estree pnpm

Imports

fromEstree

wrong:

const fromEstree = require('esast-util-from-estree')

correct:

import { fromEstree } from 'esast-util-from-estree'

This package is ESM-only since v2.0.0. There is no default export.

fromEstree (Deno/Browser)
```
import {fromEstree} from 'https://esm.sh/esast-util-from-estree@2'
```
For Deno and browser environments, use esm.sh. Append `?bundle` for browser bundling.
Options (Type)
```
import type { Options } from 'esast-util-from-estree'
```
TypeScript types are shipped with the package for configuring the transformation.

Quickstart

This quickstart demonstrates parsing a JavaScript code string with Acorn to create an ESTree, then transforming that ESTree into an esast using `esast-util-from-estree`.

import { parse } from 'acorn';
import { fromEstree } from 'esast-util-from-estree';

// Make acorn support comments and positional info.
/** @type {Array<import('acorn').Comment>} */
const comments = [];
/** @type {import('estree').Program} */
// @ts-expect-error: acorn looks like estree.
const estree = parse(
  'export function x() { /* Something senseless */ console.log(/(?:)/ + 1n) }',
  {
    sourceType: 'module',
    ecmaVersion: 'latest',
    locations: true,
    onComment: comments
  }
);
estree.comments = comments;

// Transform the estree to an esast. Note: v2.0.0+ requires using the return value.
const esast = fromEstree(estree);

console.log(JSON.stringify(esast, null, 2));

view raw JSON →