package
Esprima-compatible implementation of the Mozilla JS Parser API
npm install ast-typesGitHub-flavored package documentation.
Across all versions, last 30 days.
364,086,259 in 30 days
Runtime metadata.
Tagged topics.
Estimated unpacked size across 2 packages.
755.9 kB
Includes dependencies.
This module provides an efficient, modular, Esprima-compatible implementation of the abstract syntax tree type hierarchy pioneered by the Mozilla Parser API.
npm install ast-typesThe package ships its own TypeScript declarations; there is no
@types/ast-types to install. TypeScript 4.4 and later are supported, and
the declarations are type-checked against 4.4, 4.9 and 5.x on every commit.
To work on ast-types itself:
git clone https://github.com/benjamn/ast-types.git
cd ast-types
npm install
npm testimport assert from "assert";
import {
namedTypes as n,
builders as b,
} from "ast-types";
var fooId = b.identifier("foo");
var ifFoo = b.ifStatement(fooId, b.blockStatement([
b.expressionStatement(b.callExpression(fooId, []))
]));
assert.ok(n.IfStatement.check(ifFoo));
assert.ok(n.Statement.check(ifFoo));
assert.ok(n.Node.check(ifFoo));
assert.
The published declarations are generated from the same definitions as the
runtime types, so every node type is available as a TypeScript type of the
same name under namedTypes, and NodePath and Type are generic:
import {
builders as b,
namedTypes as n,
visit,
NodePath,
} from "ast-types";
const fooId: n.Identifier = b.identifier("foo");
const call: n.CallExpression = b.callExpression(fooId, []);
// Visitor methods receive a NodePath parameterized by the node type, so
// path.node is narrowed for you.
visit(call, {
visitCallExpression(path) {
const callee: n.CallExpression["callee"] = path.node.callee;
Note that a node type's TypeScript type describes what the definitions accept, which is often a union. Widening a field to admit a node shape a parser really produces is a change consumers may need to narrow around; see CHANGELOG.md for the ones that have happened.
Because it understands the AST type system so thoroughly, this library is able to provide excellent node iteration and traversal mechanisms.
If you want complete control over the traversal, and all you need is a way
of enumerating the known fields of your AST nodes and getting their
values, you may be interested in the primitives getFieldNames and
getFieldValue:
import {
getFieldNames,
getFieldValue,
} from "ast-types";
const partialFunExpr = { type: "FunctionExpression" };
// Even though partialFunExpr doesn't actually contain all the fields that
// are expected for a FunctionExpression, types.getFieldNames knows:
console.log(getFieldNames(partialFunExpr));
// [ 'type', 'id', 'params', 'body', 'generator', 'expression',
// 'defaults', 'rest', 'async' ]
// For fields that have default values, types.getFieldValue will return
// the default if the field is not actually defined.
console.log(getFieldValue(partialFunExpr, "generator"));
// falseTwo more low-level helper functions, eachField and someField, are
defined in terms of getFieldNames and getFieldValue:
// Iterate over all defined fields of an object, including those missing
// or undefined, passing each field name and effective value (as returned
// by getFieldValue) to the callback. If the object has no corresponding
// Def, the callback will never be called.
export function eachField(object, callback, context) {
getFieldNames(object).forEach(function(name) {
callback.call(this, name, getFieldValue(object, name));
}, context);
}
// Similar to eachField, except that iteration stops as soon as the
// callback returns a truthy value. Like Array.prototype.some, the final
// result is either true or false to indicates whether the callback
// returned true for any element or not.
export function someField(object, callback, context) {
return getFieldNames(object).some(function(name) {
return callback.call
So here's how you might make a copy of an AST node:
import { eachField } from "ast-types";
const copy = {};
eachField(node, function(name, value) {
// Note that undefined fields will be visited too, according to
// the rules associated with node.type, and default field values
// will be substituted if appropriate.
copy[name] = value;
})But that's not all! You can also easily visit entire syntax trees using
the powerful types.visit abstraction.
Here's a trivial example of how you might assert that arguments.callee
is never used in ast:
import assert from "assert";
import {
visit,
namedTypes as n,
} from "ast-types";
visit(ast, {
// This method will be called for any node with .type "MemberExpression":
visitMemberExpression(path) {
// Visitor methods receive a single argument, a NodePath object
// wrapping the node of interest.
var node = path.node;
if (
n.Identifier.check(node.object) &&
node.object.name === "arguments" &&
n.Identifier.check(node.property)
) {
assert.notStrictEqual(node.property.name, "callee");
}
Here's a slightly more involved example of transforming ...rest
parameters into browser-runnable ES5 JavaScript:
import assert from "assert";
import {
builders as b,
namedTypes as n,
visit,
} from "ast-types";
// Reuse the same AST structure for Array.prototype.slice.call.
var sliceExpr = b.memberExpression(
b.memberExpression(
b.memberExpression(
b.identifier("Array"),
b.identifier("prototype"),
false
),
b.identifier("slice"),
false
),
b.
Here's how you might use types.visit to implement a function that
determines if a given function node refers to this:
function usesThis(funcNode) {
n.Function.assert(funcNode);
var result = false;
visit(funcNode, {
visitThisExpression(path) {
result = true;
// The quickest way to terminate the traversal is to call
// this.abort(), which throws a special exception (instanceof
// this.AbortRequest) that will be caught in the top-level
// types.visit method, so you don't have to worry about
// catching the exception yourself.
this.abort();
},
visitFunction(path) {
// ThisExpression nodes in nested scopes don't count as `this`
// references for the original function node, so we can safely
// avoid traversing this subtree.
return false;
},
As you might guess, when an AbortRequest is thrown from a subtree, the
exception will propagate from the corresponding calls to this.traverse
in the ancestor visitor methods. If you decide you want to cancel the
request, simply catch the exception and call its .cancel() method. The
rest of the subtree beneath the try-catch block will be abandoned, but
the remaining siblings of the ancestor node will still be visited.
The NodePath object passed to visitor methods is a wrapper around an AST
node, and it serves to provide access to the chain of ancestor objects
(all the way back to the root of the AST) and scope information.
In general, path.node refers to the wrapped node, path.parent.node
refers to the nearest Node ancestor, path.parent.parent.node to the
grandparent, and so on.
Note that path.node may not be a direct property value of
path.parent.node; for instance, it might be the case that path.node is
an element of an array that is a direct child of the parent node:
path.node === path.parent.node.elements[3]in which case you should know that path.parentPath provides
finer-grained access to the complete path of objects (not just the Node
ones) from the root of the AST:
// In reality, path.parent is the grandparent of path:
path.parentPath.parentPath === path.parent
// The path.parentPath object wraps the elements array (note that we use
// .value because the elements array is not a Node):
path.parentPath.value === path.parent.node.elements
// The path.node object is the fourth element in that array:
path.parentPath.value[3] === path.node
// Unlike path.node and path.value, which are synonyms because path.node
// is a Node object, path.parentPath.node is distinct from
// path.parentPath.value, because the elements array is not a
// Node. Instead, path.parentPath.node refers to the closest ancestor
// Node, which happens to be the same as path.parent.node:
path.parentPath.node === path.parent.node
// The path is named for its index in the elements array:
path.name === 3
// Likewise, path.parentPath is named for the property by which
// path.parent.node refers to it:
path.parentPath.name === "elements"
These NodePath objects are created during the traversal without
modifying the AST nodes themselves, so it's not a problem if the same node
appears more than once in the AST (like Array.prototype.slice.call in
the example above), because it will be visited with a distict NodePath
each time it appears.
Child NodePath objects are created lazily, by calling the .get method
of a parent NodePath object:
// If a NodePath object for the elements array has never been created
// before, it will be created here and cached in the future:
path.get("elements").get(3).value === path.value.elements[3]
// Alternatively, you can pass multiple property names to .get instead of
// chaining multiple .get calls:
path.get("elements", 0).value === path.value.elements[0]NodePath objects support a number of useful methods:
// Replace one node with another node:
var fifth = path.get("elements", 4);
fifth.replace(newNode);
// Now do some stuff that might rearrange the list, and this replacement
// remains safe:
fifth.replace(newerNode);
// Replace the third element in an array with two new nodes:
path.get("elements", 2).replace(
b.identifier("foo"),
b.thisExpression()
);
// Remove a node and its parent if it would leave a redundant AST node:
//e.g. var t = 1, y =2; removing the `t` and `y` declarators results in `var undefined`.
path.prune(); //returns the closest parent `NodePath`.
// Remove a node from a list of nodes:
The object exposed as path.scope during AST traversals provides
information about variable and function declarations in the scope that
contains path.node. See scope.ts for its public
interface, which currently includes .isGlobal, .getGlobalScope(),
.depth, .declares(name), .lookup(name), and .getBindings().
The ast-types module was designed to be extended. To that end, it
provides a readable, declarative syntax for specifying new AST node types,
based primarily upon the require("ast-types").Type.def function:
import {
Type,
builtInTypes,
builders as b,
finalize,
} from "ast-types";
const { def } = Type;
const { string } = builtInTypes;
// Suppose you need a named File type to wrap your Programs.
def("File")
.bases("Node")
.build("name", "program")
.field("name", string)
.field("program", def("Program"));
// Prevent further modifications to the File type (and any other
The def syntax is used to define all the default AST node types found in
babel-core.ts,
babel.ts,
core.ts,
es-proposals.ts,
es6.ts,
,
,
,
,
,
,
,
,
,
,
,
and
,
so you have
no shortage of examples to learn from.