From 257f0273250087bd5080430fe4c780b208d7986c Mon Sep 17 00:00:00 2001 From: Richard Carson Date: Mon, 17 Jun 2024 18:07:48 -0400 Subject: [PATCH] docs: Add documentation to a subset of available extensions (#24138) I was able to use my experience with some of the Deno extensions to flesh out their documentation a bit I've provided docs for the following: - web - fetch - net - webidl - url - io - crypto - console --------- Signed-off-by: Richard Carson --- ext/console/README.md | 28 +++++++- ext/crypto/README.md | 84 ++++++++++++++++++++++- ext/fetch/README.md | 80 +++++++++++++++++++++- ext/io/README.md | 24 ++++++- ext/net/README.md | 120 ++++++++++++++++++++++++-------- ext/url/README.md | 53 ++++++++++++++- ext/web/README.md | 154 +++++++++++++++++++++++++++++++++++++++++- ext/webidl/README.md | 22 +++++- 8 files changed, 527 insertions(+), 38 deletions(-) diff --git a/ext/console/README.md b/ext/console/README.md index 2f8fb448ac69fc..fab5f8536c5f04 100644 --- a/ext/console/README.md +++ b/ext/console/README.md @@ -1,5 +1,31 @@ # deno_console -This crate implements the Console API. +**This crate implements the Console API.** Spec: https://console.spec.whatwg.org/ + +## Usage Example + +From javascript, include the extension's source, and assign a console to the +global scope: + +```javascript +import * as console from "ext:deno_console/01_console.js"; +Object.defineProperty(globalThis, "console", { + value: new console.Console((msg, level) => + globalThis.Deno.core.print(msg, level > 1) + ), + enumerable: false, + configurable: true, + writable: true, +}); +``` + +Then from rust, provide `deno_console::deno_console::init_ops_and_esm()` in the +`extensions` field of your `RuntimeOptions` + +## Provided ops + +Following ops are provided, which can be accessed through `Deno.ops`: + +- op_preview_entries diff --git a/ext/crypto/README.md b/ext/crypto/README.md index be07244584e75b..f4f228e60d1764 100644 --- a/ext/crypto/README.md +++ b/ext/crypto/README.md @@ -1,5 +1,87 @@ # deno_crypto -This crate implements the Web Cryptography API. +**This crate implements the Web Cryptography API.** Spec: https://www.w3.org/TR/WebCryptoAPI/ + +## Usage Example + +From javascript, include the extension's source, and assign `CryptoKey`, +`crypto`, `Crypto`, and `SubtleCrypto` to the global scope: + +```javascript +import * as crypto from "ext:deno_crypto/00_crypto.js"; + +Object.defineProperty(globalThis, "CryptoKey", { + value: crypto.CryptoKey, + enumerable: false, + configurable: true, + writable: true, +}); + +Object.defineProperty(globalThis, "crypto", { + value: crypto.crypto, + enumerable: false, + configurable: true, + writable: false, +}); + +Object.defineProperty(globalThis, "Crypto", { + value: crypto.Crypto, + enumerable: false, + configurable: true, + writable: true, +}); + +Object.defineProperty(globalThis, "SubtleCrypto", { + value: crypto.SubtleCrypto, + enumerable: false, + configurable: true, + writable: true, +}); +``` + +Then from rust, provide: +`deno_crypto::deno_crypto::init_ops_and_esm(Option)` in the `extensions` +field of your `RuntimeOptions` + +Where the `Option` represents an optional seed for initialization. + +## Dependencies + +- **deno_webidl**: Provided by the `deno_webidl` crate +- **deno_web**: Provided by the `deno_web` crate + +## Provided ops + +Following ops are provided, which can be accessed through `Deno.ops`: + +- op_crypto_get_random_values +- op_crypto_generate_key +- op_crypto_sign_key +- op_crypto_verify_key +- op_crypto_derive_bits +- op_crypto_import_key +- op_crypto_export_key +- op_crypto_encrypt +- op_crypto_decrypt +- op_crypto_subtle_digest +- op_crypto_random_uuid +- op_crypto_wrap_key +- op_crypto_unwrap_key +- op_crypto_base64url_decode +- op_crypto_base64url_encode +- x25519::op_crypto_generate_x25519_keypair +- x25519::op_crypto_derive_bits_x25519 +- x25519::op_crypto_import_spki_x25519 +- x25519::op_crypto_import_pkcs8_x25519 +- ed25519::op_crypto_generate_ed25519_keypair +- ed25519::op_crypto_import_spki_ed25519 +- ed25519::op_crypto_import_pkcs8_ed25519 +- ed25519::op_crypto_sign_ed25519 +- ed25519::op_crypto_verify_ed25519 +- ed25519::op_crypto_export_spki_ed25519 +- ed25519::op_crypto_export_pkcs8_ed25519 +- ed25519::op_crypto_jwk_x_ed25519 +- x25519::op_crypto_export_spki_x25519 +- x25519::op_crypto_export_pkcs8_x25519 diff --git a/ext/fetch/README.md b/ext/fetch/README.md index 2c946197e053bc..d088a6147c14a4 100644 --- a/ext/fetch/README.md +++ b/ext/fetch/README.md @@ -1,5 +1,83 @@ # deno_fetch -This crate implements the Fetch API. +**This crate implements the Fetch API.** Spec: https://fetch.spec.whatwg.org/ + +## Usage Example + +From javascript, include the extension's source, and assign the following +properties to the global scope: + +```javascript +import * as headers from "ext:deno_fetch/20_headers.js"; +import * as formData from "ext:deno_fetch/21_formdata.js"; +import * as request from "ext:deno_fetch/23_request.js"; +import * as response from "ext:deno_fetch/23_response.js"; +import * as fetch from "ext:deno_fetch/26_fetch.js"; +import * as eventSource from "ext:deno_fetch/27_eventsource.js"; + +// Set up the callback for Wasm streaming ops +Deno.core.setWasmStreamingCallback(fetch.handleWasmStreaming); + +Object.defineProperty(globalThis, "fetch", { + value: fetch.fetch, + enumerable: true, + configurable: true, + writable: true, +}); + +Object.defineProperty(globalThis, "Request", { + value: request.Request, + enumerable: false, + configurable: true, + writable: true, +}); + +Object.defineProperty(globalThis, "Response", { + value: response.Response, + enumerable: false, + configurable: true, + writable: true, +}); + +Object.defineProperty(globalThis, "Headers", { + value: headers.Headers, + enumerable: false, + configurable: true, + writable: true, +}); + +Object.defineProperty(globalThis, "FormData", { + value: formData.FormData, + enumerable: false, + configurable: true, + writable: true, +}); +``` + +Then from rust, provide +`deno_fetch::deno_fetch::init_ops_and_esm(Default::default())` in +the `extensions` field of your `RuntimeOptions` + +Where: + +- Permissions: a struct implementing `deno_fetch::FetchPermissions` +- Options: `deno_fetch::Options`, which implements `Default` + +## Dependencies + +- **deno_webidl**: Provided by the `deno_webidl` crate +- **deno_web**: Provided by the `deno_web` crate +- **deno_url**: Provided by the `deno_url` crate +- **deno_console**: Provided by the `deno_console` crate + +## Provided ops + +Following ops are provided, which can be accessed through `Deno.ops`: + +- op_fetch +- op_fetch_send +- op_fetch_response_upgrade +- op_utf8_to_byte_string +- op_fetch_custom_client diff --git a/ext/io/README.md b/ext/io/README.md index b66dda76e6ff98..3aef61b0b395e6 100644 --- a/ext/io/README.md +++ b/ext/io/README.md @@ -1,4 +1,24 @@ # deno_io -This crate provides IO primitives for other Deno extensions, this includes stdio -streams and abstraction over File System files. +**This crate provides IO primitives for other Deno extensions, this includes +stdio streams and abstraction over File System files.** + +## Usage Example + +From javascript, include the extension's source: + +```javascript +import * as io from "ext:deno_io/12_io.js"; +``` + +Then from rust, provide: +`deno_io::deno_io::init_ops_and_esm(Option)` in the `extensions` +field of your `RuntimeOptions` + +Where `deno_io::Stdio` implements `Default`, and can therefore be provided as +`Some(deno_io::Stdio::default())` + +## Dependencies + +- **deno_web**: Provided by the `deno_web` crate +- **deno_tty**: Provided in `deno/runtime/ops/tty.rs` diff --git a/ext/net/README.md b/ext/net/README.md index 1f9301a2d83936..915dd4c05a70d9 100644 --- a/ext/net/README.md +++ b/ext/net/README.md @@ -1,29 +1,95 @@ # deno_net -This crate implements networking APIs. - -This crate depends on following extensions: - -- "deno_web" -- "deno_fetch" - -Following ops are provided: - -- "op_net_accept_tcp" -- "op_net_accept_unix" -- "op_net_connect_tcp" -- "op_net_connect_unix" -- "op_net_listen_tcp" -- "op_net_listen_udp" -- "op_net_listen_unix" -- "op_net_listen_unixpacket" -- "op_net_recv_udp" -- "op_net_recv_unixpacket" -- "op_net_send_udp" -- "op_net_send_unixpacket" -- "op_dns_resolve" -- "op_net_connect_tls" -- "op_net_listen_tls" -- "op_net_accept_tls" -- "op_tls_start" -- "op_tls_handshake" +**This crate implements networking APIs.** + +## Usage Example + +From javascript, include the extension's source: + +```javascript +import * as webidl from "ext:deno_webidl/00_webidl.js"; +import * as net from "ext:deno_net/01_net.js"; +import * as tls from "ext:deno_net/02_tls.js"; +``` + +Then from rust, provide: +`deno_net::deno_net::init_ops_and_esm::(root_cert_store_provider, unsafely_ignore_certificate_errors)` + +Where: + +- root_cert_store_provider: `Option>` +- unsafely_ignore_certificate_errors: `Option>` +- Permissions: A struct implementing `deno_net::NetPermissions` + +In the `extensions` field of your `RuntimeOptions` + +## Dependencies + +- **deno_web**: Provided by the `deno_web` crate +- **deno_fetch**: Provided by the `deno_fetch` crate + +## Provided ops + +Following ops are provided, which can be accessed through `Deno.ops`: + +### Net + +- op_net_accept_tcp +- op_net_accept_unix +- op_net_connect_tcp +- op_net_connect_unix +- op_net_listen_tcp +- op_net_listen_udp +- op_net_listen_unix +- op_net_listen_unixpacket +- op_net_recv_udp +- op_net_recv_unixpacket +- op_net_send_udp +- op_net_send_unixpacket +- op_net_connect_tls +- op_net_listen_tls +- op_net_accept_tls +- op_net_recv_udp +- op_net_send_udp +- op_net_join_multi_v4_udp +- op_net_join_multi_v6_udp +- op_net_leave_multi_v4_udp +- op_net_leave_multi_v6_udp +- op_net_set_multi_loopback_udp +- op_net_set_multi_ttl_udp +- op_net_accept_tcp +- op_net_connect_tcp +- op_net_listen_tcp +- op_net_listen_udp +- op_net_connect_tls +- op_net_listen_tls +- op_net_accept_tls +- op_net_accept_unix +- op_net_connect_unix +- op_net_listen_unix +- op_net_listen_unixpacket +- op_net_recv_unixpacket +- op_net_send_unixpacket + +### TLS + +- op_tls_start +- op_tls_handshake +- op_tls_key_null +- op_tls_key_static +- op_tls_key_static_from_file +- op_tls_cert_resolver_create +- op_tls_cert_resolver_poll +- op_tls_cert_resolver_resolve +- op_tls_cert_resolver_resolve_error +- op_tls_start +- op_tls_handshake + +### Other + +- op_node_unstable_net_listen_udp +- op_dns_resolve +- op_dns_resolve +- op_set_nodelay +- op_set_keepalive +- op_node_unstable_net_listen_unixpacket diff --git a/ext/url/README.md b/ext/url/README.md index 519c2823eb77f7..ba2bbb4d361776 100644 --- a/ext/url/README.md +++ b/ext/url/README.md @@ -1,6 +1,57 @@ # deno_url -This crate implements the URL, and URLPattern APIs for Deno. +**This crate implements the URL, and URLPattern APIs for Deno.** URL Spec: https://url.spec.whatwg.org/ URLPattern Spec: https://wicg.github.io/urlpattern/ + +## Usage Example + +From javascript, include the extension's source, and assign `URL`, `URLPattern`, +and `URLSearchParams` to the global scope: + +```javascript +import * as url from "ext:deno_url/00_url.js"; +import * as urlPattern from "ext:deno_url/01_urlpattern.js"; + +Object.defineProperty(globalThis, "URL", { + value: url.URL, + enumerable: false, + configurable: true, + writable: true, +}); + +Object.defineProperty(globalThis, "URLPattern", { + value: url.URLPattern, + enumerable: false, + configurable: true, + writable: true, +}); + +Object.defineProperty(globalThis, "URLSearchParams", { + value: url.URLSearchParams, + enumerable: false, + configurable: true, + writable: true, +}); +``` + +Then from rust, provide `deno_url::deno_url::init_ops_and_esm()` in the +`extensions` field of your `RuntimeOptions` + +## Dependencies + +- **deno_webidl**: Provided by the `deno_webidl` crate + +## Provided ops + +Following ops are provided, which can be accessed through `Deno.ops`: + +- op_url_reparse +- op_url_parse +- op_url_get_serialization +- op_url_parse_with_base +- op_url_parse_search_params +- op_url_stringify_search_params +- op_urlpattern_parse +- op_urlpattern_process_match_input diff --git a/ext/web/README.md b/ext/web/README.md index d847ae52ea113c..12e49416e7f123 100644 --- a/ext/web/README.md +++ b/ext/web/README.md @@ -1,6 +1,154 @@ # deno web -Op crate that implements Event, TextEncoder, TextDecoder and File API -(https://w3c.github.io/FileAPI). +**Implements timers, as well as the following APIs:** -Testing for text encoding is done via WPT in cli/. +- Event +- TextEncoder +- TextDecoder +- File (Spec: https://w3c.github.io/FileAPI) + +_Note: Testing for text encoding is done via WPT in cli/._ + +## Usage Example + +From javascript, include the extension's source: + +```javascript +import * as infra from "ext:deno_web/00_infra.js"; +import * as DOMException from "ext:deno_web/01_dom_exception.js"; +import * as mimesniff from "ext:deno_web/01_mimesniff.js"; +import * as event from "ext:deno_web/02_event.js"; +import * as structuredClone from "ext:deno_web/02_structured_clone.js"; +import * as timers from "ext:deno_web/02_timers.js"; +import * as abortSignal from "ext:deno_web/03_abort_signal.js"; +import * as globalInterfaces from "ext:deno_web/04_global_interfaces.js"; +import * as base64 from "ext:deno_web/05_base64.js"; +import * as streams from "ext:deno_web/06_streams.js"; +import * as encoding from "ext:deno_web/08_text_encoding.js"; +import * as file from "ext:deno_web/09_file.js"; +import * as fileReader from "ext:deno_web/10_filereader.js"; +import * as location from "ext:deno_web/12_location.js"; +import * as messagePort from "ext:deno_web/13_message_port.js"; +import * as compression from "ext:deno_web/14_compression.js"; +import * as performance from "ext:deno_web/15_performance.js"; +import * as imageData from "ext:deno_web/16_image_data.js"; +``` + +Then assign the properties below to the global scope like this example: + +```javascript +Object.defineProperty(globalThis, "AbortController", { + value: abortSignal.AbortController, + enumerable: false, + configurable: true, + writable: true, +}); +``` + +| Name | Value | enumerable | configurable | writeable | +| -------------------------------- | ---------------------------------------- | ---------- | ------------ | --------- | +| AbortController | abortSignal.AbortController | false | true | true | +| AbortSignal | abortSignal.AbortSignal | false | true | true | +| Blob | file.Blob | false | true | true | +| ByteLengthQueuingStrategy | streams.ByteLengthQueuingStrategy | | | | +| CloseEvent | event.CloseEvent | false | true | true | +| CompressionStream | compression.CompressionStream | false | true | true | +| CountQueuingStrategy | streams.CountQueuingStrategy | | | | +| CustomEvent | event.CustomEvent | false | true | true | +| DecompressionStream | compression.DecompressionStream | false | true | true | +| DOMException | DOMException | false | true | true | +| ErrorEvent | event.ErrorEvent | false | true | true | +| Event | event.Event | false | true | true | +| EventTarget | event.EventTarget | false | true | true | +| File | file.File | false | true | true | +| FileReader | fileReader.FileReader | false | true | true | +| MessageEvent | event.MessageEvent | false | true | true | +| Performance | performance.Performance | false | true | true | +| PerformanceEntry | performance.PerformanceEntry | false | true | true | +| PerformanceMark | performance.PerformanceMark | false | true | true | +| PerformanceMeasure | performance.PerformanceMeasure | false | true | true | +| PromiseRejectionEvent | event.PromiseRejectionEvent | false | true | true | +| ProgressEvent | event.ProgressEvent | false | true | true | +| ReadableStream | streams.ReadableStream | false | true | true | +| ReadableStreamDefaultReader | streams.ReadableStreamDefaultReader | | | | +| TextDecoder | encoding.TextDecoder | false | true | true | +| TextEncoder | encoding.TextEncoder | false | true | true | +| TextDecoderStream | encoding.TextDecoderStream | false | true | true | +| TextEncoderStream | encoding.TextEncoderStream | false | true | true | +| TransformStream | streams.TransformStream | false | true | true | +| MessageChannel | messagePort.MessageChannel | false | true | true | +| MessagePort | messagePort.MessagePort | false | true | true | +| WritableStream | streams.WritableStream | false | true | true | +| WritableStreamDefaultWriter | streams.WritableStreamDefaultWriter | | | | +| WritableStreamDefaultController | streams.WritableStreamDefaultController | | | | +| ReadableByteStreamController | streams.ReadableByteStreamController | | | | +| ReadableStreamBYOBReader | streams.ReadableStreamBYOBReader | | | | +| ReadableStreamBYOBRequest | streams.ReadableStreamBYOBRequest | | | | +| ReadableStreamDefaultController | streams.ReadableStreamDefaultController | | | | +| TransformStreamDefaultController | streams.TransformStreamDefaultController | | | | +| ImageData | imageData.ImageData | false | true | true | +| atob | base64.atob | true | true | true | +| btoa | base64.btoa | true | true | true | +| clearInterval | timers.clearInterval | true | true | true | +| clearTimeout | timers.clearTimeout | true | true | true | +| performance | performance.performance | true | true | true | +| reportError | event.reportError | true | true | true | +| setInterval | timers.setInterval | true | true | true | +| setTimeout | timers.setTimeout | true | true | true | +| structuredClone | messagePort.structuredClone | true | true | true | + +Then from rust, provide: +`deno_web::deno_web::init_ops_and_esm::(Arc, Option)` +in the `extensions` field of your `RuntimeOptions` + +Where: + +- `Permissions` is a struct implementing `deno_web::TimersPermission` +- `Arc` can be provided by `Default::default()` +- `Option` provides an optional base URL for certain ops + +## Dependencies + +- **deno_webidl**: Provided by the `deno_webidl` crate +- **deno_console**: Provided by the `deno_console` crate +- **deno_url**: Provided by the `deno_url` crate + +## Provided ops + +Following ops are provided, which can be accessed through `Deno.ops`: + +- op_base64_decode +- op_base64_encode +- op_base64_atob +- op_base64_btoa +- op_encoding_normalize_label +- op_encoding_decode_single +- op_encoding_decode_utf8 +- op_encoding_new_decoder +- op_encoding_decode +- op_encoding_encode_into +- op_blob_create_part +- op_blob_slice_part +- op_blob_read_part +- op_blob_remove_part +- op_blob_create_object_url +- op_blob_revoke_object_url +- op_blob_from_object_url +- op_message_port_create_entangled +- op_message_port_post_message +- op_message_port_recv_message +- op_message_port_recv_message_sync +- op_compression_new +- op_compression_write +- op_compression_finish +- op_now +- op_defer +- op_transfer_arraybuffer +- op_readable_stream_resource_allocate +- op_readable_stream_resource_allocate_sized +- op_readable_stream_resource_get_sink +- op_readable_stream_resource_write_error +- op_readable_stream_resource_write_buf +- op_readable_stream_resource_write_sync +- op_readable_stream_resource_close +- op_readable_stream_resource_await_close diff --git a/ext/webidl/README.md b/ext/webidl/README.md index cc4ccc6e98a3ad..0b52c6fbde3d0a 100644 --- a/ext/webidl/README.md +++ b/ext/webidl/README.md @@ -1,6 +1,24 @@ # deno_webidl -This crate implements WebIDL for Deno. It consists of infrastructure to do ECMA --> WebIDL conversions. +**This crate implements WebIDL for Deno. It consists of infrastructure to do +ECMA -> WebIDL conversions.** Spec: https://webidl.spec.whatwg.org/ + +## Usage Example + +From javascript, include the extension's source, and assign the following to the +global scope: + +```javascript +import * as webidl from "ext:deno_webidl/00_webidl.js"; +Object.defineProperty(globalThis, webidl.brand, { + value: webidl.brand, + enumerable: false, + configurable: true, + writable: true, +}); +``` + +Then from rust, provide `init_webidl::init_webidl::init_ops_and_esm()` in the +`extensions` field of your `RuntimeOptions`