initial commit

Author: bakkot

.github/workflows/build.yml

@@ -0,0 +1,20 @@
+name: Build spec
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-node@v3
+      with:
+        node-version: 16
+    - run: npm ci
+    - run: npm run build
+    - run: npm run check-format

.github/workflows/deploy.yml

@@ -0,0 +1,23 @@
+name: Deploy gh-pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-node@v3
+      with:
+        node-version: 16
+    - run: npm ci
+    - run: npm run build
+    - uses: JamesIves/[email protected]
+      with:
+        branch: gh-pages
+        folder: dist
+        clean: true

.gitignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+
+.DS_Store
+Desktop.ini
+._*
+Thumbs.db
+.Spotlight-V100
+.Trashes

DETAILS.md

@@ -0,0 +1,27 @@
+# Details
+
+There are number of decisions which could be made differently. This document attempts to catalog them along with the rationales for the choices currently made.
+
+## Getting an iterator record from `this`
+
+The added methods on `%IteratorPrototype%` assume that `this` is an iterator,
+and therefore use a new `GetIteratorDirect` method to acquire an iterator
+record. This means that code like `Iterator.syncPrototype.map.call([1, 2, 3], ...)`
+will not work.
+
+## Passing the protocol
+
+All added methods attempt to pass the values and calls they receive to whatever
+iterator they are wrapping. For example, `it.map(fn).next(5)` will call
+`it.next(5)` instead of `it.next()`. Additionally, calls like
+`it.map(fn).return()` will call upwards as well, to `it.return()`.
+
+## Interface constraints
+
+- The interface used to expose these methods must not clash with existing APIs.
+  For example: `Array.prototype.map` or `Map.prototype.forEach` denying access
+  to the interface.
+- It must work with everywhere an iteration can occur.
+  For example: `%GeneratorFunction%.prototype.map` will not work because the
+  interface has to be obtained from an explicit function call.
+  `%GeneratorFunction%.prototype` has no symbolic API to get the iterator.

README.md

@@ -0,0 +1,62 @@
+# Async Iterator Helpers
+
+A proposal for several interfaces that will help with general usage and
+consumption of async iterators in ECMAScript.
+
+This proposal was split out from [proposal-iterator-helpers](https://github.com/tc39/proposal-iterator-helpers) to resolve design questions related to parallelism, which are not relevant to sync helpers. Many design questions (including choice of methods) were discussed and decided in that respository, and its readme should be read first.
+
+## Status
+
+Authors: Gus Caplan, Michael Ficarra, Adam Vandolder, Jason Orendorff, Kevin Gibbons
+
+Champions: Michael Ficarra, Kevin Gibbons
+
+This proposal is at Stage 2 of [The TC39 Process](https://tc39.es/process-document/).
+
+**This proposal is in the process of being revised.** The core set of helpers and their high-level API is unlikely to change, but the underlying specification mechanism will likely be radically revised.
+
+This proposal contains the following methods:
+
+- `Iterator.prototype.toAsync`
+- `AsyncIterator.from`
+- `AsyncIterator.prototype`
+  - `.map`
+  - `.filter`
+  - `.take`
+  - `.drop`
+  - `.flatMap`
+  - `.reduce`
+  - `.toArray`
+  - `.forEach`
+  - `.some`
+  - `.every`
+  - `.find`
+
+See [proposal-iterator-helpers](https://github.com/tc39/proposal-iterator-helpers) for motivation and additional high-level descriptions for these methods.
+
+## Parallelism
+
+In the iterator-producing methods (`.map`, `.filter`, `.take`, `.drop`, and `.flatMap`), async helpers have the opportunity to support _parallelism_. For example, in the following code:
+
+```js
+asyncIteratorOfUrls
+  .map(u => fetch(u))
+
+await Promise.all([
+  x.next(),
+  x.next(),
+])
+```
+
+there could be two calls to `fetch` running at once. For this to work, the helpers have to be explicitly designed to support this. The original design of this proposal instead implemented the helpers as essentially async generators, which buffer calls to `.next` rather than allowing multiple calls to have simulaneous effects.
+
+This proposal is being revised to support at least the above use case. The exact details of what that looks like for each helper are not yet decided.
+
+### How can I access the new intrinsics?
+
+This proposal introduces two new intrisic objects, in addition to the two added in the sync proposal. They can be accessed as follows:
+
+```js
+const AsyncIteratorHelperPrototype = Object.getPrototypeOf(AsyncIterator.from([]).take(0));
+const WrapForValidAsyncIteratorPrototype = Object.getPrototypeOf(AsyncIterator.from({ async next(){} }));
+```