Enable flush timing to be controlled from the host.

* Changes `_autorun` into a boolean
* Adds a new `flush` option to the backburner options which allows
  the host to either immediately flush (which would equal the prior
  behavior) via microtasks, **OR** flush "sometime later"
* Adds tests to ensure execution order

Co-authored-by: Kris Selden <kris.selden@gmail.com>

Author: Robert Jackson

lib/backburner/deferred-action-queues.ts

@@ -7,9 +7,9 @@ export interface IDebugInfo {
 
 export default class DeferredActionQueues {
   public queues: { [name: string]: Queue } = {};
+  public queueNameIndex = 0;
 
   private queueNames: string[];
-  private queueNameIndex = 0;
 
   constructor(queueNames: string[] = [], options: any) {
     this.queueNames = queueNames;

lib/backburner/platform.ts

@@ -2,7 +2,7 @@ export interface IPlatform {
   setTimeout(fn: Function, ms: number): any;
   clearTimeout(id: any): void;
   next(): any;
-  clearNext(timerId: any): void;
+  clearNext(): void;
   now(): number;
 }
 

lib/index.ts

@@ -150,6 +150,7 @@ export interface IBackburnerOptions {
   onErrorMethod?: string;
   mustYield?: () => boolean;
   _buildPlatform?: (flush: () => void) => IPlatform;
+  flush?(queueName: string, flush: () => void): void;
 }
 
 export default class Backburner {
@@ -213,7 +214,7 @@ export default class Backburner {
 
   private _boundRunExpiredTimers: () => void;
 
-  private _autorun: number | null = null;
+  private _autorun = false;
   private _autorunStack: Error | undefined | null = null;
   private _boundAutorunEnd: () => void;
   private _defaultQueue: string;
@@ -236,9 +237,9 @@ export default class Backburner {
       autorunsCompletedCount++;
 
       // if the autorun was already flushed, do nothing
-      if (this._autorun === null) { return; }
+      if (this._autorun === false) { return; }
 
-      this._autorun = null;
+      this._autorun = false;
       this._autorunStack = null;
       this._end(true /* fromAutorun */);
     };
@@ -260,7 +261,7 @@ export default class Backburner {
     let previousInstance = this.currentInstance;
     let current;
 
-    if (this._autorun !== null) {
+    if (this._autorun !== false) {
       current = previousInstance;
       this._cancelAutorun();
     } else {
@@ -540,7 +541,7 @@ export default class Backburner {
   }
 
   public hasTimers() {
-    return this._timers.length > 0 || this._autorun !== null;
+    return this._timers.length > 0 || this._autorun;
   }
 
   public cancel(timer?) {
@@ -601,7 +602,8 @@ export default class Backburner {
         finallyAlreadyCalled = true;
 
         if (result === QUEUE_STATE.Pause) {
-          this._scheduleAutorun();
+          const plannedNextQueue = this.queueNames[currentInstance.queueNameIndex];
+          this._scheduleAutorun(plannedNextQueue);
         } else {
           this.currentInstance = null;
 
@@ -651,9 +653,9 @@ export default class Backburner {
   }
 
   private _cancelAutorun() {
-    if (this._autorun !== null) {
-      this._platform.clearNext(this._autorun);
-      this._autorun = null;
+    if (this._autorun) {
+      this._platform.clearNext();
+      this._autorun = false;
       this._autorunStack = null;
     }
   }
@@ -767,15 +769,23 @@ export default class Backburner {
     if (currentInstance === null) {
       this._autorunStack = this.DEBUG ? new Error() : undefined;
       currentInstance = this.begin();
-      this._scheduleAutorun();
+      this._scheduleAutorun(this.queueNames[0]);
     }
     return currentInstance;
   }
 
-  private _scheduleAutorun() {
+  private _scheduleAutorun(plannedNextQueue: string) {
     autorunsCreatedCount++;
 
     const next = this._platform.next;
-    this._autorun = next();
+    const flush = this.options.flush;
+
+    if (flush) {
+      flush(plannedNextQueue, next);
+    } else {
+      next();
+    }
+
+    this._autorun = true;
   }
 }

tests/autorun-test.ts

@@ -5,6 +5,14 @@ import lolex from 'lolex';
 const SET_TIMEOUT = setTimeout;
 let fakeClock;
 
+function escapeCurrentMicrotaskQueue() {
+  return new Promise((resolve) => {
+    // this ensures that we have been to the end of the current
+    // events microtask queue
+    setTimeout(resolve, 0);
+  });
+}
+
 QUnit.module('tests/autorun', {
   afterEach() {
     if (fakeClock) {
@@ -162,3 +170,153 @@ QUnit.test('autorun functions even when using fake timers', function(assert) {
   assert.ok(bb.currentInstance, 'The DeferredActionQueues object exists');
   assert.equal(step++, 1);
 });
+
+QUnit.test('customizing flushing per queue via flush', function(assert) {
+  assert.step('start');
+
+  let deferredFlush;
+
+  let bb = new Backburner(
+    [
+      'zomg',
+      'render',
+      'afterRender'
+    ],
+    {
+      flush(queueName, flush) {
+        if (queueName === 'render') {
+          deferredFlush = flush;
+        } else {
+          flush();
+        }
+      }
+    }
+  );
+
+  bb.schedule('zomg', null, () => {
+    assert.step('running zomg');
+  });
+
+  bb.schedule('render', null, () => {
+    assert.step('running render');
+  });
+
+  bb.schedule('afterRender', null, () => {
+    assert.step('running afterRender');
+  });
+
+  return escapeCurrentMicrotaskQueue()
+    .then(() => {
+      deferredFlush();
+    })
+    .then(escapeCurrentMicrotaskQueue)
+    .then(() => {
+      assert.verifySteps([
+        'start',
+        'running zomg',
+        'running render',
+        'running afterRender',
+      ]);
+    });
+});
+
+QUnit.test('customized flushing - precedence is rechecked upon each flush', function(assert) {
+  assert.step('start');
+
+  let deferredFlush;
+
+  let bb = new Backburner(
+    [
+      'zomg',
+      'render',
+      'afterRender'
+    ],
+    {
+      flush(queueName, flush) {
+        if (deferredFlush === undefined && queueName === 'render') {
+          deferredFlush = flush;
+        } else {
+          flush();
+        }
+      }
+    }
+  );
+
+  bb.schedule('zomg', null, () => {
+    assert.step('running zomg');
+  });
+
+  bb.schedule('render', null, () => {
+    assert.step('running render');
+  });
+
+  bb.schedule('afterRender', null, () => {
+    assert.step('running afterRender');
+  });
+
+  return escapeCurrentMicrotaskQueue()
+    .then(() => {
+      bb.schedule('zomg', null, () => {
+        assert.step('running zomg 2');
+      });
+
+      deferredFlush();
+    })
+    .then(escapeCurrentMicrotaskQueue)
+    .then(() => {
+      assert.verifySteps([
+        'start',
+        'running zomg',
+        'running zomg 2',
+        'running render',
+        'running afterRender',
+      ]);
+    });
+});
+
+QUnit.test('customizing flushing per queue via flush - with forced run', function(assert) {
+  assert.step('start');
+
+  let deferredFlush;
+
+  let bb = new Backburner(
+    [
+      'zomg',
+      'render',
+      'afterRender'
+    ],
+    {
+      flush(queueName, flush) {
+        if (queueName === 'render') {
+          deferredFlush = flush;
+        } else {
+          flush();
+        }
+      }
+    }
+  );
+
+  bb.schedule('zomg', null, () => {
+    assert.step('running zomg');
+  });
+
+  bb.schedule('render', null, () => {
+    assert.step('running render');
+  });
+
+  bb.schedule('afterRender', null, () => {
+    assert.step('running afterRender');
+  });
+
+  return escapeCurrentMicrotaskQueue()
+    .then(() => {
+      bb.run(() => {});
+
+      assert.verifySteps([
+        'start',
+        'running zomg',
+        'running render',
+        'running afterRender',
+      ]);
+    });
+});

tests/configurable-timeout-test.ts

@@ -99,9 +99,8 @@ QUnit.test('We can use a custom clearTimeout', function(assert) {
         next() {
           return setTimeout(flush, 0);
         },
-        clearNext(timer) {
+        clearNext() {
           customClearTimeoutWasUsed = true;
-          return clearTimeout(timer);
         },
         now() {
           return Date.now();