From 68d287eed5dcdc7b84a317fa90c4c9131389c0b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= Date: Wed, 22 Apr 2020 21:30:45 +0200 Subject: 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 --- cli/js/lib.deno.ns.d.ts | 54 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 3 deletions(-) (limited to 'cli/js/lib.deno.ns.d.ts') 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; - /** 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; + + /** **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; + export function iterSync( + r: SyncReader, + bufSize?: number + ): IterableIterator; /** 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` -- cgit v1.2.3