refactor: extract Queue from IncrementalPublisher and IncrementalGraph

[yaacovCR]

A Queue is a batching async-generator meant to be consumed in the following pattern:

for await (const item of queue.subscribe(mapBatch)) {
   .... // use item
}

where mapBatch is a function that takes a batch of type Generator<T> and returns a single item of type U | undefined where undefined means no item is emitted.

Items are produced as managed by an executor function passed to the Queue constructor, a la repeaters, see https://repeater.js.org/)

A push() method is provided as an argument to the executor so that push() can be private to the code that constructs the Queue (although it can be saved to be passed to other code).

A stop() method is also provided as a the second argument to the executor for convenience, but it is also available on the queue object itself so that it can be called within the executor or by the consumer to end early. So this works:

const queue = new Queue(
  async (push, stop) => {
    push(1);
    push(2)
    await Promise.resolve();
    push(3);
    stop();
  },
);

const sub = queue.subscribe(batch => Array.from(batch));
const batch1 = await sub.next(); // batch1 = [1, 2]
const batch2 = await sub.next(); // batch2 = [3]

as does this:

let push;
const queue = new Queue(
  (_push) => {
    push = _push;
  },
);

push(1);
push(2);

const sub = queue.subscribe(batch => Array.from(batch));
const batch1 = await sub.next(); // batch1 = [1, 2]

const batch2Promise = sub.next();

await Promise.resolve();
push(3);
queue.stop();  // using the stop() method on queue avoid the need to set stop = _stop

const batch2 = await batch2Promise; // batch2 = [3]

Note: concurrent calls to subscribe will reference the same queue and are not encouraged.

Using queues, we are able to remove all logic for handling the implicit queue from IncrementalPublisher, retaining only the _handleCompletedBatch(), while adding only the required push() and stop() calls within the IncrementalGraph.

Tests do not change, except that we have some extra ticks from the use of our new generators (including the use of withCleanup() to wrap, and so we have to adjust a few tick-sensitive tests.

[yaacovCR]

API simplified, above edited.

[yaacovCR]

How does a Queue differ from a Repeater?

1. Queue adds two extra microtasks to the queue because (A) it uses a "real" async generator internally which adds an extra task for the [AsyncGeneratorResumeNext] job rather than a custom object following the raw async generator protocol which can avoid this and (B) it allows for concurrent .return() using the withCleanup() wrapper, which adds an await.
2. Queue does not provide a mechanism for handling backpressure, i.e. all pushes are synchronous. If we would like to add backpressure handling within the Incremental Publisher/Graph, we will do it at the source within the executor code that handles "early execution."
3. Queue allows for creation of multiple async-generators via the .subscribe() method, which could potentially conflict with each other; Repeaters ARE async generators, and cannot conflict. (This is tied to 1A, if a Queue was a generator, it would have to be a "raw" async generator, and we are using a "real" async generator purposefully for code simplification.)
4. ...other differences? @brainkim

[brainkim]

@yaacovCR Glad to see you're still working on GraphQL. The Queue is likely smaller page weight wise! 121 lines is tough to beat. I say keep going.