Merge pull request #3 from r24y/feat/nextCallDuring

New: Introduce `nthCallDuring` and `nextCallDuring`

Author: ryaninvents

.gitignore

@@ -1,2 +1,3 @@
 node_modules/
-/lib-test/
+/lib-test/
+/lib/

README.md

@@ -113,6 +113,93 @@ increment();
 // Prints `counter value is 3` since it waits for the 3rd call before resolving the Promise.
 ```
 
+### nextCallDuring(fn)
+
+Wait for the function to be called from a callback.
+
+```js
+let counter = 0;
+
+const increment = anticipatedCall(() => {
+    counter = counter + 1;
+});
+
+increment.nextCallDuring(() => {
+    counter = 5;
+    increment();
+}).then(() => console.log(`counter value is ${counter}`));
+// Prints `counter value is 6`
+```
+
+### nthCallDuring(n, fn)
+
+Like `nextCallDuring()`, but wait for the function to be called `n` times.
+
+
+```js
+let counter = 0;
+
+const increment = anticipatedCall(() => {
+    counter = counter + 1;
+});
+
+increment.nthCallDuring(3, () => {
+    counter = 5;
+    increment();
+    increment();
+    increment();
+}).then(() => console.log(`counter value is ${counter}`));
+// Prints `counter value is 8`
+```
+
+## Usage note
+
+In some cases, it's important to keep in mind that the returned Promise will resolve _at the end of the call frame_. Resolving a Promise is an asynchronous operation. Since JavaScript does one thing at a time (for the most part), when the Promise is resolved, it waits for the currently running function to stop executing (for a regular function, this happens on return; for an `async` function, this happens on `await`). If you're tracking state -- for instance, using a variable in a closure -- you might get unexpected results.
+
+Here's an example:
+
+```js
+let counter = 0;
+
+const increment = anticipatedCall(() => {
+    counter = counter + 1;
+});
+
+increment.nextCallDuring(() => {
+    increment();
+    increment();
+    increment();
+}).then(() => console.log(`counter value is ${counter}`));
+// Prints `counter value is 3`... but why?
+```
+
+`anticipated-call` was told to wait for the next invocation, but it didn't return until `increment()` had been called _three_ times! This is because the callback inside `nextCallDuring` needed to complete execution before the Promise could resolve.
+
+If the callback were an asynchronous function that yielded execution after the call, it would behave as might be expected:
+
+```js
+let counter = 0;
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const increment = anticipatedCall(() => {
+    counter = counter + 1;
+});
+
+increment.nextCallDuring(async () => {
+    increment();
+    await delay(0);
+    increment();
+    await delay(0);
+    increment();
+}).then(() => console.log(`counter value is ${counter}`));
+// Prints `counter value is 1`
+```
+
+The purpose of introducing `delay(0)` is to interrupt the call frame to allow the `anticipated-call` to have a chance to respond.
+
+If you're interested in learning more, I suggest reading about the JavaScript event loop ([this article](https://hackernoon.com/understanding-js-the-event-loop-959beae3ac40) is a great start).
+
 ## Contributing
 
-This project uses [ESLint-style commit messages](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-eslint/convention.md).
+This project uses [ESLint-style commit messages](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-eslint/readme.md).

lib/index.js

@@ -36,6 +36,18 @@ var Anticipated = function (_EventEmitter) {
         _this2.addListener('apply', didCall);
       });
     }
+  }, {
+    key: 'nthCallDuring',
+    value: function nthCallDuring(n, f) {
+      var promise = this.nthNextCall(n);
+      f();
+      return promise;
+    }
+  }, {
+    key: 'nextCallDuring',
+    value: function nextCallDuring(f) {
+      return this.nthCallDuring(1, f);
+    }
   }, {
     key: 'get',
     value: function get(target, name) {
@@ -68,4 +80,6 @@ function anticipateCall() {
   return new Proxy(fn, new Anticipated());
 }
 
-module.exports = anticipateCall;
+module.exports = anticipateCall;
+module.exports.Anticipated = Anticipated;
+module.exports.noop = noop;

src/__tests__/examples.test.js

@@ -24,3 +24,59 @@ describe('Example test suite', function () {
         assert(ex.value === 37, 'ex.value should equal 37');
     });
 });
+
+describe('Method demos', function () {
+  describe('nextCallDuring', function () {
+    it('should respond as expected', async () => {
+      let counter = 0;
+
+      const increment = anticipatedCall(() => {
+          counter = counter + 1;
+      });
+
+      return increment.nextCallDuring(() => {
+        counter = 5;
+        increment();
+      }).then(() => {
+        expect(`counter value is ${counter}`).toEqual('counter value is 6');
+      });
+    })
+  })
+})
+
+describe('usage note', () => {
+  test('counterintuitive case', () => {
+    let counter = 0;
+
+    const increment = anticipatedCall(() => {
+        counter = counter + 1;
+    });
+
+    increment.nextCallDuring(() => {
+        increment();
+        increment();
+        increment();
+    }).then(() => {
+      expect(`counter value is ${counter}`).toEqual('counter value is 3');
+    });
+  })
+  test('async usage', () => {
+    let counter = 0;
+
+    const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+    const increment = anticipatedCall(() => {
+        counter = counter + 1;
+    });
+
+    increment.nextCallDuring(async () => {
+        increment();
+        await delay(0);
+        increment();
+        await delay(0);
+        increment();
+    }).then(() => {
+      expect(`counter value is ${counter}`).toEqual('counter value is 1');
+    });
+  })
+})

src/__tests__/nextCall.test.js

@@ -0,0 +1,13 @@
+const anticipatedCall = require('..');
+
+describe('nextCallDuring', () => {
+    test('should resolve when called inside callback', () => {
+        const myFn = anticipatedCall(jest.fn());
+        const counterFn = jest.fn();
+        return myFn.nextCallDuring(() => {
+          myFn();
+        }).then(() => {
+          expect(myFn).toHaveBeenCalledTimes(1);
+        });
+    });
+})

src/__tests__/nextCallDuring.test.js

@@ -0,0 +1,27 @@
+const anticipatedCall = require('..');
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+describe('nthCallDuring', () => {
+    test('should resolve when called inside callback', () => {
+        const myFn = anticipatedCall(jest.fn());
+        return myFn.nthCallDuring(2, () => {
+          myFn();
+          myFn();
+        }).then(() => {
+          expect(myFn).toHaveBeenCalledTimes(2);
+        });
+    });
+    test('should resolve when called inside async callback', () => {
+        const myFn = anticipatedCall(jest.fn());
+        return myFn.nthCallDuring(2, async () => {
+          myFn();
+          await delay(0);
+          myFn();
+          await delay(0);
+          myFn();
+        }).then(() => {
+          expect(myFn).toHaveBeenCalledTimes(2);
+        });
+    });
+})

src/__tests__/nthCallDuring.test.js

@@ -14,18 +14,28 @@ class Anticipated extends EventEmitter {
       this.addListener('apply', didCall);
     });
   }
-  
+
   get nextCall() {
     return this.nthNextCall(1);
   }
-  
+
+  nthCallDuring(n, f) {
+    const promise = this.nthNextCall(n);
+    f();
+    return promise;
+  }
+
+  nextCallDuring(f) {
+    return this.nthCallDuring(1, f);
+  }
+
   get(target, name) {
     if (name in this) {
       return this[name];
     }
     return target[name];
   }
-  
+
   apply(target, thisArg, argumentsList) {
     this.emit('apply', thisArg, argumentsList);
     return target.apply(thisArg, argumentsList);
@@ -40,4 +50,4 @@ function anticipateCall(fn = noop) {
 
 module.exports = anticipateCall;
 module.exports.Anticipated = Anticipated;
-module.exports.noop = noop;
+module.exports.noop = noop;