api/documentation

27 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Standard Library documentation generation process

The script scripts/generate_std_docs.ts fetches overview HTML for every @std/* package from JSR. It writes or overwrites runtime/reference/std/<package>.md with frontmatter (title, description, version, stability), an optional stability banner, the package overview (HTML fragment), an Additional Examples section containing override markdown if a file named _overrides/<package>.md exists, and a preserved custom block.

How to add override content to standard library documentation

Create a file named after the package in _overrides/ directory, for example _overrides/internal.md. Put any extra examples, guides, etc. in that file. On the next generation run it will appear under an 'Additional Examples' heading. Do not include frontmatter (--- ... ---) in override files as they are appended verbatim and frontmatter will show up as plain text. Keep overrides to content sections (headings, paragraphs, code blocks, images). To change title/description/stability, edit the generated page's frontmatter or adjust upstream JSR package metadata, not in override files.

Custom block markers for persistent edits in generated documentation

To add content directly inside a generated page and keep it across regenerations, use custom block markers:  for the opening marker and  for the closing marker. Anything between those markers is preserved every time the generator runs. If a page has no custom block yet, a commented placeholder will be added for convenience.

Safety notes for editing standard library documentation

Do not edit outside the custom block as those areas will be replaced by the generator. If you rename or remove the custom block markers, the content will be lost on the next run. Overrides (_overrides/<pkg>.md) are never modified by the generator; they are simply read and injected.

Example of standard library documentation override content

Example for _overrides/internal.md showing how to document diff utilities: ```ts import { diffStr } from "jsr:@std/internal"; console.log(diffStr("a", "b")); ``` This example demonstrates importing and using a diff utility from the @std/internal package.

@std/internal is internal-only

The @std/internal package is for internal use and not intended for public consumption. APIs may change or be removed without notice.

@std/internal version and JSR reference

The @std/internal package has version 1.0.12 and is available at jsr:@std/internal.

@std/internal stability classification

The @std/internal package is marked with stability: internal, indicating it is not part of the public API.

@std/log package deprecation status

@std/log is a customizable logger framework that is no longer recommended and is likely to be removed in the future. Users should consider using OpenTelemetry for production systems instead.

@std/log package details

@std/log is available at jsr:@std/log with version 0.224.14. The package stability is marked as unstable.

Deno TypeScript configuration design principles

Deno aims to simplify TypeScript configuration based on three design choices: strict and modern defaults for type-checking rules, allowing omission of settings relating to target runtime or compatibility by leveraging direct integration with the execution environment, and using project references via deno.json directory scopes instead of tsconfig.json's references and extends fields.

tsconfig.json compatibility in Deno

While tsconfig.json files are not recommended for Deno-first projects, existing Node.js + TypeScript workspaces using them will work out-of-the-box under Deno's type checker and LSP. Each workspace directory containing a deno.json or package.json is probed for a tsconfig.json. If found, it is added as a root project reference and contained references are included recursively.

tsconfig.json precedence rules in Deno

When determining the scope of a TSConfig: a reference takes precedence over its referrer; for root references, foo/bar/tsconfig.json takes precedence over foo/tsconfig.json; if a parent deno.json contains compilerOptions, that takes precedence over any TSConfig.

tsconfig.json fields supported in Deno

The following fields are supported in tsconfig.json: extends, files, include, exclude, references (with path property), and compilerOptions. Except for compilerOptions, these fields cannot be specified in deno.json.

TypeScript compiler options to delete when migrating from Node.js

Options that should be deleted when migrating from Node.js tsconfig.json to Deno: target, outDir, outFile, rootDir (delete - Deno never emits, code runs directly on latest V8, deno check type-checks without producing output); declaration, declarationMap, emitDeclarationOnly (delete - no emit, use deno doc for API documentation); sourceMap, inlineSourceMap, inlineSources (delete - stack traces map to TypeScript sources automatically); esModuleInterop, allowSyntheticDefaultImports (delete - Deno is ESM-native and handles CommonJS interop in runtime); importHelpers, noEmitHelpers, downlevelIteration (delete - no downleveling, no helpers emitted); resolveJsonModule (delete - import JSON with attribute instead: import data from "./data.json" with { type: "json" }); skipLibCheck (delete - Deno does not type-check dependencies by default, deno check --all opts in).

TypeScript compiler options to usually delete or keep when migrating

When migrating from Node.js tsconfig.json: module and moduleResolution - usually delete, Deno defaults to nodenext, supported values are nodenext, esnext, and preserve; lib and types - usually delete, Deno's defaults cover its runtime, keep lib only for cross-runtime code; strict, noImplicit*, noUnused*, and other check flags - keep the ones desired in deno.json's compilerOptions (Deno's defaults are already strict); paths and baseUrl - keep if needed for type-time path mapping, or replace with import maps which also work at runtime.

Deno TypeScript compiler options defaults

Complete table of TypeScript compiler options with Deno defaults: allowUnreachableCode (false), allowUnusedLabels (false), baseUrl ("./" - used for resolving bare specifier entries in paths and rootDirs, but never for bare specifiers in module imports), checkJs (false), jsx ("react"), jsxFactory ("React.createElement"), jsxFragmentFactory ("React.Fragment"), keyofStringsOnly (false), lib (["deno.window"] - default varies based on other settings, overrides default if supplied), module ("nodenext" - supported values: nodenext, esnext, preserve), moduleResolution ("nodenext" - supported values: nodenext, bundler), noErrorTruncation (false), noFallthroughCasesInSwitch (false), noImplicitAny (true), noImplicitOverride (true), noImplicitReturns (false), noImplicitThis (true), noImplicitUseStrict (true), noStrictGenericChecks (false), noUncheckedIndexedAccess (false), noUnusedLocals (false), noUnusedParameters (false), paths ({}), rootDirs (null), strict (true), strictBindCallApply (true), strictFunctionTypes (true), strictNullChecks (true), strictPropertyInitialization (true), suppressExcessPropertyErrors (false), suppressImplicitAnyIndexErrors (false), useUnknownInCatchVariables (true).

Deno built-in TypeScript libraries

Built-in libraries available in Deno: deno.ns (includes all custom Deno global namespace APIs plus Deno additions to import.meta, should generally not conflict with other libraries); deno.window (default library used when checking Deno main runtime scripts, includes deno.ns and other type libraries for built-in extensions, conflicts with libraries like dom and dom.iterable); deno.worker (used when checking Deno web worker script); dom.asynciterable (TypeScript does not include DOM async iterables that Deno implements); deno.desktop (used when checking apps created with deno desktop).

Common TypeScript libraries not enabled by default in Deno

Common libraries not enabled by default but useful for cross-runtime code: dom (main browser global library, type definitions conflict with deno.window, consider using just deno.ns to expose Deno specific APIs); dom.iterable (iterable extensions to browser global library); scripthost (library for Microsoft Windows Script Host); webworker (main library for web workers in browser, conflicts with deno.window or deno.worker, consider using just deno.ns); webworker.importscripts (exposes importScripts() API in web worker); webworker.iterable (adds iterables to objects within web worker).

Targeting Deno and browser with deno.json compilerOptions

To write code that runs seamlessly in both Deno and the browser, use this compilerOptions configuration: {"lib": ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]}. This allows most code to be type-checked properly by Deno.

Targeting Deno, browser, and unstable APIs

To target Deno, browser, and unstable APIs, use this compilerOptions configuration: {"lib": ["dom", "dom.iterable", "dom.asynciterable", "deno.ns", "deno.unstable"]}. When using deno.ns and deno.unstable, they automatically include esnext, so you don't need to explicitly include an ES library.

Type declaration file semantics in Deno

Type declaration files (.d.ts files) in Deno follow the same semantics as other files. Declaration files are assumed to be module declarations (UMD declarations), not ambient/global declarations, and it is unpredictable how Deno will handle ambient/global declarations. If a type declaration imports something like another .d.ts file, its resolution follows normal Deno import rules. Many .d.ts files generated and available on the web may not be compatible with Deno.

Disabling type declarations from HTTPS CDN imports

Type declarations are provided by default from HTTPS CDN imports like esm.sh via the X-TypeScript-Types header. This can be disabled by appending ?no-dts to the import URL. For most use cases, npm: specifiers are the recommended way to import npm packages.

JavaScript type checking behavior in Deno TypeScript

When importing JavaScript code into TypeScript within Deno, even if checkJs is set to false (Deno's default), the TypeScript compiler still analyzes the JavaScript module and tries to infer the shape of exports to validate the import in TypeScript files. This usually works with standard ES modules, but may fail with modules that have special packaging or are global UMD modules. In such cases, provide type information using methods like @ts-types, @ts-self-types, X-TypeScript-Types headers, or .d.ts files.

Web worker type checking with triple-slash directives

To instruct Deno to type-check a web worker script using triple-slash directives, add near the top of the worker script entry point: /// <reference no-default-lib="true" /> and /// <reference lib="deno.worker" />. The first directive ensures no other default libraries are used (without it, conflicting type definitions occur). The second instructs Deno to apply built-in Deno worker type definitions plus dependent libraries like esnext. A disadvantage is this makes code less portable to non-Deno platforms like tsc.

Web worker type checking with deno.json lib setting

To configure web worker type checking via deno.json, use: {"compilerOptions": {"target": "esnext", "lib": ["deno.worker"]}}. If you have non-worker scripts, consider using workspaces so each workspace member can have its own compilerOptions.

Deno module graph and TypeScript type checking internals

Before code execution or compilation, Deno generates a module graph by parsing the root module, detecting all dependencies, and recursively retrieving and parsing those modules. For each dependency, there are two slots: a code slot and a type slot. As the module graph is filled, code that can be emitted to JavaScript fills the code slot, while type-only dependencies like .d.ts files fill the type slot. When type checking, Deno starts the TypeScript compiler and feeds it module names needing potential JavaScript emission. During this, TypeScript requests additional modules, and Deno offers the type slot if filled before the code slot. This means when importing .d.ts modules or using alternative type modules for JavaScript code, that type information is provided to TypeScript instead.

Give your agent this brain