BREAKING CHANGE: rename Deno.toAsyncIterator() to Deno.iter() (#4848)

* rename Deno.toAsyncIterator() to Deno.iter()
* adds sync version Deno.iterSync()
* adds optional second argument for buffer size

1 files changed, 51 insertions, 3 deletions

diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts
index 9f2c854d9..ed2e40f84 100644
--- a/cli/js/lib.deno.ns.d.ts
+++ b/cli/js/lib.deno.ns.d.ts
@@ -573,13 +573,61 @@ declare namespace Deno {
    */
   export function copy(dst: Writer, src: Reader): Promise<number>;
 
-  /** Turns a Reader, `r`, into an async iterator.
+  /** **UNSTABLE**: new API, yet to be vetted
+   * Turns a Reader, `r`, into an async iterator.
+   *
+   *      let f = await open("/etc/passwd");
+   *      for await (const chunk of iter(f)) {
+   *        console.log(chunk);
+   *      }
+   *      f.close();
+   *
+   * Second argument can be used to tune size of a buffer.
+   * Default size of the buffer is 1024 bytes.
    *
-   *      for await (const chunk of toAsyncIterator(reader)) {
+   *      let f = await open("/etc/passwd");
+   *      for await (const chunk of iter(f, 1024 * 1024)) {
    *        console.log(chunk);
    *      }
+   *      f.close();
+   *
+   * Iterator uses internal buffer of fixed size for efficiency returning
+   * a view on that buffer on each iteration. It it therefore callers
+   * responsibility to copy contents of the buffer if needed; otherwise
+   * next iteration will overwrite contents of previously returned chunk.
+   */
+  export function iter(
+    r: Reader,
+    bufSize?: number
+  ): AsyncIterableIterator<Uint8Array>;
+
+  /** **UNSTABLE**: new API, yet to be vetted
+   * Turns a SyncReader, `r`, into an iterator.
+   *
+   *      let f = await open("/etc/passwd");
+   *      for (const chunk of iterSync(reader)) {
+   *        console.log(chunk);
+   *      }
+   *      f.close();
+   *
+   * Second argument can be used to tune size of a buffer.
+   * Default size of the buffer is 1024 bytes.
+   *
+   *      let f = await open("/etc/passwd");
+   *      for (const chunk of iterSync(reader, 1024 * 1024)) {
+   *        console.log(chunk);
+   *      }
+   *      f.close()
+   *
+   * Iterator uses internal buffer of fixed size for efficiency returning
+   * a view on that buffer on each iteration. It it therefore callers
+   * responsibility to copy contents of the buffer if needed; otherwise
+   * next iteration will overwrite contents of previously returned chunk.
    */
-  export function toAsyncIterator(r: Reader): AsyncIterableIterator<Uint8Array>;
+  export function iterSync(
+    r: SyncReader,
+    bufSize?: number
+  ): IterableIterator<Uint8Array>;
 
   /** Synchronously open a file and return an instance of `Deno.File`.  The
    * file does not need to previously exist if using the `create` or `createNew`