NodeMutation

NodeMutation provides a set of APIs to rewrite node source code.

Table of Contents

- NodeMutation
- Table of Contents
- Installation
- Usage
- Evaluated Value
- Configuration
- adapter
- strategy
- tabWidth
- Contributing Guide

Installation

Install NodeMutation using npm:

``
npm install --save @xinminlabs/node-mutation
`

Or yarn;

`
yarn add @xinminlabs/node-mutation
`

Usage

1. initialize the NodeMutation instance:

`typescript
import { Node } from "typescript"

mutation = new NodeMutation(filePath: string, source: string, { adapter: "typescript" | "espree" | "gonzales-pe" })
`

2. call the rewrite apis:

`typescript
// append the code to the current node.
mutation.append(node: Node, code: string)
// delete source code of the child ast node
mutation.delete(node: Node, selectors: string | string[], options: DeleteOptions)
// insert code to the ast node.
mutation.insert(node: Node, code: string, options: InsertOptions)
// prepend code to the ast node.
mutation.prepend(node: Node, code: string)
// remove source code of the ast node
mutation.remove(node: Node, options: RemoveOptions)
// replace child node of the ast node with new code
mutation.replace(node: Node, selectors: string | string[], options: ReplaceOptions)
// replace the ast node with new code
mutation.replaceWith(node: Node, code: string)
// no operation
mutation.noop(node: Node)
// group actions
mutation.group(() => {
mutation.delete(node: Node, selectors: string | string[], options: DeleteOptions)
mutation.insert(node: Node, code: string, options: InsertOptions)
})
`

3. process actions and write the new source code to file:

`typescript
mutation.process()
`

Evaluated Value

NodeMutation supports to evaluate the value of the node, and use the evaluated value to rewrite the source code.

`ruby
source = 'class Synvert {}'
node = espree.parse(source)
mutation.replace node, '{{id}}', with: 'Foobar'
source # class Foobar {}
`

See more in TypescriptAdapter, SyntaxTreeAdapter, and GonzalesPeAdapter

Configuration

$3

Different parsers, like typescript and espree, will generate different AST nodes, to make NodeMutation work for them all,
we define an Adapter interface,
if you implement the Adapter interface, you can set it as NodeMutation's adapter.

It provides 3 adapters:

1. TypescriptAdapter
2. EspreeAdapter
3. GonzalesPeAdapter

`typescript
NodeMutation.configure({ adapter: new EspreeAdapter() }); // default is TypescriptAdapter
`

$3

It provides 2 strategies to handle conflicts when processing actions:

1. Strategy.KEEP_RUNNING: keep running and ignore the conflict action.
2. Strategy.THROW_ERROR: throw error when conflict action is found.

`typescript
NodeMutation.configure({ strategy: Strategy.KEEP_RUNNING }); // default is Strategy.THROW_ERROR
`

$3

`typescript
NodeMutation.configure({ tabWidth: 4 }); // default is 2
`

Contributing Guide

1. Fork and clone the repo.

2. Run npm install to install dependencies.

3. Run npm run test or npm run watch:test` to run tests.

4. Make some changes and make tests all passed.

5. Push the changes to the repo.