Initial explainer, spec

Author: ljharb

README.md

@@ -1,50 +1,25 @@
-# template-for-proposals
+# proposal-array-zip
 
-A repository template for ECMAScript proposals.
+A TC39 proposal to synchronize the iteration of multiple arrays.
 
-## Before creating a proposal
+This proposal is based entirely on https://github.com/tc39/proposal-joint-iteration - in other words, this proposal is `Iterator.zip` and `Iterator.zipKeyed` for arrays.
 
-Please ensure the following:
-  1. You have read the [process document](https://tc39.github.io/process-document/)
-  1. You have reviewed the [existing proposals](https://github.com/tc39/proposals/)
-  1. You are aware that your proposal requires being a member of TC39, or locating a TC39 delegate to “champion” your proposal
+**Stage**: -1
 
-## Create your proposal repo
+**Specification**: (https://ljharb.github.io/proposal-array-zip/)
 
-Follow these steps:
-  1. Click the green [“use this template”](https://github.com/tc39/template-for-proposals/generate) button in the repo header. (Note: Do not fork this repo in GitHub's web interface, as that will later prevent transfer into the TC39 organization)
-  1. Update ecmarkup and the biblio to the latest version: `npm install --save-dev ecmarkup@latest && npm install --save-dev --save-exact @tc39/ecma262-biblio@latest`.
-  1. Go to your repo settings page:
-      1. Under “General”, under “Features”, ensure “Issues” is checked, and disable “Wiki”, and “Projects” (unless you intend to use Projects)
-      1. Under “Pull Requests”, check “Always suggest updating pull request branches” and “automatically delete head branches”
-      1. Under the “Pages” section on the left sidebar, and set the source to “deploy from a branch”, select “gh-pages” in the branch dropdown, and then ensure that “Enforce HTTPS” is checked.
-      1. Under the “Actions” section on the left sidebar, under “General”, select “Read and write permissions” under “Workflow permissions” and click “Save”
-  1. [“How to write a good explainer”][explainer] explains how to make a good first impression.
+## Motivation / Problem
 
-      > Each TC39 proposal should have a `README.md` file which explains the purpose
-      > of the proposal and its shape at a high level.
-      >
-      > ...
-      >
-      > The rest of this page can be used as a template ...
+Despite iterators existing for over a decade, it is still exceedingly common to use - and prefer - arrays over iterators, especially for small finite lists. They're simpler to work with, often more performant, and more broadly compatible with ecosystem libraries.
 
-      Your explainer can point readers to the `index.html` generated from `spec.emu`
-      via markdown like
+One can now always turn any iterator into an array with `.toArray()` - which is useful, but not ergnomic, especially when combined with the need to wrap the value in `Iterator.from()` before accessing iterator helpers.
 
-      ```markdown
-      You can browse the [ecmarkup output](https://ACCOUNT.github.io/PROJECT/)
-      or browse the [source](https://github.com/ACCOUNT/PROJECT/blob/HEAD/spec.emu).
-      ```
+## Solution
 
-      where *ACCOUNT* and *PROJECT* are the first two path elements in your project's Github URL.
-      For example, for github.com/**tc39**/**template-for-proposals**, *ACCOUNT* is “tc39”
-      and *PROJECT* is “template-for-proposals”.
+Add `Array.zip` and `Array.zipKeyed` static methods to the `Array` constructor.
 
+### Rationales
 
-## Maintain your proposal repo
-
-  1. Make your changes to `spec.emu` (ecmarkup uses HTML syntax, but is not HTML, so I strongly suggest not naming it “.html”)
-  1. Any commit that makes meaningful changes to the spec, should run `npm run build` to verify that the build will succeed and the output looks as expected.
-  1. Whenever you update `ecmarkup`, run `npm run build` to verify that the build will succeed and the output looks as expected.
-
-  [explainer]: https://github.com/tc39/how-we-work/blob/HEAD/explainer.md
+ - the method names, APIs, and semantics must match https://github.com/tc39/proposal-joint-iteration, to avoid confusion
+  - this includes accepting iterables, like `Array.from` and `Array.fromAsync`
+ - Adding Array.prototype methods is the most frequent cause of web compatibility issues, and browsers have expressed an unwillingness to even attempt adding more in the future - thus, they must be static