Skip to content

docs: add examples for uncovered runtime APIs and remaining stragglers#3238

Open
bartlomieju wants to merge 1 commit into
mainfrom
api-gaps-examples
Open

docs: add examples for uncovered runtime APIs and remaining stragglers#3238
bartlomieju wants to merge 1 commit into
mainfrom
api-gaps-examples

Conversation

@bartlomieju

Copy link
Copy Markdown
Member

A coverage analysis of the Deno namespace against the examples catalog
showed that after the recent expansion, the remaining holes cluster in a
few areas: FFI had no example at all, and neither did Deno.bundle, the
Deno.jupyter display API, or the newer networking APIs (startTls, QUIC,
WebTransport). This PR fills those gaps and picks up the remaining small,
locally verifiable items from the examples backlog, taking the catalog
from 316 to 330 items.

New examples: Call C functions with FFI (dlopen plus UnsafeCallback via
qsort), Bundle code with Deno.bundle, Rich output in Jupyter notebooks,
Upgrade a TCP connection to TLS (STARTTLS), Communicate over QUIC,
Connect two peers with WebTransport, Two-way streaming with
WebSocketStream, Atomic transactions in Deno KV, Run a compute shader
with WebGPU, Extract front matter from markdown, Generate seeded random
numbers, Parse and generate XML, and Distribute work across a worker
pool. One new tutorial: Publish a package to JSR, a step-by-step guide
including dry runs and OIDC-based publishing from GitHub Actions.

Every script was run and its output captured rather than invented: the
STARTTLS example performs a real SMTP upgrade handshake, the QUIC and
WebTransport examples run a server and client in one process against a
self-signed certificate, the WebGPU shader was executed on a real
adapter, and the publish tutorial's dry run output comes from an actual
deno publish --dry-run. Unstable APIs carry the standard warning banner
and the matching --unstable-* flags in their run lines.

Two backlog items were intentionally dropped rather than written: custom
OpenTelemetry spans and metrics are already covered by the basic
OpenTelemetry setup tutorial, so separate examples would have duplicated
it. The KV atomic transactions example goes deeper than the existing KV
intro (transfer with retry on conflict, sum mutations, failed checks)
and cross-links it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant