# ast-source

> AST helper to transform source code.

Latest version **4.0.0** (published 2022-10-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install ast-source
pnpm add ast-source
yarn add ast-source
bun add ast-source
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2022-10-10 |
| First published | 2015-08-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 12 |
| Unpacked size | 69.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | azu |
| Maintainers | azu |
| Keywords | ast, generator, sourcemap, source-map |

## Links

- npm: https://www.npmjs.com/package/ast-source
- Repository: https://github.com/azu/ast-source
- Issues: https://github.com/azu/ast-source/issues
- npm.io page: https://npm.io/package/ast-source

## Dependencies (12)

- [debug](https://npm.io/package/debug.md) ^4.1.0
- [babylon](https://npm.io/package/babylon.md) ^6.6.5
- [espurify](https://npm.io/package/espurify.md) ^1.3.0
- [escodegen](https://npm.io/package/escodegen.md) ^1.6.1
- [@babel/core](https://npm.io/package/@babel/core.md) ^7.0.0
- [esprima-next](https://npm.io/package/esprima-next.md) ^5.8.4
- [object-assign](https://npm.io/package/object-assign.md) ^4.0.1
- [@babel/traverse](https://npm.io/package/@babel/traverse.md) ^7.0.0
- [@babel/generator](https://npm.io/package/@babel/generator.md) ^7.0.0
- [acorn-to-esprima](https://npm.io/package/acorn-to-esprima.md) ^2.0.8
- [path-is-absolute](https://npm.io/package/path-is-absolute.md) ^1.0.0
- [convert-source-map](https://npm.io/package/convert-source-map.md) ^1.1.1

## Alternatives

- [update-check](https://npm.io/package/update-check.md) — 4.0M weekly downloads
- [react-native-onesignal](https://npm.io/package/react-native-onesignal.md) — 134.5K weekly downloads
- [react-redux-toastr](https://npm.io/package/react-redux-toastr.md) — 33.7K weekly downloads
- [@nocobase/plugin-notification-manager](https://npm.io/package/@nocobase/plugin-notification-manager.md) — 2.0K weekly downloads
- [react-simple-toasts](https://npm.io/package/react-simple-toasts.md) — 1.9K weekly downloads

## Recent versions

- 4.0.0 (latest) — 2022-10-10
- 3.0.0 — 2018-10-14
- 2.1.0 — 2016-06-15
- 2.0.0 — 2016-03-06
- 1.2.1 — 2015-08-09
- 1.2.0 — 2015-08-09
- 1.1.0 — 2015-08-09
- 1.0.6 — 2015-08-09
- 1.0.5 — 2015-08-09
- 1.0.4 — 2015-08-09
- 1.0.3 — 2015-08-09
- 1.0.2 — 2015-08-08
- 1.0.1 — 2015-08-08

## README

# ast-source [![Actions Status: test](https://github.com/azu/ast-source/workflows/test/badge.svg)](https://github.com/azu/ast-source/actions?query=workflow%3A"test")

AST helper to transform source code.

On purpose make you focus to develop AST transforming function.


## Installation

    npm install ast-source

## Feature

- Automatically select JavaScript parser like esprima or babel(babylon)
    - It make you focus to develop AST transforming function.
- SourceMap support is first class.
- Always get clean AST if you want.
    - AST transforming function pollute AST's meta info(`range`, `loc` etc..).
    - `ASTSource#transformStrict` provide always clean AST by options.

## Example

- [azu/comment-to-assert: convert single line comment to assert.](https://github.com/azu/comment-to-assert)
- [azu/power-doctest: JavaScript: doctest + power-assert.](https://github.com/azu/power-doctest)


## Usage

### API

#### ASTSource(code, options)

ASTSource's input is source code, output is `ASTOutput`.

```js
var source = new ASTSource(code, options)
```

All options are optional. often set `filePath` as options.

```js
/**
 * @namespace
 * @type {Object} ASTSourceOptions
 * @property {string} ASTSourceOptions.filePath? path to source code
 * @property {string} ASTSourceOptions.sourceRoot? source root path to source code
 * @property {parserType} ASTSourceOptions.parserType? what parser is used
 * @property {boolean} ASTSourceOptions.esprimaTokens? tokens
 * @property {boolean} ASTSourceOptions.range? range
 * @property {boolean} ASTSourceOptions.loc? location
 * @property {boolean} ASTSourceOptions.comment?
 */
const defaultOptions = {
    filePath: null,
    disableSourceMap: false,
    parserType: null,
    esprimaTokens: true,
    loc: true,
    range: true,
    comment: true
};
```

##### value(): AST

Returns current AST

##### cloneValue(): AST

Return current AST that is [espurify](https://github.com/estools/espurify "espurify")ed.

##### transform(fn)

Transform current AST by `fn`.

```js
function transformFn(AST){
   return modify(AST)
}
var source = new ASTSource(code, options)
source.transform(transformFn);
```

##### transformStrict(fn)

Transform AST by `fn` after healing the AST.

re-calculate `range`, `loc`, `comment` the AST and transform.

##### output(): ASTOutput

Returns `ASTOutput`

#### ASTOutput

ASTOutput's input is source code, output are source code and source-map.

##### code: string

Returns source code of the results.

##### map: Object

Returns source map of the results.

##### codeWithMap: string

Returns source code that include base64ed comment of source map.

### Example

See [example](./example).
 
Run `npm test` on `example/`

```js
import ASTSource from "ast-source"
import estraverse from "estraverse"
import fs from "fs"

function transform(AST) {
    var replaced = {
        "type": "Literal",
        "value": 42,
        "raw": "42"
    };
    return estraverse.replace(AST, {
        enter: function (node) {
            if (node.type === estraverse.Syntax.Literal) {
                return replaced;
            }
        }
    });
}

var source = new ASTSource(fs.readFileSync("./input.js", "utf-8"), {
    filePath: "./input.js"
});
var output = source.transform(transform).output();
console.log(output.code);// => "var a = 42;"
console.dir(output.map.toString()); // => source map
fs.writeFileSync("./output.js", output.codeWithMap, "utf-8");

```

## Tests

    npm test

## Contributing

1. Fork it!
2. Create your feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. Submit a pull request :D

## License

MIT

---
_Source: https://npm.io/package/ast-source · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._