Package Exports

esast-util-from-js
esast-util-from-js/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (esast-util-from-js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

esast-util-from-js

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

What is this?
When should I use this?
Install
Use
API
- fromJs(value[, options])
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 14.14+, 16.0+, or 18.0+), install with npm:

npm install esast-util-from-js

In Deno with esm.sh:

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

In browsers with esm.sh:

<script type="module">
  import {fromJs} from "https://esm.sh/esast-util-from-js@1?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 a JavaScript (string or Buffer in UTF-8) to an esast (Node).

`options`

Configuration (optional).

`options.version`

JavaScript version (number or 'latest', default: 'latest'). When a number, must be a year in the range 2015 and 2022 (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.

`options.module`

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

`options.allowReturnOutsideFunction`

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

`options.allowImportExportEverywhere`

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

`options.allowAwaitOutsideFunction`

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

`options.allowSuperOutsideMethod`

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

`options.allowHashBang`

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

`options.plugins`

List of acorn plugins (Array<Plugin>). Examples are acorn-jsx and acorn-stage3.

Returns

Tree (Node).

Types

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

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+, 16.0+, and 18.0+. Our projects sometimes work with older versions, but this is not guaranteed.

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.