esast-util-from-js

esast (and estree) utility to parse trees from JavaScript.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • fromJs(value[, options])
  • Options
  • Plugin
  • Value
  • Version
• Types
• Compatibility
• Contribute
• License

What is this?

This package is a utility that turns a string of JavaScript into an esast (estree with some extra cleanliness) syntax tree.

When should I use this?

You can use this utility when you want to deal with ASTs of JavaScript combined with other unist and vfile things. You can use acorn itself if you don’t care about unified.

The utility estree-util-to-js does the inverse of this utility. It turns the tree into a string of JavaScript.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install esast-util-from-js

In Deno with esm.sh:

import {fromJs} from 'https://esm.sh/esast-util-from-js@2'

In browsers with esm.sh:

<script type="module">
  import {fromJs} from 'https://esm.sh/esast-util-from-js@2?bundle'
</script>

Use

import fs from 'node:fs/promises'
import {fromJs} from 'esast-util-from-js'

const tree = fromJs(await fs.readFile('example.js'), {module: true})

console.log(tree)

Yields:

{
  type: 'Program',
  body: [
    {
      type: 'ImportDeclaration',
      specifiers: [Array],
      source: [Object],
      position: [Object]
    },
    {
      type: 'ImportDeclaration',
      specifiers: [Array],
      source: [Object],
      position: [Object]
    },
    {
      type: 'VariableDeclaration',
      declarations: [Array],
      kind: 'const',
      position: [Object]
    },
    {
      type: 'ExpressionStatement',
      expression: [Object],
      position: [Object]
    }
  ],
  sourceType: 'module',
  comments: [],
  position: {
    start: {line: 1, column: 1, offset: 0},
    end: {line: 7, column: 1, offset: 157}
  }
}

API

This package exports the identifier fromJs. There is no default export.

fromJs(value[, options])

Parse JavaScript to an esast.

Parameters

• value (Value) — serialized JavaScript to parse
• options (Options, optional) — configuration

Returns

Tree (Node).

Throws

When the JavaScript cannot be parsed with acorn, a VFileMessage is thrown.

This can for example happen when passing modern syntax (you could maybe use a newer version, or it might be that the syntax is not yet supported), or just otherwise invalid JavaScript (you might need a plugin).

Options

Configuration (TypeScript type).

Fields

version

JavaScript version (Version, default: 'latest').

When a number, must be a year in the range 2015 and 2023 (both including). 'latest' is the same as passing the latest supported year.

☢️ Danger: 'latest' is a sliding thing, you could consider it as breaking semver. Pass an actual year to lock that down.

module

Whether this is a module (ESM) or a script (boolean, default: false).

allowReturnOutsideFunction

Whether a return statement is allowed in the top scope (boolean, default: false).

allowImportExportEverywhere

Whether import/export statements are allowed in the every scope (boolean, default: false).

allowAwaitOutsideFunction

Whether await is allowed in the top scope (boolean, default: depends). Defaults to version >= 2022.

allowSuperOutsideMethod

Whether super is allowed outside methods (boolean, default: false).

allowHashBang

Whether a shell hasbang is allowed (boolean, default: false).

plugins

List of acorn plugins (Array<Plugin>, default: []). Examples are acorn-jsx and acorn-stage3.

Plugin

Acorn plugin (TypeScript type).

Type

type Plugin = (Parser: ParserClass) => ParserClass

Value

Input value (TypeScript type).

When a typed array, must be UTF-8.

Type

type Value = Uint8Array | string

Version

JavaScript version (TypeScript type).

'latest' is equivalent to the latest supported year.

Type

type Version = 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 'latest'

Types

This package is fully typed with TypeScript. It exports the additional types Options, Plugin, Value, and Version.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, esast-util-from-js@^2, compatible with Node.js 16.

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer