stabilize Deno.iter() and Deno.iterSync() (#4890)

cli/js/io.ts

@@ -6,6 +6,8 @@
 export const EOF: unique symbol = Symbol("EOF");
 export type EOF = typeof EOF;
 
+const DEFAULT_BUFFER_SIZE = 32 * 1024;
+
 // Seek whence values.
 // https://golang.org/pkg/io/#pkg-constants
 export enum SeekMode {
@@ -71,7 +73,7 @@ export interface ReadWriteSeeker extends Reader, Writer, Seeker {}
 // https://golang.org/pkg/io/#Copy
 export async function copy(dst: Writer, src: Reader): Promise<number> {
   let n = 0;
-  const b = new Uint8Array(32 * 1024);
+  const b = new Uint8Array(DEFAULT_BUFFER_SIZE);
   let gotEOF = false;
   while (gotEOF === false) {
     const result = await src.read(b);
@@ -86,9 +88,12 @@ export async function copy(dst: Writer, src: Reader): Promise<number> {
 
 export async function* iter(
   r: Reader,
-  bufSize?: number
+  options?: {
+    bufSize?: number;
+  }
 ): AsyncIterableIterator<Uint8Array> {
-  const b = new Uint8Array(bufSize ?? 1024);
+  const bufSize = options?.bufSize ?? DEFAULT_BUFFER_SIZE;
+  const b = new Uint8Array(bufSize);
   while (true) {
     const result = await r.read(b);
     if (result === EOF) {
@@ -101,9 +106,12 @@ export async function* iter(
 
 export function* iterSync(
   r: SyncReader,
-  bufSize?: number
+  options?: {
+    bufSize?: number;
+  }
 ): IterableIterator<Uint8Array> {
-  const b = new Uint8Array(bufSize ?? 1024);
+  const bufSize = options?.bufSize ?? DEFAULT_BUFFER_SIZE;
+  const b = new Uint8Array(bufSize);
   while (true) {
     const result = r.readSync(b);
     if (result === EOF) {

cli/js/lib.deno.ns.d.ts

@@ -576,60 +576,68 @@ declare namespace Deno {
    */
   export function copy(dst: Writer, src: Reader): Promise<number>;
 
-  /** **UNSTABLE**: new API, yet to be vetted
+  /** Turns a Reader, `r`, into an async iterator.
-   * Turns a Reader, `r`, into an async iterator.
    *
-   *      let f = await open("/etc/passwd");
+   *      let f = await Deno.open("/etc/passwd");
-   *      for await (const chunk of iter(f)) {
+   *      for await (const chunk of Deno.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.
+   * Default size of the buffer is 32kB.
    *
-   *      let f = await open("/etc/passwd");
+   *      let f = await Deno.open("/etc/passwd");
-   *      for await (const chunk of iter(f, 1024 * 1024)) {
+   *      const iter = Deno.iter(f, {
+   *        bufSize: 1024 * 1024
+   *      });
+   *      for await (const chunk of iter) {
    *        console.log(chunk);
    *      }
    *      f.close();
    *
-   * Iterator uses internal buffer of fixed size for efficiency returning
+   * Iterator uses an internal buffer of fixed size for efficiency; it returns
-   * a view on that buffer on each iteration. It it therefore callers
+   * a view on that buffer on each iteration. It is therefore caller's
-   * responsibility to copy contents of the buffer if needed; otherwise
+   * responsibility to copy contents of the buffer if needed; otherwise the
    * next iteration will overwrite contents of previously returned chunk.
    */
   export function iter(
     r: Reader,
-    bufSize?: number
+    options?: {
+      bufSize?: number;
+    }
   ): AsyncIterableIterator<Uint8Array>;
 
-  /** **UNSTABLE**: new API, yet to be vetted
+  /** Turns a SyncReader, `r`, into an iterator.
-   * Turns a SyncReader, `r`, into an iterator.
    *
-   *      let f = openSync("/etc/passwd");
+   *      let f = Deno.openSync("/etc/passwd");
-   *      for (const chunk of iterSync(reader)) {
+   *      for (const chunk of Deno.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.
+   * Default size of the buffer is 32kB.
    *
-   *      let f = openSync("/etc/passwd");
+   *      let f = await Deno.open("/etc/passwd");
-   *      for (const chunk of iterSync(reader, 1024 * 1024)) {
+   *      const iter = Deno.iterSync(f, {
+   *        bufSize: 1024 * 1024
+   *      });
+   *      for (const chunk of iter) {
    *        console.log(chunk);
    *      }
-   *      f.close()
+   *      f.close();
    *
-   * Iterator uses internal buffer of fixed size for efficiency returning
+   * Iterator uses an internal buffer of fixed size for efficiency; it returns
-   * a view on that buffer on each iteration. It it therefore callers
+   * a view on that buffer on each iteration. It is therefore caller's
-   * responsibility to copy contents of the buffer if needed; otherwise
+   * responsibility to copy contents of the buffer if needed; otherwise the
    * next iteration will overwrite contents of previously returned chunk.
    */
   export function iterSync(
     r: SyncReader,
-    bufSize?: number
+    options?: {
+      bufSize?: number;
+    }
   ): IterableIterator<Uint8Array>;
 
   /** Synchronously open a file and return an instance of `Deno.File`.  The

cli/js/tests/files_test.ts

@@ -46,7 +46,7 @@ unitTest(
 
     let totalSize = 0;
     let iterations = 0;
-    for await (const buf of Deno.iter(file, 6)) {
+    for await (const buf of Deno.iter(file, { bufSize: 6 })) {
       totalSize += buf.byteLength;
       iterations += 1;
     }
@@ -78,7 +78,7 @@ unitTest(
 
     let totalSize = 0;
     let iterations = 0;
-    for (const buf of Deno.iterSync(file, 6)) {
+    for (const buf of Deno.iterSync(file, { bufSize: 6 })) {
       totalSize += buf.byteLength;
       iterations += 1;
     }