From 6613a312b160374ba7a86c3b88fb67c0fe4247e0 Mon Sep 17 00:00:00 2001 From: Geert-Jan Zwiers <34610306+GJZwiers@users.noreply.github.com> Date: Tue, 22 Feb 2022 20:41:59 +0100 Subject: [PATCH] docs: code example to `structuredClone`, `CompressionStream`, `DecompressionStream` (#13719) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bartek Iwańczuk --- cli/dts/lib.deno.ns.d.ts | 10 ++-- cli/dts/lib.deno.window.d.ts | 16 +++--- ext/web/lib.deno_web.d.ts | 70 ++++++++++++++++++++++++++- ext/websocket/lib.deno_websocket.d.ts | 2 +- 4 files changed, 85 insertions(+), 13 deletions(-) diff --git a/cli/dts/lib.deno.ns.d.ts b/cli/dts/lib.deno.ns.d.ts index d759bdd58d..14cf2a3168 100644 --- a/cli/dts/lib.deno.ns.d.ts +++ b/cli/dts/lib.deno.ns.d.ts @@ -2910,11 +2910,13 @@ declare namespace Deno { * If `pid` is negative, the signal will be sent to the process group * identified by `pid`. * - * const p = Deno.run({ - * cmd: ["sleep", "10000"] - * }); + * ```ts + * const p = Deno.run({ + * cmd: ["sleep", "10000"] + * }); * - * Deno.kill(p.pid, "SIGINT"); + * Deno.kill(p.pid, "SIGINT"); + * ``` * * Requires `allow-run` permission. */ export function kill(pid: number, signo: Signal): void; diff --git a/cli/dts/lib.deno.window.d.ts b/cli/dts/lib.deno.window.d.ts index 1c8cdeae8a..fbd0a967b6 100644 --- a/cli/dts/lib.deno.window.d.ts +++ b/cli/dts/lib.deno.window.d.ts @@ -71,9 +71,11 @@ declare function prompt(message?: string, defaultValue?: string): string | null; /** Registers an event listener in the global scope, which will be called * synchronously whenever the event `type` is dispatched. * - * addEventListener('unload', () => { console.log('All finished!'); }); - * ... - * dispatchEvent(new Event('unload')); + * ```ts + * addEventListener('unload', () => { console.log('All finished!'); }); + * ... + * dispatchEvent(new Event('unload')); + * ``` */ declare function addEventListener( type: string, @@ -83,9 +85,11 @@ declare function addEventListener( /** Remove a previously registered event listener from the global scope * - * const lstnr = () => { console.log('hello'); }; - * addEventListener('load', lstnr); - * removeEventListener('load', lstnr); + * ```ts + * const listener = () => { console.log('hello'); }; + * addEventListener('load', listener); + * removeEventListener('load', listener); + * ``` */ declare function removeEventListener( type: string, diff --git a/ext/web/lib.deno_web.d.ts b/ext/web/lib.deno_web.d.ts index 1233b842f7..e8f7f26cd6 100644 --- a/ext/web/lib.deno_web.d.ts +++ b/ext/web/lib.deno_web.d.ts @@ -167,13 +167,17 @@ declare class ProgressEvent extends Event { /** Decodes a string of data which has been encoded using base-64 encoding. * - * console.log(atob("aGVsbG8gd29ybGQ=")); // outputs 'hello world' + * ``` + * console.log(atob("aGVsbG8gd29ybGQ=")); // outputs 'hello world' + * ``` */ declare function atob(s: string): string; /** Creates a base-64 ASCII encoded string from the input string. * - * console.log(btoa("hello world")); // outputs "aGVsbG8gd29ybGQ=" + * ``` + * console.log(btoa("hello world")); // outputs "aGVsbG8gd29ybGQ=" + * ``` */ declare function btoa(s: string): string; @@ -805,19 +809,81 @@ declare class MessagePort extends EventTarget { ): void; } +/** + * Creates a deep copy of a given value using the structured clone algorithm. + * + * Unlike a shallow copy, a deep copy does not hold the same references as the + * source object, meaning its properties can be changed without affecting the + * source. For more details, see + * [MDN](https://developer.mozilla.org/en-US/docs/Glossary/Deep_copy). + * + * Throws a `DataCloneError` if any part of the input value is not + * serializable. + * + * @example + * ```ts + * const object = { x: 0, y: 1 }; + * + * const deepCopy = structuredClone(object); + * deepCopy.x = 1; + * console.log(deepCopy.x, object.x); // 1 0 + * + * const shallowCopy = object; + * shallowCopy.x = 1; + * // shallowCopy.x is pointing to the same location in memory as object.x + * console.log(shallowCopy.x, object.x); // 1 1 + * ``` + */ declare function structuredClone( value: any, options?: StructuredSerializeOptions, ): any; +/** + * An API for compressing a stream of data. + * + * @example + * ```ts + * await Deno.stdin.readable + * .pipeThrough(new CompressionStream("gzip")) + * .pipeTo(Deno.stdout.writable); + * ``` + */ declare class CompressionStream { + /** + * Creates a new `CompressionStream` object which compresses a stream of + * data. + * + * Throws a `TypeError` if the format passed to the constructor is not + * supported. + */ constructor(format: string); readonly readable: ReadableStream; readonly writable: WritableStream; } +/** + * An API for decompressing a stream of data. + * + * @example + * ```ts + * const input = await Deno.open("./file.txt.gz"); + * const output = await Deno.create("./file.txt"); + * + * await input.readable + * .pipeThrough(new DecompressionStream("gzip")) + * .pipeTo(output.writable); + * ``` + */ declare class DecompressionStream { + /** + * Creates a new `DecompressionStream` object which decompresses a stream of + * data. + * + * Throws a `TypeError` if the format passed to the constructor is not + * supported. + */ constructor(format: string); readonly readable: ReadableStream; diff --git a/ext/websocket/lib.deno_websocket.d.ts b/ext/websocket/lib.deno_websocket.d.ts index af9026d419..8b79fa5cc5 100644 --- a/ext/websocket/lib.deno_websocket.d.ts +++ b/ext/websocket/lib.deno_websocket.d.ts @@ -37,7 +37,7 @@ interface WebSocketEventMap { /** * Provides the API for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection. * - * If you are looking to create a WebSocket server, please take a look at Deno.upgradeWebSocket(). + * If you are looking to create a WebSocket server, please take a look at `Deno.upgradeWebSocket()`. */ declare class WebSocket extends EventTarget { constructor(url: string, protocols?: string | string[]);