https://github.com/enteee/fluentflow
A tool to filter json objects by describing their (timely) behaviour
https://github.com/enteee/fluentflow
javascript loganalytics nodejs timeseries-analysis
Last synced: 4 months ago
JSON representation
A tool to filter json objects by describing their (timely) behaviour
- Host: GitHub
- URL: https://github.com/enteee/fluentflow
- Owner: Enteee
- License: apache-2.0
- Created: 2016-03-09T17:59:34.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-01-05T00:50:48.000Z (over 3 years ago)
- Last Synced: 2025-10-21T08:47:38.436Z (7 months ago)
- Topics: javascript, loganalytics, nodejs, timeseries-analysis
- Language: JavaScript
- Homepage: https://duckpond.ch
- Size: 3.64 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
## FluentFlow
FluentFlow is a filter language with a simple [API][1] which lets you define 'followed by'-relations in a flow of JavaScript objects. You can either use FluentFlow [from the command line][2] or as a [JavaScript library][3].
[![npm version][5]][4]
[![Build Status][7]][6]
[![Coverage Status][9]][8]
[![js-semistandard-style][11]][10]
[#FluentFlow][12]
## Library
### Installation
```shell
$ npm install --save fluentflow
```
### Usage
```javascript
const ff = require('fluentflow');
const $ = ff.RuleBuilder
const _ = require('lodash');
/**
* Log all numbers greater than 9000.
*/
const ffm = ff.Matcher(
$(
// Start matching after 9000
(o, p, c, pc, match) => match(o === 9000)
).followedBy(
// Is the next object (o) greater than the previous (p)?
(o, p, c, pc, match) => match(o > p.get(0))
).then(
(objs, next) => next(console.log(objs))
)
);
_.range(9002).forEach((obj) => ffm(obj));
```
#### Sandbox (Matchbox)
FluentFlow supports evaluating string rules in an isolated environment:
```javascript
const _ = require('lodash');
const ffm = require('fluentflow').Matchbox(`
[
$(
// Start matching after 9000
(o, p, c, pc, match) => match(o === 9000)
).followedBy(
// Is the next object (o) greater than the previous (p)?
(o, p, c, pc, match) => match(o > p.get(0))
).then(
(objs, next) => next(console.log(objs))
)
]`);
_.range(9002).forEach((obj) => ffm(obj));
```
- `new Matchbox()` will raise an exception if the chain contains syntax-errors.
- `ffm()` will run the chain inside a [vm2]-instance.
- runtime exceptions will be reported via the `ffm()` callback: `ffm(obj, (err) => { console.log(err) } );`
[vm2]: https://github.com/patriksimek/vm2
## Command Line
### Installation
```shell
$ sudo npm install -g fluentflow
```
### Usage
Usage: fluentflow.js [OPTIONS] rulesFile
rulesFile : path to the rules file
OPTIONS:
-j JSONPath : JSONPath expression
-t : test if rules are valid
-h : print this help
### Getting started
Configure rules.js:
```javascript
[
/**
* Check if somebody forked this repository after submitting an issue.
* Reverse order because the github api displays events in this order.
*/
$(
(o, p, c, pc, match) => {
match(o.get('type') === 'ForkEvent');
}
).followedBy(
(o, p, c, pc, match) => match(
o.get('type') === 'IssuesEvent' &&
o.get('actor').get('login') === p.get(0).get('actor').get('login')
)
).then((objs, next) => next(
console.log('User: ' +
objs.get(1).get('actor').get('login') +
' forked after writing issue: ' +
objs.get(0).get('id')
)
))
];
```
Run FluentFlow:
```shell
$ curl -s https://api.github.com/repos/Enteee/FluentFlow/events | fluentflow rules.js -j '*'
```
_Note:_ `-j '*'` splits an array into objects.
## Testing
```shell
$ npm test
```
## API
[Documentation on github-pages][13]
### ffm
Matching core. Built using the JavaScript API using a [Matcher][14]
or from a [String][15] in a [Matchbox][16].
#### Parameters
- `obj` **[Object][17]** next [Object][18] to match
- `cb` **[errorFirstCallback][19]?** callback after matching finishes
### Matcher
Generates the matcher ([ffm][20]) for the given [Rule][21](s).
#### Parameters
- `rule` **...[Rule][22]** Rule(s) to match against.
#### Examples
```javascript
const _ = require('lodash');
const ff = require('fluentflow');
const $ = ff.RuleBuilder;
const ffm = ff.Matcher(
$(
(o, p, c, pc, match, f) => match(o == 42)
).followedBy(
(o, p, c, pc, match, f) => match(o == 9000)
).then(
(objs, next) => next(
console.log(objs)
)
)
);
// match some objects
_.range(9001).forEach((obj) => ffm(obj)); // prints [42, 9000]
```
Returns **[ffm][23]** a new matcher
### Matchbox
Generates the isolated matcher ([ffm][20]) for the given [Rule][21](s).
#### Parameters
- `rulesRaw` **[string][24]** a string of rules
- `vmoptions` **[Object][17]?** options to [vm2][25]
#### Examples
```javascript
const _ = require('lodash');
const ffm = require('fluentflow').Matchbox(`
[
$(
(o, p, c, pc, match, forget) => match(o == 42)
).followedBy(
(o, p, c, pc, match, forget) => match(o == 9000)
).then(
(objs, next) => next(
console.log(objs)
)
)
]
`);
// match some objects
_.range(9001).forEach((obj) => ffm(obj)); // prints [42, 9000]
```
Returns **[ffm][23]** an isolated [ffm][20]
### Callback Types
#### checkerCallback
Checks if an [Object][18] matches.
Type: [Function][26]
##### Parameters
- `o` **[Object][17]** the object to check
- `p` **[Object][17]** the previous object
- `c` **[Object][17]** the matching context
- `pc` **[Object][17]** the matching context from the previous state
- `match` **[match][27]** match callback, true if matches false otherwise
- `forget` **[forget][28]** forget callback, forget all states including objects passed as arguments
#### thenCallback
Called each time a sequence of [Object][18]s matches a [Rule][21] in a [ffm][20]
Type: [Function][26]
##### Parameters
- `objs` **[Array][29]** the matched objects
- `next` **[next][30]** end of callback. Continue matching next object
- `forget` **[forget][28]** forget objects.
#### errorFirstCallback
Standard node.js callback type.
Type: [Function][26]
##### Parameters
- `Error` **[Object][17]** Truthy if an error occured
- `data` **...[Object][17]** data
### Helper Classes
#### Rule
##### Parameters
- `check` **[Function][26]** checker function
- `next` **[Rule][22]** next rule
##### setThen
###### Parameters
- `then` **[thenCallback][31]** match callback
#### RuleBuilder
Builds [Rule][21].
##### Parameters
- `checker` **[checkerCallback][32]** first checker
##### Examples
```javascript
const rule = require('fluentflow').RuleBuilder(
(o, p, c, pc, match, forget) => match(o === 42)
).followedBy(
(o, p, c, pc, match, forget) => match(o === 9000)
).then(
(objs, next) => next(
console.log(objs)
)
); // prints [42, 9000]
```
Returns **[RuleBuilder][33]** continue
##### followedBy
Add a new checker.
###### Parameters
- `checker` **[checkerCallback][32]** next checker
Returns **[RuleBuilder][33]** continue
##### then
Finishes and builds the chain.
###### Parameters
- `then` **[thenCallback][31]?** run if rule matches
Returns **[Rule][22]** finish
## next
Signal the end of a [thenCallback][34].
## forget
Signal the intent to forget an object. Must be called before [next][35].
### Parameters
- `obj` **...[Object][17]** the object(s) to forget
## match
Signal the result of a matching operation.
### Parameters
- `matched` **[Boolean][36]?** true if matched, false otherwise. Default if omitted: false.
[1]: #api
[2]: #command-line
[3]: #library
[4]: https://badge.fury.io/js/fluentflow
[5]: https://badge.fury.io/js/fluentflow.svg
[6]: https://travis-ci.com/Enteee/FluentFlow
[7]: https://travis-ci.com/Enteee/FluentFlow.svg?branch=master
[8]: https://coveralls.io/github/Enteee/FluentFlow
[9]: https://coveralls.io/repos/github/Enteee/FluentFlow/badge.svg
[10]: https://github.com/Flet/semistandard
[11]: https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg?style=flat-square
[12]: https://twitter.com/hashtag/FluentFlow
[13]: https://enteee.github.io/FluentFlow/
[14]: #matcher
[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[16]: #matchbox
[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[19]: #errorfirstcallback
[20]: #ffm
[21]: #rule
[22]: #rule
[23]: #ffm
[24]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[25]: https://www.npmjs.com/package/vm2
[26]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
[27]: #match
[28]: #forget
[29]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[30]: #next
[31]: #thencallback
[32]: #checkercallback
[33]: #rulebuilder
[34]: #thencallback
[35]: #next
[36]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean