npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@jacob-ebey/astring

v1.4.4

Published

JavaScript code generator from an ESTree-compliant AST.

Downloads

3

Readme

Astring

NPM Version Build Status Coverage devDependency Status

🌳 Tiny and fast JavaScript code generator from an ESTree-compliant AST.

Key features

Checkout the live demo showing Astring in action.

Contents

Installation

:warning: Astring relies on String.prototype.repeat(amount) and String.prototype.endsWith(string). If the environment running Astring does not define these methods, use string.prototype.repeat, string.prototype.endsWith or babel-polyfill.

Install with the Node Package Manager:

npm install astring

Alternatively, checkout this repository and install the development dependencies to build the module file:

git clone https://github.com/davidbonnet/astring.git
cd astring
npm install

Import

With JavaScript 6 modules:

import { generate } from 'astring'

With CommonJS:

const { generate } = require('astring')

A browser-ready minified bundle containing Astring is available at dist/astring.min.js. The module exposes a global variable astring:

<script src="astring.min.js" type="text/javascript"></script>
<script type="text/javascript">
  var generate = astring.generate
</script>

API

The astring module exposes the following properties:

generate(node: object, options: object): string | object

Returns a string representing the rendered code of the provided AST node. However, if an output stream is provided in the options, it writes to that stream and returns it.

The options are:

  • indent: string to use for indentation (defaults to "␣␣")
  • lineEnd: string to use for line endings (defaults to "\n")
  • startingIndentLevel: indent level to start from (defaults to 0)
  • comments: generate comments if true (defaults to false)
  • output: output stream to write the rendered code to (defaults to null)
  • generator: custom code generator (defaults to astring.baseGenerator)
  • sourceMap: source map generator (defaults to null)

baseGenerator: object

Base generator that can be used to extend Astring.

Benchmark

Generating code

Operations per second for generating each sample code from a pre-parsed AST:

| code sample (length) | escodegen | astring | uglify | babel | prettier | | :------------------- | --------: | --------: | ------: | ------: | -------: | | tiny code (11) | 1,257,527 | 7,185,642 | 129,467 | 156,184 | 333 | | everything (8532) | 1,366 | 8,008 | 0 | 346 | 64 |

Parsing and generating code

Operations per second for parsing and generating each sample code:

| code sample (length) | acorn + astring | meriyah + astring | buble | sucrase | | :------------------- | --------------: | ----------------: | -----: | ------: | | tiny code (11) | 92,578 | 864,665 | 25,911 | 575,370 | | everything (8532) | 706 | 1,425 | 132 | 1,403 |

Examples

The following examples are written in JavaScript 5 with Astring imported à la CommonJS.

Generating code

This example uses Acorn, a blazingly fast JavaScript AST producer and therefore the perfect companion of Astring.

// Make sure acorn and astring modules are imported

// Set example code
var code = 'let answer = 4 + 7 * 5 + 3;\n'
// Parse it into an AST
var ast = acorn.parse(code, { ecmaVersion: 6 })
// Format it into a code string
var formattedCode = astring.generate(ast)
// Check it
console.log(code === formattedCode ? 'It works!' : 'Something went wrong…')

Generating source maps

This example uses the source map generator from the Source Map module.

// Make sure acorn, sourceMap and astring modules are imported

var code = 'function add(a, b) { return a + b; }\n'
var ast = acorn.parse(code, {
  ecmaVersion: 6,
  sourceType: 'module',
  // Locations are needed in order for the source map generator to work
  locations: true,
})
// Create empty source map generator
var map = new sourceMap.SourceMapGenerator({
  // Source file name must be set and will be used for mappings
  file: 'script.js',
})
var formattedCode = generate(ast, {
  // Enable source maps
  sourceMap: map,
})
// Display generated source map
console.log(map.toString())

Using writable streams

This example for Node shows how to use writable streams to get the rendered code.

// Make sure acorn and astring modules are imported

// Set example code
var code = 'let answer = 4 + 7 * 5 + 3;\n'
// Parse it into an AST
var ast = acorn.parse(code, { ecmaVersion: 6 })
// Format it and write the result to stdout
var stream = astring.generate(ast, {
  output: process.stdout,
})
// The returned value is the output stream
console.log('Does stream equal process.stdout?', stream === process.stdout)

Generating comments

Astring supports comment generation, provided they are stored on the AST nodes. To do so, this example uses Astravel, a fast AST traveller and modifier.

// Make sure acorn, astravel and astring modules are imported

// Set example code
var code =
  [
    '// Compute the answer to everything',
    'let answer = 4 + 7 * 5 + 3;',
    '// Display it',
    'console.log(answer);',
  ].join('\n') + '\n'
// Parse it into an AST and retrieve the list of comments
var comments = []
var ast = acorn.parse(code, {
  ecmaVersion: 6,
  locations: true,
  onComment: comments,
})
// Attach comments to AST nodes
astravel.attachComments(ast, comments)
// Format it into a code string
var formattedCode = astring.generate(ast, {
  comments: true,
})
// Check it
console.log(code === formattedCode ? 'It works!' : 'Something went wrong…')

Extending

Astring can easily be extended by updating or passing a custom code generator. A code generator consists of a mapping of node names and functions that take two arguments: node and state. The node points to the node from which to generate the code and the state exposes the write method that takes generated code strings.

This example shows how to support the await keyword which is part of the asynchronous functions proposal. The corresponding AwaitExpression node is based on this suggested definition.

// Make sure the astring module is imported and that `Object.assign` is defined

// Create a custom generator that inherits from Astring's base generator
var customGenerator = Object.assign({}, astring.baseGenerator, {
  AwaitExpression: function(node, state) {
    state.write('await ')
    var argument = node.argument
    if (argument != null) {
      this[argument.type](argument, state)
    }
  },
})
// Obtain a custom AST somehow (note that this AST is not obtained from a valid code)
var ast = {
  type: 'AwaitExpression',
  argument: {
    type: 'CallExpression',
    callee: {
      type: 'Identifier',
      name: 'callable',
    },
    arguments: [],
  },
}
// Format it
var code = astring.generate(ast, {
  generator: customGenerator,
})
// Check it
console.log(
  code === 'await callable();\n' ? 'It works!' : 'Something went wrong…',
)

Command line interface

The bin/astring utility can be used to convert a JSON-formatted ESTree compliant AST of a JavaScript code. It accepts the following arguments:

  • -i, --indent: string to use as indentation (defaults to "␣␣")
  • -l, --line-end: string to use for line endings (defaults to "\n")
  • -s, --starting-indent-level: indent level to start from (defaults to 0)
  • -h, --help: print a usage message and exit
  • -v, --version: print package version and exit

The utility reads the AST from a provided list of files or from stdin if none is supplied and prints the generated code.

Example

As in the previous example, these examples use Acorn to get the JSON-formatted AST. This command pipes the AST output by Acorn from a script.js file to Astring and writes the formatted JavaScript code into a result.js file:

acorn --ecma6 script.js | astring > result.js

This command does the same, but reads the AST from an intermediary file:

acorn --ecma6 script.js > ast.json
astring ast.json > result.js

This command reads JavaScript 6 code from stdin and outputs a prettified version:

cat | acorn --ecma6 | astring