docs: Add documentation to a subset of available extensions (denoland…

…#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 <[email protected]>
eryue0220 · Jun 17, 2024 · 257f027 · 257f027
1 parent 5dec3fd
commit 257f027
Show file tree

Hide file tree

Showing 8 changed files with 527 additions and 38 deletions.
diff --git 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
@@ -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<u64>)` in the `extensions`
+field of your `RuntimeOptions`
+
+Where the `Option<u64>` 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
@@ -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<Permissions>(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
@@ -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<deno_io::Stdio>)` 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
@@ -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::<Permissions>(root_cert_store_provider, unsafely_ignore_certificate_errors)`
+
+Where:
+
+- root_cert_store_provider: `Option<Arc<dyn RootCertStoreProvider>>`
+- unsafely_ignore_certificate_errors: `Option<Vec<String>>`
+- 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