Socket
Socket
Sign inDemoInstall

wait-for-stuff

Package Overview
Dependencies
Maintainers
1
Versions
10
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

wait-for-stuff - npm Package Compare versions

Comparing version 1.2.1 to 1.2.2

0

index.js

@@ -0,0 +0,0 @@ ///////////////////////////////////////////////////////////

2

package.json
{
"name": "wait-for-stuff",
"version": "1.2.1",
"version": "1.2.2",
"description": "an extendable library that can wait for stuff to happen in a synchronous-but-not-blocking manner",

@@ -5,0 +5,0 @@ "main": "index.js",

432

README.md
[![Build Status](https://travis-ci.org/ujc/wait-for-stuff.svg?branch=master)](https://travis-ci.org/ujc/wait-for-stuff)
# wait-for-stuff
an extendable library that can wait for stuff to happen in a synchronous-but-not-blocking manner
instead of waiting for **`async\await`**, you can now simply wait for the following "stuff":
An extendable library that can wait for stuff to happen in a synchronous-yet-non-blocking manner.
Instead of waiting for **`async\await`**, you can now simply wait for the following "stuff":
* **time** *(wait for x seconds to pass)*
* **date** *(wait until `date` is reached)*
* **predicate** *(wait until `prediacte` returns true)*
* **event** *(wait until `event` emits)*
* **predicate** *(wait until `prediacte` returns true)*
* **promise** *(wait for `promise` to settle)*
* **generator** *(wait for `generator` to fully exhaust all values)*
* **stream** *(wait until `readable-stream` is fully read)*
* **callback** *(wait for node-style `callback` to be called)*
* **function** *(wait for custom callback `function` to be called)*
* **yield** *(wait for a generator to `yield` a speific value)*
* **value** *(wait for `object.property` to equal `value`)*
* **property** *(wait for `object.property` to exist)*
* **yield** *(wait for a generator to `yield` a speific value)*
* **generator** *(wait for `generator` to fully exhaust all values)*
* **callback** *(wait for node-style `callback` to be called)*
* **function** *(wait for custom callback `function` to be called)*
* **array** *(wait for `array` to contain some value)*
* **compose** *(compose a new waiter from two or more existing waiters)*
* *(chainable \ follow-through waiters are coming soon)*
*(follow-through waiters are coming soon)*
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
---
## Why ?
because I'm tired of waiting for `await\async`, and want this code to work *(without blocking node's event-loop)*:
## Table of Contents
1. [Why?](#why)
2. [Install](#install)
3. [How it works](#how-it-works)
4. [Built-in waiters](#built-in-waiters)
1. [`wait.for.time()`](#wait-for-time)
2. [`wait.for.date()`](#wait-for-date)
3. [`wait.for.event()`](#wait-for-event)
4. [`wait.for.predicate()`](#wait-for-predicate)
5. [`wait.for.promise()`](#wait-for-promise)
6. [`wait.for.generator()`](#wait-for-generator)
7. [`wait.for.stream()`](#wait-for-stream)
8. [`wait.for.callback()`](#wait-for-callback)
9. [`wait.for.function()`](#wait-for-function)
10. [`wait.for.yield()`](#wait-for-yield)
11. [`wait.for.value()`](#wait-for-value)
12. [`wait.for.property()`](#wait-for-property)
13. [`wait.for.array()`](#wait-for-array)
5. [Middleware](#middleware)
1. [`wait.use()`](#wait-use)
2. [`wait.alias()`](#wait-alias)
6. [Composition](#composition)
1. [`wait.compose()`](#wait-compose)
7. [Contribute](#contribute)
8. [Test](#test)
9. [Related](#related)
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
---
## <a id="why">[#](#why)</a> Why ?
Because I'm tired of waiting for `await\async`, and want this code to work
*(without blocking node's event-loop)*:
```javascript
var fs = require('fs');
var wait = require('wait-for-stuff');
var myFile = fs.createReadStream('my.json');
var fs = require('fs');
var wait = require('wait-for-stuff');
var fileContents = wait.for.stream(myFile);
var myFile = fs.createReadStream('my.json');
var contents = wait.for.stream(myFile);
// the stream has now been fully read, async in the

@@ -44,24 +82,36 @@ // background while my code is still nice-and-pretty, without

---
## Install
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
## <a id="install">[#](#install)</a> Install
```
npm install wait-for-stuff
```
<br /><br />
---
## How it works
behind the scenes, `wait-for-stuff` uses [deasync](https://www.npmjs.com/package/deasync) to do it's magic.
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
this basically means that you can **write your code in a linear, sequential manner - while still allowing async operations to complete in the background on the same execution block**.
## <a id="how-it-works">[#](#how-it-works)</a> How it works
Behind the scenes, `wait-for-stuff` uses [deasync](https://www.npmjs.com/package/deasync) to do it's magic.
This basically means that you can write your code in a **linear, sequential manner** - while still allowing async operations to complete in the background on the same execution block.
<br /><br /><br />
---
## Built-in waiters
`wait-for-stuff` is designed to be *middleware-oriented* - which is just a fancy way of saying you can add your own "stuff" to "wait for" based on your own logic.
that said, it also comes with the following built-in waiters
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
## <a id="built-in-waiters">[#](#built-in-waiters)</a> Built-in waiters
`wait-for-stuff` is designed to be *middleware-oriented* - which is just a fancy way of saying you can add your own "stuff" to "wait for" based on your own logic.
That said, it also comes with the following built-in waiters:
<br /><br /><br />
**`wait.for.time(seconds)`** waits until `seconds` number of seconds pass
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-time">[#](#wait-for-time)</a>
**`wait.for.time(seconds)`**
Waits until `seconds` number of seconds pass
```javascript

@@ -74,61 +124,30 @@ wait.for.time(3);

**`wait.for.promise(promise)`** waits until `promise` is settled (either resolved or rejected). returns the value that the promise was settled with.
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-date">[#](#wait-for-date)</a>
**`wait.for.date(futureDateObject)`**
Waits until the system time passes the date of `futureDateObject`.
```javascript
var resultOrError = wait.for.promise(new Promise(...));
```
<br /><br />
`futureDateObject` must be a `Date` object.
If `futureDateObject` is configured as a date that has already passed, the waiting will simply end immediately.
**`wait.for.predicate(fn)`** waits until the `predicate` function returns a truthy value. this is useful if you need a simple mechanism to wait on your own custom application logic
```javascript
var isDone = false;
setTimeout(() => isDone = true, 5000);
wait.for.predicate(() => isDone);
// [5 seconds later]: isDone is now true, execution continues
var theFuture = new Date( new Date().getTime() + 5000 );
wait.for.date(theFuture);
// we are now in the future (though just by 5 seconds, so no biggy)
```
<br /><br />
**`wait.for.condition`** same as `wait.for.predicate`. this is just a convenience alias in case you prefer to use the word "condition" instead of "predicate"
<br /><br />
**`wait.for.value(owner, property, valueToWaitFor)`** waits until the `owner[property]` matches `valueToWaitFor`.
`property` must be a string.
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-event">[#](#wait-for-event)</a>
**`wait.for.event(emitter, eventName)`**
Waits until `emitter` emits the `eventName` event.
Returns the data that the event emitted (if any).
`owner` must be an object
```javascript
var myObject = { foo: 'bar'};
setTimeout(() => myObject.foo = '123', 5000);
var eventData = wait.for.event(myEmitter, 'someEvent');
wait.for.value(myObject, 'foo', '123');
// [5 seconds later]: myObject.foo now equals '123'
```
<br /><br />
**`wait.for.property(owner, property)`** waits until `owner` has a property named `property`
`property` must be a string.
`owner` must be an object
```javascript
var myObject = {};
setTimeout(() => myObject.foo = true, 5000);
wait.for.property(myObject, 'foo');
// [5 seconds later]: myObject now has a property named 'foo'
```
<br /><br />
**`wait.for.event(emitter, eventName)`** waits until `emitter` emits the `eventName` event. returns the data that the event emitted (if any).
```javascript
var eventData = wait.for.event(myEmitter, 'someEvent');
// if the event was emitted with just a single data argument,

@@ -144,20 +163,15 @@ // <eventData> will get that value

**`wait.for.date(futureDateObject)`** waits until the system time passes the date of `futureDateObject`.
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-predicate">[#](#wait-for-predicate)</a>
**`wait.for.predicate(fn)`**
Waits until the `predicate` function returns a truthy value.
This is useful if you need a simple mechanism to wait on your own custom application logic
`futureDateObject` must be a `Date` object. if `futureDateObject` is configured as a date that has already passed the waiting will simply end immediately.
```javascript
var theFuture = new Date( new Date().getTime() + 5000 );
wait.for.date(theFuture);
// we are now in the future (though just by 5 seconds, so no biggy)
```
<br /><br />
var isDone = false;
setTimeout(() => isDone = true, 5000);
**`wait.for.stream(readableStream)`** waits until `readableStream` has been fully read (ended). returns the data that was read from the stream (either as `string` or `buffer`, based on what the stream emitted as it's chunks)
```javascript
var myFile = fs.createReadStream('someFile.json');
var fileContents = wait.for.stream(myFile);
// fileContents now contains the contents of someFile.json
wait.for.predicate(() => isDone);
// [5 seconds later]: isDone is now true, execution continues
```

@@ -168,27 +182,20 @@ <br /><br />

[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-condition">[#](#wait-for-condition)</a>
**`wait.for.condition`**
Same as `wait.for.predicate`.
This is just a convenience alias in case you prefer to use the word "condition" instead of "predicate"
<br /><br /><br />
**`wait.for.yield(generator, value)`** waits until the `generator` has yielded the specified `value`.
`generator` can either be a generator-function, or an actuale iterable-generator *(the result of a generator-function)*
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-promise">[#](#wait-for-promise)</a>
**`wait.for.promise(promise)`**
Waits until `promise` is settled (either resolved or rejected).
Returns the value that the promise was settled with.
```javascript
function* myGeneratorFunction(){
count = 0;
while (true) { yield ++count }
}
wait.for.yield(myGeneratorFunction, 5);
// count is now 5
//////////////////////////////////////////////////////
// alternative (pass in the actual iterable-generator)
function* myGeneratorFunction(){
count = 0;
while (true) { yield ++count }
}
var iterable = myGeneratorFunction();
wait.for.yield(iterable, 5);
var resultOrError = wait.for.promise(new Promise(...));
```

@@ -200,5 +207,11 @@ <br /><br />

**`wait.for.generator(generator)`** waits until the `generator` has fully exhausted all of it's yielded values. returns the value that the generator function returns.
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-generator">[#](#wait-for-generator)</a>
**`wait.for.generator(generator)`**
Waits until the `generator` has fully exhausted all of it's yielded values.
Returns the value that the generator function returns.
`generator` can either be a generator-function, or an actuale iterable-generator *(the result of a generator-function)*
`generator` can either be a generator-function, or an actuale iterable-generator
*(the result of a generator-function)*

@@ -232,8 +245,32 @@ ```javascript

**`wait.for.callback(nodeAsyncFunction, ...params)`** waits until the `nodeAsyncFunction` has finished, passing to it any `params` that you supply.
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-stream">[#](#wait-for-stream)</a>
**`wait.for.stream(readableStream)`**
Waits until `readableStream` has been fully read (ended).
Returns the data that was read from the stream
*(either as `string` or `buffer`, based on what the stream emitted as it's chunks)*
**note:** with node-style callbacks, there's usually an `error` as the first argument, and any possible `data` argument comes after that. either of these might will be null if the other isn't, and there can be more than one `data` argument. `wait.for.callback` will make an attempt to simplify the result value when possible.
```javascript
var myFile = fs.createReadStream('someFile.json');
var fileContents = wait.for.stream(myFile);
// fileContents now contains the contents of someFile.json
```
<br /><br />
**see also:** **`wait.for.function`** *(below)*
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-callback">[#](#wait-for-callback)</a>
**`wait.for.callback(nodeAsyncFunction, ...params)`**
Waits until the `nodeAsyncFunction` has finished, passing to it any `params` that you supply.
Returns one or more values that the `callback` got as it's arguments.
If the callback got just a single value, that value will be returned by `wait.for.callback()` *(usually either an error object or actual data)*.
If the callback got more than a single value, an array-of-values is returned by `wait.for.callback()`. This array-of-values filters out `null` and `undefined` values. The order of the items in the array is the order in which they were passed into the callback.
Also, if the after filtering for `null` and `undefined` values the array only contains a single element, that element is returned directly *(instead of returning an array with just a single element in it)*.
**NOTE:** If you want to always get an array as the return value, use **[#](#wait-for-function) `wait.for.function()`**
```javascript

@@ -268,7 +305,10 @@ // instead of this:

[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-function">[#](#wait-for-function)</a>
**`wait.for.function(customAsyncFunction, ...params)`**
Waits until the `customAsyncFunction` has finished, passing to it any `params` that you supply.
**`wait.for.function(customAsyncFunction, ...params)`** waits until the `customAsyncFunction` has finished, passing to it any `params` that you supply.
Unlike `wait.for.callback()`, any-and-all arguments that were passed into the function will be returned as the complete `resultSet` of the `customAsyncFunction`.
unlike `wait.for.callback`, any arguments that were passed into the callback will be returned as the complete `resultSet` of the `customAsyncFunction`
```javascript

@@ -291,5 +331,86 @@ // instead of this:

**`wait.for.array(array, value)`** waits until `array` contains `value`
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-yield">[#](#wait-for-yield)</a>
**`wait.for.yield(generator, value)`**
Waits until the `generator` has yielded the specified `value`.
`generator` can either be a generator-function, or an actuale iterable-generator
*(the result of a generator-function)*
```javascript
function* myGeneratorFunction(){
count = 0;
while (true) { yield ++count }
}
wait.for.yield(myGeneratorFunction, 5);
// count is now 5
//////////////////////////////////////////////////////
// alternative (pass in the actual iterable-generator)
function* myGeneratorFunction(){
count = 0;
while (true) { yield ++count }
}
var iterable = myGeneratorFunction();
wait.for.yield(iterable, 5);
```
<br /><br />
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-value">[#](#wait-for-value)</a>
**`wait.for.value(owner, property, valueToWaitFor)`**
Waits until the `owner[property]` matches `valueToWaitFor`.
`property` must be a string
`owner` must be an object
```javascript
var myObject = { foo: 'bar'};
setTimeout(() => myObject.foo = '123', 5000);
wait.for.value(myObject, 'foo', '123');
// [5 seconds later]: myObject.foo now equals '123'
```
<br /><br />
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-property">[#](#wait-for-property)</a>
**`wait.for.property(owner, property)`**
Waits until `owner` has a property named `property`
`property` must be a string
`owner` must be an object
```javascript
var myObject = {};
setTimeout(() => myObject.foo = true, 5000);
wait.for.property(myObject, 'foo');
// [5 seconds later]: myObject now has a property named 'foo'
```
<br /><br />
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
<a id="wait-for-array">[#](#wait-for-array)</a>
**`wait.for.array(array, value)`**
Waits until `array` contains `value`
```javascript
var myArray = [];

@@ -304,9 +425,15 @@ setTimeout(() => myArray.push('hello world'), 1000);

[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
---
## Middleware
this library tries to provide atomic structures with the built-in waiters. from these basic waiters, you should be able to construct any custom waiter for anything you can think of *(and I sure hope you will).*
## <a id="middleware">[#](#middleware)</a> Middleware
This library aims to provide atomic structures with the built-in waiters.
From these, you can construct any custom waiter for anything additional that you may need in your application.
once you've built your own waiter-middleware, you can add it to `wait-for-stuff` using the **`wait.use(name, middleware)`** api.
Once you've built your own waiter-middleware - *or installed third-party waiter-middleware* - you can add it to `wait-for-stuff` using the **`wait.use(name, middleware)`** api.
<br /><br /><br />
**`wait.use(name, middleware)`** adds `middleware` as an additional waiter to `wait-for-stuff` under **`wait.for.<name>`**.
<a id="wait-use">[#](#wait-use)</a>
**`wait.use(name, middleware)`**
Adds `middleware` as a waiter that can be used with the general `wait.for...` API, under **`wait.for.<name>`**.

@@ -329,19 +456,32 @@ ```javascript

**note** you can also use this api to overwrite existing waiters with your own logic. while this is not recommended, it is possible.
**NOTE:** You can also use this api to overwrite existing waiters with your own logic.
While this is possible to do, it is not recommended.
<br /><br /><br />
**`wait.alias(originalName, alias)`** allows you to create an alias of your own liking to some waiter. for example, the built-in **`wait.for.condition`** waiter is just an alias to **`wait.for.predicate`**.
<a id="wait-alias">[#](#wait-alias)</a>
**`wait.alias(originalName, alias)`**
Allows you to create an alias of your own liking to an existing waiter.
For example, **`wait.for.condition()`** is just an alias to **`wait.for.predicate()`**.
```javascript
wait.alias('promise', 'syncPromise');
wait.for.syncPromise(myPromise); // just an alias to "wait.for.promise()"
```
<br /><br />
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
---
## Composition
you can compose your own "complex" waiter by combining the work of two or more waiters.
this is done by calling `wait.compose(waiter1, waiter2, ...waiterN)`. the result is a new waiter that passes
the return value from each waiter to the next, until all waiters have completed.
## <a id="composition">[#](#composition)</a> Composition
You can `compose` an advanced waiter by combining the work of two or more waiters together.
This is done using `wait.compose(waiter1, waiter2, ...waiterN)`.
The result is a new waiter that passes the return value from one waiter to the next, until all waiters have completed.
**`wait.compose(waiter1, waiter2, ...waiterN)`** composes a new waiter from the waiters that are passed in.
waiters are exhausted from right-to-left - just like you would expect from the functionl-programming `compose` function
<a id="wait-compose">[#](#wait-compose)</a>
**`wait.compose(waiter1, waiter2, ...waiterN)`**
Composes a new waiter from the waiters that are passed in.
Waiters are exhausted from right-to-left - just like you would expect from the functionl-programming `compose` function

@@ -357,7 +497,7 @@ ```javascript

// first we create a composed waiter
// it will first expect the arguments that should be passed into wait.for.callback.
// it will first expect the arguments that should be passed into >wait.for.callback.
// the result of wait.for.callback is then passed into wait.for.stream.
// the final result is what wait.for.stream will have returned
//
// in our case, myComplexFunction() expects a callback, which then gets a stream
// in our case, myComplexFunction() expects a callback, which then gets >a stream
// composition allows us to wait on both 'waiters'

@@ -368,3 +508,2 @@ var streamAndCallbackWaiter = wait.compose('stream', 'callback');

// result is the return value from wait.for.stream
result.toString().should.include('extension: compose');
```

@@ -376,15 +515,16 @@ <br /><br />

[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
--
## Contribute
I hope many people will find this module helpful - either as an alternative to asynchronous flow-execution patterns such as await\async (while we wait) etc.. - or as a supplement to go along with what ever you're allready using.
## <a id="contribute">[#](#contribute)</a> Contribute
I hope people will find this module helpful - either as an alternative to asynchronous flow-execution patterns such as `await\async` *(until it's official release at least)* - or as a supplement to go along with what ever you're all ready using.
If you create your own waiter middlewares, please do share them with the community.
If you create your own waiter-middlewares, please do share them with the community.
If you would like to have your waiter middlware added as a built-in to `wait-for-stuff`, please send a PR *(please also make sure to include tests)*
<br /><br /><br />
If you would like to have your waiter middlware added as a built-in to `wait-for-stuff`, please send me PR (please also make sure to include tests)
---
## Test
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
## <a id="test">[#](#test)</a> Test
```

@@ -396,5 +536,7 @@ npm run test

---
## Related
[//]: # (----------------------------------------------------)
[//]: # (----------------------------------------------------)
## <a id="related">[#](#related)</a> Related
* [deasync](https://www.npmjs.com/package/deasync)

0

test/wait-for-stuff.spec.js

@@ -0,0 +0,0 @@ var EventEmitter = require('events').EventEmitter;

.npmignore

Sorry, the diff of this file is not supported yet

.travis.yml

Sorry, the diff of this file is not supported yet

LICENSE

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc