Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/anywhichway/assentials
Essential polymorphic async functions ... every, forEach, map, reduce, some, flow, pipe, when, route and more!
https://github.com/anywhichway/assentials
Last synced: about 4 hours ago
JSON representation
Essential polymorphic async functions ... every, forEach, map, reduce, some, flow, pipe, when, route and more!
- Host: GitHub
- URL: https://github.com/anywhichway/assentials
- Owner: anywhichway
- License: mit
- Created: 2019-02-14T03:51:08.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2019-05-10T11:15:50.000Z (over 5 years ago)
- Last Synced: 2024-10-16T11:34:20.409Z (30 days ago)
- Language: JavaScript
- Homepage:
- Size: 129 KB
- Stars: 10
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# assentials
Essential polymorphic async functions ... every, forEach, map, reduce, some, flow, pipe, when, route and more!
The `assentials` library provides asynchronous polymorphic versions of `forEach`, `every`, `map`, `reduce` and `some`. By "polymorphic" we mean you can pass in an `Array`, `Map`, `Set`, `generator`, `async generator`, or even an `object`.
The `assentials` library also provides asynchronous sequenced processing of functions, Regular Expressions, and literals through versions of `flow`, `pipe`, `when`, `route` and `router`.
`router` deserves special attention. It can handle just about anything as a condition. You can use literal matching, object destructuring, regular expressions, or functions as tests. The literal matching includes support for objects including nested values, Sets, and Maps.
Finally, there is a `parallel` function which will provide the same argument to multiple functions and run them in parallel (to the degree JavaScript supports parallel processing). It returns a `Promise` for an array of the final results in the order they are resolved.
All the above in about 2K minimized and gziped, 7K minimized, 12K raw!
# installation
npm install assentials
# usage
In NodeJS use:
`const assentials = require("assentials");`
In the browser, use the browserified version, `assentials.js`, in the browser directory.
There are unit tests for just about every common case in the `test/index.js` file. You can load them in a browser using `test/index.html`.
# API
## Iterating Functions
All iterating functions take the target of iteration as their first argument. When passing an `object`, the leaf nodes are by default considered the members of the item being iterated. This means that `forEach` and other functions can walk the leaves of an entire JavaScript object that might be used to represent a graph. Optionally, the branch nodes of the object can also be included in iteration.
The second argument to all the iterating functions is a function to apply to the current item being processed. This function can optionally be asynchronous itself and will be awaited.
```javascript
async every(Iterable||object object,
boolean [async] (any value,any key,Iterable||object)=>...,
boolean nodes)
```
* Works like the regular JavaScript `every` function, except it supports `Generator`, `AsyncGenerator`, and `object` as `iterable`. If an `object` is passed in `nodes` can be set to `true` to process branches as well as leaves.
```javascript
undefined forEach(Iterable||object iterable,
undefined [async] (any value,any key,object object)=>...,
boolean nodes)
```
* Works like the regular JavaScript `forEach` function, except it supports `Generator`, `AsyncGenerator`, and `object` as `iterable`. If an `object` is passed in `nodes` can be set to `true` to process branches as well as leaves. This is useful if processing a feedback graph like a neural net.
```javascript
async any map(Iterable||object iterable,
any [async] (any value,any key,object object)=>...,
boolean skipUndefined = false,
boolean nodes)
```
* Works like the regular JavaScript `map` function, except it returns the same class of iterable or object it was passed, e.g. if you map a `Set`, you will get a `Set` back. It also supports `Generator`, `AsyncGenerator`, and `object` as `iterable`. You can set `skipUndefined` to `true` in order to simply skip over `undefined` values returned from the map function. In the regular JavaScript function there is no way to do this without a subsequent filter, which could be expensive. If an `object` is passed in, `nodes` can be set to `true` to process branches as well as leaves. This is useful if processing a feedback graph like a neural net.
```javascript
async any reduce(Iterable||object iterable,
any [async] (any value,any key,object object)=>...,
any accum,
boolean continuable = true,
boolean nodes)
```
* Works like the regular JavaScript `reduce` function, except it supports `Generator`, `AsyncGenerator`, and `object` as `iterable` Setting `continuable` to `false` will abort the reduce operation as soon as the reducing function returns `undefined`. If an `object` is passed in `nodes` can be set to `true` to process branches as well as leaves. This is useful if processing a graph database structure.
```
async some(Iterable||object object,
boolean [async] (any value,any key,object object)=>...,
boolean nodes)
```
* Works like the regular JavaScript `some` function, except it supports `Generator`, `AsyncGenerator`, and `object` as `iterable`. If an `object` is passed in `nodes` can be set to `true` to process branches as well as leaves.
## Sequential Processing Functions
All sequence processing functions take one or more functions or literal values as their arguments. During processing, literal values are treated like they are functions of the form `(value) => value`.
`async any flow(function||any arg[,...])(any input)`
* Processes each argument by providing as an input the output of the previous argument's evaluation. As a result, any literals will simply replace the value from upstream and become the input for the next argument's evaluation. The flow will abort and return `undefined` if anything evaluates to `undefined`; otherwise, it will return the final evaluation. Think of it like a stream that stops flowing when there is nothing left.
`async any pipe(function||any arg[,...])(any input)`
* Processes each argument by providing as an input the output of the previous argument's evaluation. As a result, any literals will simply replace the value from upstream and become the input for the next argument's evaluation. The flow will continue through the last argument and return its evaluation. Functions within the flow must know how to handle `undefined` if an upstream argument can possibly evaluate to `undefined`. Think of it like a a real peipe that still exists even when there is nothing flowing through it.
`async any route(any condition,function||any arg[,...])(input)`
* Tests the `condition` against the `input`, and if `true` process each arg until the end or one evaluates to `undefined` or
`{value: any value, done: boolean true}`. Note: if returning a done indicator, it must have at most two keys, `done` and `value` or just `done`. This minimizes the chance of accidental aborts when inputs happen to contain properties by the name `value` or `done`, which would be hard to debug. Returns either the replacement `value` or `undefined`.
* For convenience, there is a `router(route aRoute[,...])` which takes a bunch of routes as its arguments. This function is itself a `until` whose condition is met when a route returns a value that is not undefined. This allows nesting of routes.
* When used in the context of a `router`, a `route` that returns `{done: true}` will cause the router to immediatelly return; whereas `undefined` will allow the next route to be processed.
* A router always returns the `input` or the `value` from `{value,done:true}`. Think of it like a package routing through many handlers who may look at or modify the contents of the package, but at the end of the day must deliver it to the next recipient in the chain before it utlimately gets delivered to the requestor, unless a valid substituion is provided via `{value,done:true}`.
* If the `condition` is a function it receives the argument and must return true if the route is to be proceesed.
* Otherwise, a single value is expected that must left equal the `condition`. By "left equal" we mean that the values satisfy `===`, the condition is a regular expression and the value matches it, or the condition and value are objects and all condition property values recursively left equal the value property values. This will even work with `Map` and `Set`. Additionally, if the condition property names can be converted into regular expressions or functions (even async ones!), they will be used to match which properties to test in the submitted value. At least one property must match. If destructuring is used, then the test must be a function that checks the destructured variables. The only thing that can't be matched is `undefined`. For example,
```javascript
const route = assentials.route,
handler = assentials.router(
route(new Set("a","b"),(item) => ...), // literal left equal test
route({age:21},(item) => ...), // literal left equal test
route(({age}) => age>21,(item) => ...) // destructuring function test
route( // property matching
{
// trivial case, something with a name property that has value "bill"
[(key) => /name/.test(key)]:"bill"
},
(item) => ...
),
)
```
* Typically, routes will be used with destructuring assignment or object left equal testing. You can route just about any object, but frequently they will be http request/response pairs or browser events, e.g.
```javascript
const route = assentials.route,
handler = assentials.router(
// normalize urls to industry standard URL object
route(({request:{url}}) => url!=null,({request}) => request.URL = new URL(url)),
// literal match on "/" to change to "/index.html"
route({request:{URL:{pathname:"/"}},
({request}) => request.url.pathname = "/index.html"),
// if no request body, abort by using {done: true}
route(({request:{body}}) => !body || body.length=0,
({response}) => { response.end(""); return {done:true}; }),
// parse the body
route(({request:{body}}) => body.length>0,
({request}) => { request.body = bodyParser(request.body); }),
...
route(({response:{sent}}) => !sent,
({response}) => { response.status = 404; response.end("Not Found"); })
);
http.createServer(function (request, response) {
handler({request,response});
}).listen(8080);
```
You can also use a router for generalized destructive object transformation, which is effectively what is happening above. For non-destructive transformation us `map`.
`async boolean trigger(any condition,function callback,[...])(input)`
* Immediately returns the result of evaluating condition. The calls each callback. If you want to to conditionalize how the callbacks operate, then wrap them in a `flow`, `route`, `when`, or even another `trigger`.
* See `route` for how `condition` is tested.
`async any until(condition,...functions)(input)`
Calls functions with `input` until condition is met and then returns the `input`'
`async any when(any condition,function||any arg[,...])(input)`
* Tests the `condition` against the `input`, and if `true` process each arg until the end or one evaluates to `undefined` or `{value: any value, done: boolean true}`. Note: if returning a done indicator, it must have at most two keys, `done` and `value` or just `done`. This minimizes the chance of accidental aborts which would be hard to debug. Returns the last evalutation. Otherwise, if the condition fails, returns the `input`.
## Parallel Processing Functions
`async Array parallel(function f,[...])(any arg[,...])`
Calls all the functions with the provided arguments. If any are asynchronous will await their resolution and returns a `Promise` for an array of results in the order they were resolved.
# Internals
For the iterating functions, `assentials` first turns the target of iteration into an asynchronous generator. This allows all subsequent logic to, for the most part, avoid conditionalizing on the type of item being iterated and keeps the code base small and easy to test.
Converting keys into regular expression tests or functions. For keys that start with "/" and using a try block an attempt is made to convert the key into a regular expression using `const regxp = new RegExp(key)`. If it works, the function `(value) => regexp.test(value)` is returned. For keys that start with the word "function" or matches `/\(*\)*=>*` and sucessfully compiles to function using a try block. To ensure that your keys are always compilable, create them using structured assignment, e.g.:
```
{
[/myregexp/]: value,
// or a functionally identical key to the preceding key in the context of left equal
[(key) => /myregexp/.test(key)]: value
}
```
# Updates (reverse chronological order)
2019-05-10 v1.0.2 Reverted to old module format. Too many interal projects at AnyWhichWay were breaking when trying to use new module format.
2019-05-09 v1.0.1 Revised export to export specific functions not entire module.
2019-05-08 v1.0.0 Moved to JavaScript modules format for index.js. Webpack produces ./browser/assentials.min.js. There is no longer a non-minified browser file. The index.js file is webpack tree shaking compatible.
2019-03-21 v0.0.14 Further refinements to router. WARNING: The behavior of `route` has changed. To exit a route return `{value:value,done:true}`. If a route does not exit, if now returns `undefined` by default.
2019-03-21 v0.0.13 Added `until`. Modified `router` to use `until` rather than `when`, which could have resulted in extra routes being run.
2019-03-20 v0.0.12 `router` was returning the Iterable control object instead of just its value, fixed.
2019-03-16 v0.0.11 exported `leftEqual`, corrected issue where `leftEqual` did not work on arrays.
2019-03-08 v0.0.10 added `trigger`
2019-03-04 v0.0.9 added regular expression and functional keys in left equal
2019-03-03 v0.0.8 documentation updates
2019-02-20 v0.0.7b `router` redefined to use a `when` as its top level to allow it to return the `value` in `{value,done:true}` if it is not `undefined`.
2019-02-19 v0.0.6b In one case leftEqual switched order or left and right. Fixed.
2019-02-19 v0.0.5b Correct object matching for routes to be leftEqual.
2019-02-18 v0.0.4b Added support for the `Iterable` continuation object `{value,done}` with `when` and `route`.
2019-02-18 v0.0.3b Minor deep equal enhancement.
2019-02-16 v0.0.2b Added object literal routing.
2019-02-16 v0.0.0b Initial public release.