transform-ast/readme.md

# transform-ast

Transform an AST with source maps.
Basically @substack's [falafel](https://github.com/substack/node-falafel), but based on [magic-string][].

## Example

```js
var result = require('transform-ast')(`
  var multiply = (a, b) => {
    return a * b
  }
  var add = (a, b) => a + b
`, function (node) {
  if (node.type === 'ArrowFunctionExpression') {
    var params = node.params.map(function (param) { return param.getSource() })
    if (node.body.type !== 'BlockStatement') {
      node.body.edit.update(`{ return ${node.body.getSource()} }`)
    }
    node.edit.update(`function (${params.join(', ')}) ${node.body.getSource()}`)
  }
})
result.toString() === `
  var multiply = function (a, b) {
    return a * b
  }
  var add = function (a, b) { return a + b }
`
fs.writeFile('output.js.map', result.generateMap().toString())
```

## Install

```bash
npm install --save transform-ast
```

## API

### `magicString = transformAst(source, opts = {}, fn = function () {})`

Parse and transform a `source` string.
`fn` will be called on each node.
The returned `magicString` is a [magic-string][] instance, with a `toString()` method to get the transformed string and a `generateMap()` method to generate a source map.

### `magicString.walk(fn)`

Walk the AST again.
`fn` will be called on each node.

### nodes

In addition to the usual AST node properties, each node object also has some additional methods.
Unlike falafel, these methods live on the `.edit` property, to prevent name conflicts (such as the `update()` method and the `.update` property of a ForStatement).
They're still also defined on the `node`s themselves, but only if there is no naming conflict.
It's better to use the `.edit` property.

### `node.getSource()`, `node.edit.source()`

Get the source string for a node, including transformations.

### `node.edit.update(string)`

Replace `node` with the given string.

### `node.edit.append(string)`

Append the source `string` after this node.

### `node.edit.prepend(string)`

Prepend the source `string` before this node.

## Custom Parser

You can pass in a custom parser using the `parser` option.
The parser should be an object with a `parse` function that takes a string and returns an AST.
Each AST node should have `.start` and `.end` properties indicating their position in the source string.

For example, parsing JSX using [babylon](https://github.com/babel/babylon):

```js
var babylon = require('babylon')
var transform = require('transform-ast')
var assert = require('assert')

assert.equal(transform(`
  var el = <div />;
`, { parser: babylon, plugins: [ 'jsx' ] }, function (node) {
  if (node.type === 'JSXElement') {
    node.edit.update(JSON.stringify(node.source()))
  }
}).toString(), `
  var el = "<div />";
`)
```

But parsers for other languages too, like [tacoscript](https://tacoscript.github.io)'s parser module [horchata](https://github.com/forivall/tacoscript/tree/master/packages/horchata):

```js
var horchata = require('horchata')
var transform = require('transform-ast')
var assert = require('assert')

assert.equal(transform(`
X = () -> {
  @prop or= 'value'
}
new X
`, { parser: horchata }, function (node) {
  switch (node.type) {
  case 'FunctionExpression':
    node.edit.update('function () ' + node.body.getSource())
  }
}).toString(), `
X = function () {
  @prop or= 'value'
}
new X
`)
```

## License

[MIT](./LICENSE)

[magic-string]: https://github.com/rich-harris/magic-string