# call-matcher

> ECMAScript CallExpression matcher made from function/method signature

Latest version **2.0.0** (published 2019-01-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install call-matcher
pnpm add call-matcher
yarn add call-matcher
bun add call-matcher
```

## 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 | 2.0.0 |
| Published | 2019-01-21 |
| First published | 2015-12-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 15.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Takuto Wada |
| Maintainers | twada |
| Keywords | ast, estree, ecmascript |

## Links

- npm: https://www.npmjs.com/package/call-matcher
- Repository: https://github.com/twada/call-matcher
- Issues: https://github.com/twada/call-matcher/issues
- npm.io page: https://npm.io/package/call-matcher

## Dependencies (3)

- [espurify](https://npm.io/package/espurify.md) ^2.0.0
- [deep-equal](https://npm.io/package/deep-equal.md) ^1.0.0
- [estraverse](https://npm.io/package/estraverse.md) ^4.0.0

## 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

- 2.0.0 (latest) — 2019-01-21
- 1.1.0 — 2018-08-23
- 1.0.1 — 2016-12-31
- 1.0.0 — 2016-05-28
- 0.1.0 — 2015-12-22

## README

call-matcher
================================

ECMAScript CallExpression matcher made from function/method signature

[![Build Status][travis-image]][travis-url]
[![NPM version][npm-image]][npm-url]
[![Code Style][style-image]][style-url]
[![License][license-image]][license-url]


EXAMPLE
---------------------------------------

Creating CallExpression matcher for method signature `'assert.equal(actual, expected, [message])'`.

Then match against `path/to/some_test.js`.

```javascript
var CallMatcher = require('call-matcher');
var esprima = require('esprima');
var estraverse = require('estraverse');
var fs = require('fs');

var ast = esprima.parse('assert.equal(actual, expected, [message])');
var expression = ast.body[0].expression;
var matcher = new CallMatcher(expression);

estraverse.traverse(esprima.parse(fs.readFileSync('path/to/some_test.js')), {
    enter: function (currentNode, parentNode) {
        if (matcher.test(currentNode)) {
            // currentNode is a CallExpression that matches to the signature
        }
        var argMatched = matcher.matchArgument(currentNode, parentNode);
        if (argMatched) {
            if (argMatched.kind === 'mandatory') {
                // mandatory arg (in this case, `actual` or `expected`)
            } else if (argMatched.kind === 'optional') {
                // optional arg (in this case, `message`)
            }
        }
    }
});
```

where content of `path/to/some_test.js` is:

```javascript
var assert = require('assert');
var anotherAssert = assert;
var equal = assert.equal.bind(assert);
var foo = '2';
var bar = 2;

assert.equal(foo, bar);  // matches
assert.equal(bar, foo);  // matches
assert.equal(foo, bar, 'foo shoule be equal to bar');  // matches (with optional arg)

assert.equal();  // does not match (less args)
assert.equal(foo);  // does not match (less args)
assert.equal(foo, bar, 'hoge', 'fuga');  // does not match (too much args)

assert.notEqual(foo, bar);  // does not match (callee method name differs)
anotherAssert.equal(foo, bar);  // does not match (callee object name differs)
equal(foo, bar);  // does not match (callee does not match)
```

`call-matcher` is a spin-off product of [power-assert](https://github.com/twada/power-assert) project.

Pull-requests, issue reports and patches are always welcomed.


API
---------------------------------------

### var matcher = new CallMatcher(signatureAst, [options])

Create matcher object for a given expression.

```javascript
var ast = esprima.parse('assert.equal(actual, expected, [message])');
var expression = ast.body[0].expression;
var matcher = new CallMatcher(expression);
```

Any signature string enclosed in bracket (for example, `[message]`) means optional parameters. Without bracket means mandatory parameters.

Returns `matcher` object having four methods, `test`, `matchArgument`, `calleeAst`, and `argumentSignatures`.


#### options

an `object` for configuration options. If not passed, default options will be used.


#### options.visitorKeys

| type     | default value |
|:---------|:--------------|
| `object` | (return value of `estraverse.VisitorKeys`)   |

VisitorKeys for AST traversal. See [estraverse.VisitorKeys](https://github.com/estools/estraverse/blob/4.0.0/estraverse.js#L217-L288) and [babel.types.VISITOR_KEYS](https://github.com/babel/babel/blob/v5.1.11/src/babel/types/visitor-keys.json).


#### options.astWhiteList

| type     | default value |
|:---------|:--------------|
| `object` | N/A           |

Type and property whitelist on creating AST clone. `astWhiteList` is an object containing NodeType as keys and properties as values.

```js
{
    ArrayExpression: ['type', 'elements'],
    ArrayPattern: ['type', 'elements'],
    ArrowFunctionExpression: ['type', 'id', 'params', 'body', 'generator', 'expression'],
    AssignmentExpression: ['type', 'operator', 'left', 'right'],
    ...
```


### var isMatched = matcher.test(node)

Tests whether `node` matches the signature or not.

 - Returns `true` if matched.
 - Returns `false` if not matched.

`node` should be an AST node object defined in [The ESTree Spec](https://github.com/estree/estree) (formerly known as [Mozilla SpiderMonkey Parser API](https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API)).


### var argMatched = matcher.matchArgument(node, parentNode)

Returns match result object representing whether `node` (and its `parentNode`) matches some argument of the signature or not.

 - Returns `null` if not matched.
 - If matched, returns object like `{index: 0, name: 'actual', kind: 'mandatory'}`, whose `index` is an index of matched argument, `name` is an argument name in the signature and `kind` is `'mandatory'` or `'optional'`.

`node` and `parentNode` should be AST node objects defined in [The ESTree Spec](https://github.com/estree/estree) (formerly known as [Mozilla SpiderMonkey Parser API](https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API)).


### var calleeAst = matcher.calleeAst()

Returns clone of callee AST object based on signature passed to `CallMatcher` function. Returned tree is one of AST node objects defined in [The ESTree Spec](https://github.com/estree/estree) (formerly known as [Mozilla SpiderMonkey Parser API](https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API)) (in most cases, `Identifier` or `MemberExpression`).


### var argSigs = matcher.argumentSignatures()

Returns array of argument signature objects based on signature passed to `CallMatcher` function. Returns array of objects like `[{index: 0, name: 'actual', kind: 'mandatory'}]`, whose `index` is an index of matched argument, `name` is an argument name in the signature and `kind` is `'mandatory'` or `'optional'`.



INSTALL
---------------------------------------

### via npm

Install

    $ npm install --save call-matcher


CHANGELOG
---------------------------------------
See [CHANGELOG](https://github.com/twada/call-matcher/blob/master/CHANGELOG.md)


AUTHOR
---------------------------------------
* [Takuto Wada](https://github.com/twada)


CONTRIBUTORS
---------------------------------------
* [Renée Kooi](https://github.com/goto-bus-stop)


LICENSE
---------------------------------------
Licensed under the [MIT](https://github.com/twada/call-matcher/blob/master/MIT-LICENSE.txt) license.


[npm-url]: https://npmjs.org/package/call-matcher
[npm-image]: https://badge.fury.io/js/call-matcher.svg

[travis-url]: https://travis-ci.org/twada/call-matcher
[travis-image]: https://secure.travis-ci.org/twada/call-matcher.svg?branch=master

[style-url]: https://github.com/Flet/semistandard
[style-image]: https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg

[license-url]: https://github.com/twada/call-matcher/blob/master/MIT-LICENSE.txt
[license-image]: https://img.shields.io/badge/license-MIT-brightgreen.svg

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