@omneedia/parse-function

Parse a function into an object using espree, acorn or babylon parsers. Extensible through Smart Plugins

Quality Assurance :100:

Features

• Always up-to-date: auto-publish new version when new version of dependency is out, Renovate
• Standard: using StandardJS, Prettier, SemVer, Semantic Release and conventional commits
• Smart Plugins: for extending the core API or the end Result, see .use method and Plugins Architecture
• Extensible: using plugins for working directly on AST nodes, see the Plugins Architecture
• ES2017 Ready: by using .parseExpression method of the babylon v7.x parser
• Customization: allows switching the parser, through options.parse
• Support for: arrow functions, default parameters, generators and async/await functions
• Stable: battle-tested in production and against all parsers - espree, acorn, babylon
• Tested: with 275+ tests for 200% coverage

Table of Contents

• Install
• Which version to use?
• Notes

• API

• Related
• Contributing
• Author
• License

$ yarn add parse-function

Which version to use?

const parseFunction = require('parse-function')
const app = parseFunction()

app.use((self) => {
  // self is same as `app`
  console.log(self.use)
  console.log(self.parse)
  console.log(self.define)

  self.define(self, 'foo', (bar) => bar + 1)
})

console.log(app.foo(2)) // => 3

const parseFunction = require('parse-function')
const app = parseFunction()

app.use((self) => {
  console.log('immediately called')

  return (node, result) => {
    console.log('called only when .parse is invoked')
    console.log(node)
    console.log(result)
  } 
})

parseFunction

Initializes with optional opts object which is passed directly

• opts {Object}: optional, merged with options passed to .parse method
  returns {Object}: app object with .use and .parse methods

const parseFunction = require('parse-function')

const app = parseFunction({
  ecmaVersion: 2017
})

const fixtureFn = (a, b, c) => {
  a = b + c
  return a + 2
}

const result = app.parse(fixtureFn)
console.log(result)

// see more
console.log(result.name) // => null
console.log(result.isNamed) // => false
console.log(result.isArrow) // => true
console.log(result.isAnonymous) // => true

// array of names of the arguments
console.log(result.args) // => ['a', 'b', 'c']

// comma-separated names of the arguments
console.log(result.params) // => 'a, b, c'

.parse

Parse a given code and returns a result object

• code {Function|String}: any kind of function or string to be parsed
  options {Object}: directly passed to the parser - babylon, acorn, espree
  options.parse {Function}: by default babylon.parseExpression, all options are passed as second argument to that provided function
  returns {Object}: result see result section for more info

const acorn = require('acorn')
const parseFn = require('parse-function')
const app = parseFn()

const fn = function foo (bar, baz) { return bar * baz }
const result = app.parse(fn, {
  parse: acorn.parse,
  ecmaVersion: 2017
})

console.log(result.name) // => 'foo'
console.log(result.args) // => ['bar', 'baz']
console.log(result.body) // => ' return bar * baz '
console.log(result.isNamed) // => true
console.log(result.isArrow) // => false
console.log(result.isAnonymous) // => false
console.log(result.isGenerator) // => false

.use

Add a plugin fn function for extending the API or working on the AST nodes. The fn is immediately invoked and passed with app argument which is instance of parseFunction() call. That fn may return another function that accepts (node, result) signature, where node is an AST node and result is an object which will be returned result from the .parse method. This retuned function is called on each node only when .parse method is called.

// plugin extending the `app`
app.use((app) => {
  app.define(app, 'hello', (place) => `Hello ${place}!`)
})

const hi = app.hello('World')
console.log(hi) // => 'Hello World!'

// or plugin that works on AST nodes
app.use((app) => (node, result) => {
  if (node.type === 'ArrowFunctionExpression') {
    result.thatIsArrow = true
  }
  return result
})

const result = app.parse((a, b) => (a + b + 123))
console.log(result.name) // => null
console.log(result.isArrow) // => true
console.log(result.thatIsArrow) // => true

const result = app.parse(function foo () { return 123 })
console.log(result.name) // => 'foo'
console.log(result.isArrow) // => false
console.log(result.thatIsArrow) // => undefined

• obj {Object}: the object on which to define the property
  prop {String}: the name of the property to be defined or modified
  val {Any}: the descriptor for the property being defined or modified
  returns {Object}: obj the passed object, but modified

const parseFunction = require('parse-function')
const app = parseFunction()

// use it like `define-property` lib
const obj = {}
app.define(obj, 'hi', 'world')
console.log(obj) // => { hi: 'world' }

// or define a custom plugin that adds `.foo` property
// to the end result, returned from `app.parse`
app.use((app) => {
  return (node, result) => {
    // this function is called
    // only when `.parse` is called

    app.define(result, 'foo', 123)

    return result
  }
})

// fixture function to be parsed
const asyncFn = async (qux) => {
  const bar = await Promise.resolve(qux)
  return bar
}

const result = app.parse(asyncFn)

console.log(result.name) // => null
console.log(result.foo) // => 123
console.log(result.args) // => ['qux']

console.log(result.isAsync) // => true
console.log(result.isArrow) // => true
console.log(result.isNamed) // => false
console.log(result.isAnonymous) // => true

Author

• github/tunnckoCore
• twitter/tunnckoCore
• codementor/tunnckoCore

License