From 276c679bc0489e8afffaff9c69cdb83931fad979 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= Date: Sat, 25 Apr 2020 00:05:48 +0200 Subject: [PATCH] stabilize Deno.iter() and Deno.iterSync() (#4890) --- cli/js/io.ts | 18 +++++++++---- cli/js/lib.deno.ns.d.ts | 54 ++++++++++++++++++++++---------------- cli/js/tests/files_test.ts | 4 +-- 3 files changed, 46 insertions(+), 30 deletions(-) diff --git a/cli/js/io.ts b/cli/js/io.ts index 0237181002fcc7..d41914d34a9188 100644 --- a/cli/js/io.ts +++ b/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 { 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 { export async function* iter( r: Reader, - bufSize?: number + options?: { + bufSize?: number; + } ): AsyncIterableIterator { - 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 { - 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) { diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts index 696844f9496a22..c40e42b8c3cbb6 100644 --- a/cli/js/lib.deno.ns.d.ts +++ b/cli/js/lib.deno.ns.d.ts @@ -576,60 +576,68 @@ declare namespace Deno { */ export function copy(dst: Writer, src: Reader): Promise; - /** **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"); - * for await (const chunk of iter(f)) { + * let f = await Deno.open("/etc/passwd"); + * 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"); - * for await (const chunk of iter(f, 1024 * 1024)) { + * let f = await Deno.open("/etc/passwd"); + * 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 - * a view on that buffer on each iteration. It it therefore callers - * responsibility to copy contents of the buffer if needed; otherwise + * Iterator uses an internal buffer of fixed size for efficiency; it returns + * a view on that buffer on each iteration. It is therefore caller's + * 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; - /** **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"); - * for (const chunk of iterSync(reader)) { + * let f = Deno.openSync("/etc/passwd"); + * 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"); - * for (const chunk of iterSync(reader, 1024 * 1024)) { + * let f = await Deno.open("/etc/passwd"); + * 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 - * a view on that buffer on each iteration. It it therefore callers - * responsibility to copy contents of the buffer if needed; otherwise + * Iterator uses an internal buffer of fixed size for efficiency; it returns + * a view on that buffer on each iteration. It is therefore caller's + * 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; /** Synchronously open a file and return an instance of `Deno.File`. The diff --git a/cli/js/tests/files_test.ts b/cli/js/tests/files_test.ts index f68e5def4732c0..1e2c0608277a0a 100644 --- a/cli/js/tests/files_test.ts +++ b/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; }