foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-12-22 07:14:47 -05:00
Code Issues Packages 1 Wiki Activity

docs: Add documentation to a subset of available extensions (#24138)

Browse source 
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 <Rscarson@rogers.com>
This commit is contained in:
Richard Carson 2024-06-17 18:07:48 -04:00 committed by GitHub
parent 5dec3fd4b7
commit 257f027325
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 523 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
ext/console/README.md
View file

@ -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

84
ext/crypto/README.md
View file

@ -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

80
ext/fetch/README.md
View file

@ -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

24
ext/io/README.md
View file

@ -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`

112
ext/net/README.md
View file

@ -1,29 +1,95 @@
# deno_net
This crate implements networking APIs.
**This crate implements networking APIs.**
This crate depends on following extensions:
## Usage Example
- "deno_web"
- "deno_fetch"
From javascript, include the extension's source:
Following ops are provided:
```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";
```
- "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"
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

53
ext/url/README.md
View file

@ -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

154
ext/web/README.md
View file

@ -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::<Permissions>(Arc<BlobStore>, Option<Url>)`
in the `extensions` field of your `RuntimeOptions`
Where:
- `Permissions` is a struct implementing `deno_web::TimersPermission`
- `Arc<BlobStore>` can be provided by `Default::default()`
- `Option<Url>` 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

22
ext/webidl/README.md
View file

@ -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`