diff --git a/packages/deno/lib.deno.d.ts b/packages/deno/lib.deno.d.ts index 555614d581cf..b0833d622ce3 100644 --- a/packages/deno/lib.deno.d.ts +++ b/packages/deno/lib.deno.d.ts @@ -1,4 +1,4 @@ -// Copyright 2018-2025 the Deno authors. MIT license. +// Copyright 2018-2026 the Deno authors. MIT license. /// /// @@ -234,7 +234,7 @@ declare namespace Deno { * @category Errors */ export class AlreadyExists extends Error {} /** - * Raised when an operation to returns data that is invalid for the + * Raised when an operation returns data that is invalid for the * operation being performed. * * @category Errors */ @@ -248,7 +248,7 @@ declare namespace Deno { /** * Raised when the underlying operating system reports an `EINTR` error. In * many cases, this underlying IO error will be handled internally within - * Deno, or result in an @{link BadResource} error instead. + * Deno, or result in an {@link BadResource} error instead. * * @category Errors */ export class Interrupted extends Error {} @@ -1166,6 +1166,78 @@ declare namespace Deno { options: Omit, fn: (t: TestContext) => void | Promise, ): void; + + /** Register a function to be called before all tests in the current scope. + * + * These functions are run in FIFO order (first in, first out). + * + * If an exception is raised during execution of this hook, the remaining `beforeAll` hooks will not be run. + * + * ```ts + * Deno.test.beforeAll(() => { + * // Setup code that runs once before all tests + * console.log("Setting up test suite"); + * }); + * ``` + * + * @category Testing + */ + beforeAll( + fn: () => void | Promise, + ): void; + + /** Register a function to be called before each test in the current scope. + * + * These functions are run in FIFO order (first in, first out). + * + * If an exception is raised during execution of this hook, the remaining hooks will not be run and the currently running + * test case will be marked as failed. + * + * ```ts + * Deno.test.beforeEach(() => { + * // Setup code that runs before each test + * console.log("Setting up test"); + * }); + * ``` + * + * @category Testing + */ + beforeEach(fn: () => void | Promise): void; + + /** Register a function to be called after each test in the current scope. + * + * These functions are run in LIFO order (last in, first out). + * + * If an exception is raised during execution of this hook, the remaining hooks will not be run and the currently running + * test case will be marked as failed. + * + * ```ts + * Deno.test.afterEach(() => { + * // Cleanup code that runs after each test + * console.log("Cleaning up test"); + * }); + * ``` + * + * @category Testing + */ + afterEach(fn: () => void | Promise): void; + + /** Register a function to be called after all tests in the current scope have finished running. + * + * These functions are run in the LIFO order (last in, first out). + * + * If an exception is raised during execution of this hook, the remaining `afterAll` hooks will not be run. + * + * ```ts + * Deno.test.afterAll(() => { + * // Cleanup code that runs once after all tests + * console.log("Cleaning up test suite"); + * }); + * ``` + * + * @category Testing + */ + afterAll(fn: () => void | Promise): void; } /** @@ -1242,6 +1314,17 @@ declare namespace Deno { /** If at least one bench has `only` set to true, only run benches that have * `only` set to `true` and fail the bench suite. */ only?: boolean; + /** Number of iterations to perform. + * @remarks When the benchmark is very fast, this will only be used as a + * suggestion in order to get a more accurate measurement. + */ + n?: number; + /** Number of warmups to do before running the benchmark. + * @remarks A warmup will always be performed even if this is `0` in order to + * determine the speed of the benchmark in order to improve the measurement. When + * the benchmark is very fast, this will be used as a suggestion. + */ + warmup?: number; /** Ensure the bench case does not prematurely cause the process to exit, * for example via a call to {@linkcode Deno.exit}. * @@ -1499,7 +1582,7 @@ declare namespace Deno { * * ```ts * console.log(Deno.env.get("HOME")); // e.g. outputs "/home/alice" - * console.log(Deno.env.get("MADE_UP_VAR")); // outputs "undefined" + * console.log(Deno.env.get("MADE_UP_VAR")); // outputs undefined * ``` * * Requires `allow-env` permission. @@ -1580,9 +1663,6 @@ declare namespace Deno { * console.log(Deno.execPath()); // e.g. "/home/alice/.local/bin/deno" * ``` * - * Requires `allow-read` permission. - * - * @tags allow-read * @category Runtime */ export function execPath(): string; @@ -1620,9 +1700,6 @@ declare namespace Deno { * * Throws {@linkcode Deno.errors.NotFound} if directory not available. * - * Requires `allow-read` permission. - * - * @tags allow-read * @category Runtime */ export function cwd(): string; @@ -1786,7 +1863,7 @@ declare namespace Deno { * } * ``` */ - readonly readable: ReadableStream; + readonly readable: ReadableStream>; /** A {@linkcode WritableStream} instance to write the contents of the * file. This makes it easy to interoperate with other web streams based * APIs. @@ -1801,7 +1878,7 @@ declare namespace Deno { * } * ``` */ - readonly writable: WritableStream; + readonly writable: WritableStream>; /** Write the contents of the array buffer (`p`) to the file. * * Resolves to the number of bytes written. @@ -2110,8 +2187,7 @@ declare namespace Deno { * @category File System */ utimeSync(atime: number | Date, mtime: number | Date): void; - /** **UNSTABLE**: New API, yet to be vetted. - * + /** * Checks if the file resource is a TTY (terminal). * * ```ts @@ -2121,8 +2197,7 @@ declare namespace Deno { * ``` */ isTerminal(): boolean; - /** **UNSTABLE**: New API, yet to be vetted. - * + /** * Set TTY to be under raw mode or not. In raw mode, characters are read and * returned as is, without being processed. All special processing of * characters by the terminal is disabled, including echoing input @@ -2268,7 +2343,7 @@ declare namespace Deno { */ close(): void; /** A readable stream interface to `stdin`. */ - readonly readable: ReadableStream; + readonly readable: ReadableStream>; /** * Set TTY to be under raw mode or not. In raw mode, characters are read and * returned as is, without being processed. All special processing of @@ -2346,7 +2421,7 @@ declare namespace Deno { */ close(): void; /** A writable stream interface to `stdout`. */ - readonly writable: WritableStream; + readonly writable: WritableStream>; /** * Checks if `stdout` is a TTY (terminal). * @@ -2410,7 +2485,7 @@ declare namespace Deno { */ close(): void; /** A writable stream interface to `stderr`. */ - readonly writable: WritableStream; + readonly writable: WritableStream>; /** * Checks if `stderr` is a TTY (terminal). * @@ -2695,7 +2770,8 @@ declare namespace Deno { * | 1 | execute only | * | 0 | no permission | * - * NOTE: This API currently throws on Windows + * Note: On Windows, only the read and write permissions can be modified. + * Distinctions between owner, group, and others are not supported. * * Requires `allow-write` permission. * @@ -2713,8 +2789,6 @@ declare namespace Deno { * * For a full description, see {@linkcode Deno.chmod}. * - * NOTE: This API currently throws on Windows - * * Requires `allow-write` permission. * * @tags allow-write @@ -2905,7 +2979,7 @@ declare namespace Deno { /** Reads and resolves to the entire contents of a file as an array of bytes. * `TextDecoder` can be used to transform the bytes to string if required. - * Reading a directory returns an empty data array. + * Rejects with an error when reading a directory. * * ```ts * const decoder = new TextDecoder("utf-8"); @@ -2921,11 +2995,11 @@ declare namespace Deno { export function readFile( path: string | URL, options?: ReadFileOptions, - ): Promise; + ): Promise>; /** Synchronously reads and returns the entire contents of a file as an array * of bytes. `TextDecoder` can be used to transform the bytes to string if - * required. Reading a directory returns an empty data array. + * required. Throws an error when reading a directory. * * ```ts * const decoder = new TextDecoder("utf-8"); @@ -2938,7 +3012,7 @@ declare namespace Deno { * @tags allow-read * @category File System */ - export function readFileSync(path: string | URL): Uint8Array; + export function readFileSync(path: string | URL): Uint8Array; /** Provides information about a file and is returned by * {@linkcode Deno.stat}, {@linkcode Deno.lstat}, {@linkcode Deno.statSync}, @@ -2977,17 +3051,15 @@ declare namespace Deno { ctime: Date | null; /** ID of the device containing the file. */ dev: number; - /** Inode number. - * - * _Linux/Mac OS only._ */ + /** Corresponds to the inode number on Unix systems. On Windows, this is + * the file index number that is unique within a volume. This may not be + * available on all platforms. */ ino: number | null; /** The underlying raw `st_mode` bits that contain the standard Unix * permissions for this file/directory. */ mode: number | null; - /** Number of hard links pointing to this file. - * - * _Linux/Mac OS only._ */ + /** Number of hard links pointing to this file. */ nlink: number | null; /** User ID of the owner of this file. * @@ -3005,9 +3077,7 @@ declare namespace Deno { * * _Linux/Mac OS only._ */ blksize: number | null; - /** Number of blocks allocated to the file, in 512-byte units. - * - * _Linux/Mac OS only._ */ + /** Number of blocks allocated to the file, in 512-byte units. */ blocks: number | null; /** True if this is info for a block device. * @@ -3124,7 +3194,7 @@ declare namespace Deno { * @tags allow-read * @category File System */ - export function readDirSync(path: string | URL): Iterable; + export function readDirSync(path: string | URL): IteratorObject; /** Copies the contents and permissions of one file to another specified path, * by default creating a new file if needed, else overwriting. Fails if target @@ -3433,24 +3503,6 @@ declare namespace Deno { */ export function truncateSync(name: string, len?: number): void; - /** @category Runtime - * - * @deprecated This will be removed in Deno 2.0. - */ - export interface OpMetrics { - opsDispatched: number; - opsDispatchedSync: number; - opsDispatchedAsync: number; - opsDispatchedAsyncUnref: number; - opsCompleted: number; - opsCompletedSync: number; - opsCompletedAsync: number; - opsCompletedAsyncUnref: number; - bytesSentControl: number; - bytesSentData: number; - bytesReceived: number; - } - /** * Additional information for FsEvent objects with the "other" kind. * @@ -3731,9 +3783,9 @@ declare namespace Deno { * @category Subprocess */ export class ChildProcess implements AsyncDisposable { - get stdin(): WritableStream; - get stdout(): ReadableStream; - get stderr(): ReadableStream; + get stdin(): WritableStream>; + get stdout(): SubprocessReadableStream; + get stderr(): SubprocessReadableStream; readonly pid: number; /** Get the status of the child. */ readonly status: Promise; @@ -3741,13 +3793,13 @@ declare namespace Deno { /** Waits for the child to exit completely, returning all its output and * status. */ output(): Promise; - /** Kills the process with given {@linkcode Deno.Signal}. + /** Kills the process with given {@linkcode Deno.Signal} or numeric signal. * * Defaults to `SIGTERM` if no signal is provided. * * @param [signo="SIGTERM"] */ - kill(signo?: Signal): void; + kill(signo?: Signal | number): void; /** Ensure that the status of the child process prevents the Deno process * from exiting. */ @@ -3759,6 +3811,36 @@ declare namespace Deno { [Symbol.asyncDispose](): Promise; } + /** + * The interface for stdout and stderr streams for child process returned from + * {@linkcode Deno.Command.spawn}. + * + * @category Subprocess + */ + export interface SubprocessReadableStream + extends ReadableStream> { + /** + * Reads the stream to completion. It returns a promise that resolves with + * an `ArrayBuffer`. + */ + arrayBuffer(): Promise; + /** + * Reads the stream to completion. It returns a promise that resolves with + * a `Uint8Array`. + */ + bytes(): Promise>; + /** + * Reads the stream to completion. It returns a promise that resolves with + * the result of parsing the body text as JSON. + */ + json(): Promise; + /** + * Reads the stream to completion. It returns a promise that resolves with + * a `USVString` (text). + */ + text(): Promise; + } + /** * Options which can be set when calling {@linkcode Deno.Command}. * @@ -3821,6 +3903,20 @@ declare namespace Deno { * * @default {false} */ windowsRawArguments?: boolean; + + /** Whether to detach the spawned process from the current process. + * This allows the spawned process to continue running after the current + * process exits. + * + * Note: In order to allow the current process to exit, you need to ensure + * you call `unref()` on the child process. + * + * In addition, the stdio streams – if inherited or piped – may keep the + * current process from exiting until the streams are closed. + * + * @default {false} + */ + detached?: boolean; } /** @@ -3845,9 +3941,9 @@ declare namespace Deno { */ export interface CommandOutput extends CommandStatus { /** The buffered output from the child process' `stdout`. */ - readonly stdout: Uint8Array; + readonly stdout: Uint8Array; /** The buffered output from the child process' `stderr`. */ - readonly stderr: Uint8Array; + readonly stderr: Uint8Array; } /** Option which can be specified when performing {@linkcode Deno.inspect}. @@ -4081,6 +4177,21 @@ declare namespace Deno { path?: string | URL; } + /** The permission descriptor for the `allow-import` and `deny-import` permissions, which controls + * access to importing from remote hosts via the network. The option `host` allows scoping the + * permission for outbound connection to a specific host and port. + * + * @category Permissions */ + export interface ImportPermissionDescriptor { + name: "import"; + /** Optional host string of the form `"[:]"`. Examples: + * + * "github.com" + * "deno.land:8080" + */ + host?: string; + } + /** Permission descriptors which define a permission and can be queried, * requested, or revoked. * @@ -4096,7 +4207,8 @@ declare namespace Deno { | NetPermissionDescriptor | EnvPermissionDescriptor | SysPermissionDescriptor - | FfiPermissionDescriptor; + | FfiPermissionDescriptor + | ImportPermissionDescriptor; /** The interface which defines what event types are supported by * {@linkcode PermissionStatus} instances. @@ -4358,6 +4470,7 @@ declare namespace Deno { | "aix" | "solaris" | "illumos"; + standalone: boolean; /** The computer vendor that the Deno CLI was built for. */ vendor: string; /** Optional environment flags that were set for this build of Deno CLI. */ @@ -4395,13 +4508,13 @@ declare namespace Deno { * Give the following command line invocation of Deno: * * ```sh - * deno run --allow-read https://examples.deno.land/command-line-arguments.ts Sushi + * deno eval "console.log(Deno.args)" Sushi Maguro Hamachi * ``` * * Then `Deno.args` will contain: * * ```ts - * [ "Sushi" ] + * [ "Sushi", "Maguro", "Hamachi" ] * ``` * * If you are looking for a structured way to parse arguments, there is @@ -4623,12 +4736,14 @@ declare namespace Deno { * Deno.kill(child.pid, "SIGINT"); * ``` * + * As a special case, a signal of 0 can be used to test for the existence of a process. + * * Requires `allow-run` permission. * * @tags allow-run * @category Subprocess */ - export function kill(pid: number, signo?: Signal): void; + export function kill(pid: number, signo?: Signal | number): void; /** The type of the resource record to resolve via DNS using * {@linkcode Deno.resolveDns}. @@ -5087,6 +5202,12 @@ declare namespace Deno { * @category HTTP Server */ fetch: ServeHandler; + /** + * The callback which is called when the server starts listening. + * + * @category HTTP Server + */ + onListen?: (localAddr: Deno.Addr) => void; } /** Options which can be set when calling {@linkcode Deno.serve}. @@ -5133,6 +5254,18 @@ declare namespace Deno { /** Sets `SO_REUSEPORT` on POSIX systems. */ reusePort?: boolean; + + /** Maximum number of pending connections in the listen queue. + * + * This parameter controls how many incoming connections can be queued by the + * operating system while waiting for the application to accept them. If more + * connections arrive when the queue is full, they will be refused. + * + * The kernel may adjust this value (e.g., rounding up to the next power of 2 + * plus 1). Different operating systems have different maximum limits. + * + * @default {511} */ + tcpBacklog?: number; } /** @@ -5149,6 +5282,25 @@ declare namespace Deno { path: string; } + /** + * Options that can be passed to `Deno.serve` to create a server listening on + * a VSOCK socket. + * + * @experimental **UNSTABLE**: New API, yet to be vetted. + * + * @category HTTP Server + */ + export interface ServeVsockOptions extends ServeOptions { + /** The transport to use. */ + transport?: "vsock"; + + /** The context identifier to use. */ + cid: number; + + /** The port to use. */ + port: number; + } + /** * @category HTTP Server */ @@ -5250,6 +5402,60 @@ declare namespace Deno { options: ServeUnixOptions, handler: ServeHandler, ): HttpServer; + /** Serves HTTP requests with the given option bag and handler. + * + * @experimental **UNSTABLE**: New API, yet to be vetted. + * + * You can specify an object with the cid and port options for the VSOCK interface. + * + * The VSOCK address family facilitates communication between virtual machines and the host they are running on: https://man7.org/linux/man-pages/man7/vsock.7.html + * + * ```ts + * Deno.serve( + * { cid: -1, port: 3000 }, + * (_req) => new Response("Hello, world") + * ); + * ``` + * + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. + * + * ```ts + * const ac = new AbortController(); + * + * const server = Deno.serve( + * { signal: ac.signal, cid: -1, port: 3000 }, + * (_req) => new Response("Hello, world") + * ); + * server.finished.then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * By default `Deno.serve` prints the message `Listening on cid:port`. + * If you want to change this behavior, you can specify a custom `onListen` + * callback. + * + * ```ts + * Deno.serve({ + * onListen({ cid, port }) { + * console.log(`Server started at ${cid}:${port}`); + * // ... more info specific to your server .. + * }, + * cid: -1, + * port: 3000, + * }, (_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ + export function serve( + options: ServeVsockOptions, + handler: ServeHandler, + ): HttpServer; /** Serves HTTP requests with the given option bag and handler. * * You can specify an object with a port and hostname option, which is the @@ -5337,6 +5543,37 @@ declare namespace Deno { export function serve( options: ServeUnixOptions & ServeInit, ): HttpServer; + /** Serves HTTP requests with the given option bag. + * + * The VSOCK address family facilitates communication between virtual machines and the host they are running on: https://man7.org/linux/man-pages/man7/vsock.7.html + * + * @experimental **UNSTABLE**: New API, yet to be vetted. + * + * You can specify an object with the cid and port options for the VSOCK interface. + * + * ```ts + * const ac = new AbortController(); + * + * const server = Deno.serve({ + * cid: -1, + * port: 3000, + * handler: (_req) => new Response("Hello, world"), + * signal: ac.signal, + * onListen({ cid, port }) { + * console.log(`Server started at ${cid}:${port}`); + * }, + * }); + * server.finished.then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * @category HTTP Server + */ + export function serve( + options: ServeVsockOptions & ServeInit, + ): HttpServer; /** Serves HTTP requests with the given option bag. * * You can specify an object with a port and hostname option, which is the @@ -5429,7 +5666,7 @@ declare namespace Deno { /** * @category FFI */ - export const brand: unique symbol; + const brand: unique symbol; /** * @category FFI @@ -5557,7 +5794,7 @@ declare namespace Deno { * @category FFI */ export type FromNativeType = T extends - NativeStructType ? Uint8Array + NativeStructType ? Uint8Array : T extends NativeNumberType ? T extends NativeU8Enum ? U : T extends NativeI8Enum ? U : T extends NativeU16Enum ? U @@ -5582,7 +5819,7 @@ declare namespace Deno { */ export type FromNativeResultType< T extends NativeResultType = NativeResultType, - > = T extends NativeStructType ? Uint8Array + > = T extends NativeStructType ? Uint8Array : T extends NativeNumberType ? T extends NativeU8Enum ? U : T extends NativeI8Enum ? U : T extends NativeU16Enum ? U @@ -5796,11 +6033,17 @@ declare namespace Deno { getFloat64(offset?: number): number; /** Gets a pointer at the specified byte offset from the pointer */ getPointer(offset?: number): PointerValue; - /** Gets a C string (`null` terminated string) at the specified byte offset - * from the pointer. */ + /** Gets a UTF-8 encoded string at the specified byte offset until 0 byte. + * + * Returned string doesn't include U+0000 character. + * + * Invalid UTF-8 characters are replaced with U+FFFD character in the returned string. */ getCString(offset?: number): string; - /** Gets a C string (`null` terminated string) at the specified byte offset - * from the specified pointer. */ + /** Gets a UTF-8 encoded string at the specified byte offset from the specified pointer until 0 byte. + * + * Returned string doesn't include U+0000 character. + * + * Invalid UTF-8 characters are replaced with U+FFFD character in the returned string. */ static getCString(pointer: PointerObject, offset?: number): string; /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte * offset from the pointer. */ @@ -6071,7 +6314,7 @@ declare namespace Deno { * * Must be in PEM format. */ caCerts?: string[]; - /** A HTTP proxy to use for new connections. */ + /** An alternative transport (a proxy) to use for new connections. */ proxy?: Proxy; /** Sets the maximum number of idle connections per host allowed in the pool. */ poolMaxIdlePerHost?: number; @@ -6094,20 +6337,58 @@ declare namespace Deno { * @default {false} */ allowHost?: boolean; + /** Sets the local address where the socket will connect from. */ + localAddress?: string; } /** - * The definition of a proxy when specifying + * The definition for alternative transports (or proxies) in * {@linkcode Deno.CreateHttpClientOptions}. * + * Supported proxies: + * - HTTP/HTTPS proxy: this uses passthrough to tunnel HTTP requests, or HTTP + * CONNECT to tunnel HTTPS requests through a different server. + * - SOCKS5 proxy: this uses the SOCKS5 protocol to tunnel TCP connections + * through a different server. + * - TCP socket: this sends all requests to a specified TCP socket. + * - Unix domain socket: this sends all requests to a local Unix domain + * socket rather than a TCP socket. *Not supported on Windows.* + * - Vsock socket: this sends all requests to a local vsock socket. + * *Only supported on Linux and macOS.* + * * @category Fetch */ - export interface Proxy { - /** The string URL of the proxy server to use. */ + export type Proxy = { + transport?: "http" | "https" | "socks5"; + /** + * The string URL of the proxy server to use. + * + * For `http` and `https` transports, the URL must start with `http://` or + * `https://` respectively, or be a plain hostname. + * + * For `socks` transport, the URL must start with `socks5://` or + * `socks5h://`. + */ url: string; /** The basic auth credentials to be used against the proxy server. */ basicAuth?: BasicAuth; - } + } | { + transport: "tcp"; + /** The hostname of the TCP server to connect to. */ + hostname: string; + /** The port of the TCP server to connect to. */ + port: number; + } | { + transport: "unix"; + /** The path to the unix domain socket to use. */ + path: string; + } | { + transport: "vsock"; + /** The CID (Context Identifier) of the vsock to connect to. */ + cid: number; + /** The port of the vsock to connect to. */ + port: number; + }; /** * Basic authentication credentials to be used with a {@linkcode Deno.Proxy} @@ -6159,7860 +6440,13702 @@ declare namespace Deno { | (CreateHttpClientOptions & TlsCertifiedKeyPem), ): HttpClient; - export {}; // only export exports -} - -// Copyright 2018-2025 the Deno authors. MIT license. - -// deno-lint-ignore-file no-explicit-any - -/// -/// - -/** @category I/O */ -interface Console { - assert(condition?: boolean, ...data: any[]): void; - clear(): void; - count(label?: string): void; - countReset(label?: string): void; - debug(...data: any[]): void; - dir(item?: any, options?: any): void; - dirxml(...data: any[]): void; - error(...data: any[]): void; - group(...data: any[]): void; - groupCollapsed(...data: any[]): void; - groupEnd(): void; - info(...data: any[]): void; - log(...data: any[]): void; - table(tabularData?: any, properties?: string[]): void; - time(label?: string): void; - timeEnd(label?: string): void; - timeLog(label?: string, ...data: any[]): void; - trace(...data: any[]): void; - warn(...data: any[]): void; - - /** This method is a noop, unless used in inspector */ - timeStamp(label?: string): void; - - /** This method is a noop, unless used in inspector */ - profile(label?: string): void; - - /** This method is a noop, unless used in inspector */ - profileEnd(label?: string): void; -} - -// Copyright 2018-2025 the Deno authors. MIT license. - -// deno-lint-ignore-file no-explicit-any no-var - -/// -/// - -/** @category URL */ -interface URLSearchParams { - /** Appends a specified key/value pair as a new search parameter. - * - * ```ts - * let searchParams = new URLSearchParams(); - * searchParams.append('name', 'first'); - * searchParams.append('name', 'second'); - * ``` - */ - append(name: string, value: string): void; - - /** Deletes search parameters that match a name, and optional value, - * from the list of all search parameters. + /** + * APIs for working with the OpenTelemetry observability framework. Deno can + * export traces, metrics, and logs to OpenTelemetry compatible backends via + * the OTLP protocol. * + * Deno automatically instruments the runtime with OpenTelemetry traces and + * metrics. This data is exported via OTLP to OpenTelemetry compatible + * backends. User logs from the `console` API are exported as OpenTelemetry + * logs via OTLP. + * + * User code can also create custom traces, metrics, and logs using the + * OpenTelemetry API. This is done using the official OpenTelemetry package + * for JavaScript: + * [`npm:@opentelemetry/api`](https://opentelemetry.io/docs/languages/js/). + * Deno integrates with this package to provide tracing, metrics, and trace + * context propagation between native Deno APIs (like `Deno.serve` or `fetch`) + * and custom user code. Deno automatically registers the providers with the + * OpenTelemetry API, so users can start creating custom traces, metrics, and + * logs without any additional setup. + * + * @example Using OpenTelemetry API to create custom traces + * ```ts,ignore + * import { trace } from "npm:@opentelemetry/api@1"; + * + * const tracer = trace.getTracer("example-tracer"); + * + * async function doWork() { + * return tracer.startActiveSpan("doWork", async (span) => { + * span.setAttribute("key", "value"); + * await new Promise((resolve) => setTimeout(resolve, 1000)); + * span.end(); + * }); + * } + * + * Deno.serve(async (req) => { + * await doWork(); + * const resp = await fetch("https://example.com"); + * return resp; + * }); + * ``` + * + * @category Telemetry + */ + export namespace telemetry { + /** + * A TracerProvider compatible with OpenTelemetry.js + * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.TracerProvider.html + * + * This is a singleton object that implements the OpenTelemetry + * TracerProvider interface. + * + * @category Telemetry + */ + // deno-lint-ignore no-explicit-any + export const tracerProvider: any; + + /** + * A ContextManager compatible with OpenTelemetry.js + * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.ContextManager.html + * + * This is a singleton object that implements the OpenTelemetry + * ContextManager interface. + * + * @category Telemetry + */ + // deno-lint-ignore no-explicit-any + export const contextManager: any; + + /** + * A MeterProvider compatible with OpenTelemetry.js + * https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.MeterProvider.html + * + * This is a singleton object that implements the OpenTelemetry + * MeterProvider interface. + * + * @category Telemetry + */ + // deno-lint-ignore no-explicit-any + export const meterProvider: any; + + export {}; // only export exports + } + + export {}; // only export exports +} + +// Copyright 2018-2026 the Deno authors. MIT license. + +// deno-lint-ignore-file no-explicit-any + +/// +/// + +/** + * The Console interface provides methods for logging information to the console, + * as well as other utility methods for debugging and inspecting code. + * Methods include logging, debugging, and timing functionality. + * @see https://developer.mozilla.org/en-US/docs/Web/API/console + * + * @category I/O + */ + +interface Console { + /** + * Tests that an expression is true. If not, logs an error message + * @param condition The expression to test for truthiness + * @param data Additional arguments to be printed if the assertion fails + * @example * ```ts - * let searchParams = new URLSearchParams([['name', 'value']]); - * searchParams.delete('name'); - * searchParams.delete('name', 'value'); + * console.assert(1 === 1, "This won't show"); + * console.assert(1 === 2, "This will show an error"); * ``` */ - delete(name: string, value?: string): void; + assert(condition?: boolean, ...data: any[]): void; - /** Returns all the values associated with a given search parameter - * as an array. - * + /** + * Clears the console if the environment allows it + * @example * ```ts - * searchParams.getAll('name'); + * console.clear(); * ``` */ - getAll(name: string): string[]; + clear(): void; - /** Returns the first value associated to the given search parameter. - * + /** + * Maintains an internal counter for a given label, incrementing it each time the method is called + * @param label The label to count. Defaults to 'default' + * @example * ```ts - * searchParams.get('name'); + * console.count('myCounter'); + * console.count('myCounter'); // Will show: myCounter: 2 * ``` */ - get(name: string): string | null; + count(label?: string): void; - /** Returns a boolean value indicating if a given parameter, - * or parameter and value pair, exists. - * + /** + * Resets the counter for a given label + * @param label The label to reset. Defaults to 'default' + * @example * ```ts - * searchParams.has('name'); - * searchParams.has('name', 'value'); + * console.count('myCounter'); + * console.countReset('myCounter'); // Resets to 0 * ``` */ - has(name: string, value?: string): boolean; + countReset(label?: string): void; - /** Sets the value associated with a given search parameter to the - * given value. If there were several matching values, this method - * deletes the others. If the search parameter doesn't exist, this - * method creates it. - * + /** + * Outputs a debugging message to the console + * @param data Values to be printed to the console + * @example * ```ts - * searchParams.set('name', 'value'); + * console.debug('Debug message', { detail: 'some data' }); * ``` */ - set(name: string, value: string): void; + debug(...data: any[]): void; - /** Sort all key/value pairs contained in this object in place and - * return undefined. The sort order is according to Unicode code - * points of the keys. - * + /** + * Displays a list of the properties of a specified object + * @param item Object to display + * @param options Formatting options + * @example * ```ts - * searchParams.sort(); + * console.dir({ name: 'object', value: 42 }, { depth: 1 }); * ``` */ - sort(): void; + dir(item?: any, options?: any): void; - /** Calls a function for each element contained in this object in - * place and return undefined. Optionally accepts an object to use - * as this when executing callback as second argument. - * + /** + * @ignore + */ + dirxml(...data: any[]): void; + + /** + * Outputs an error message to the console. + * This method routes the output to stderr, + * unlike other console methods that route to stdout. + * @param data Values to be printed to the console + * @example * ```ts - * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); - * params.forEach((value, key, parent) => { - * console.log(value, key, parent); - * }); + * console.error('Error occurred:', new Error('Something went wrong')); * ``` */ - forEach( - callbackfn: (value: string, key: string, parent: this) => void, - thisArg?: any, - ): void; + error(...data: any[]): void; - /** Returns an iterator allowing to go through all keys contained - * in this object. - * + /** + * Creates a new inline group in the console, indenting subsequent console messages + * @param data Labels for the group + * @example * ```ts - * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); - * for (const key of params.keys()) { - * console.log(key); - * } + * console.group('Group 1'); + * console.log('Inside group 1'); + * console.groupEnd(); * ``` */ - keys(): IterableIterator; + group(...data: any[]): void; - /** Returns an iterator allowing to go through all values contained - * in this object. - * + /** + * Creates a new inline group in the console that is initially collapsed + * @param data Labels for the group + * @example * ```ts - * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); - * for (const value of params.values()) { - * console.log(value); - * } + * console.groupCollapsed('Details'); + * console.log('Hidden until expanded'); + * console.groupEnd(); * ``` */ - values(): IterableIterator; + groupCollapsed(...data: any[]): void; - /** Returns an iterator allowing to go through all key/value - * pairs contained in this object. - * + /** + * Exits the current inline group in the console + * @example * ```ts - * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); - * for (const [key, value] of params.entries()) { - * console.log(key, value); - * } + * console.group('Group'); + * console.log('Grouped message'); + * console.groupEnd(); * ``` */ - entries(): IterableIterator<[string, string]>; + groupEnd(): void; - /** Returns an iterator allowing to go through all key/value - * pairs contained in this object. - * + /** + * Outputs an informational message to the console + * @param data Values to be printed to the console + * @example * ```ts - * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); - * for (const [key, value] of params) { - * console.log(key, value); - * } + * console.info('Application started', { version: '1.0.0' }); * ``` */ - [Symbol.iterator](): IterableIterator<[string, string]>; + info(...data: any[]): void; - /** Returns a query string suitable for use in a URL. - * + /** + * Outputs a message to the console + * @param data Values to be printed to the console + * @example * ```ts - * searchParams.toString(); + * console.log('Hello', 'World', 123); * ``` */ - toString(): string; + log(...data: any[]): void; - /** Contains the number of search parameters - * + /** + * Displays tabular data as a table + * @param tabularData Data to be displayed in table format + * @param properties Array of property names to be displayed + * @example * ```ts - * searchParams.size + * console.table([ + * { name: 'John', age: 30 }, + * { name: 'Jane', age: 25 } + * ]); * ``` */ - size: number; -} + table(tabularData?: any, properties?: string[]): void; -/** @category URL */ -declare var URLSearchParams: { - readonly prototype: URLSearchParams; - new ( - init?: Iterable | Record | string, - ): URLSearchParams; -}; + /** + * Starts a timer you can use to track how long an operation takes + * @param label Timer label. Defaults to 'default' + * @example + * ```ts + * console.time('operation'); + * // ... some code + * console.timeEnd('operation'); + * ``` + */ + time(label?: string): void; -/** The URL interface represents an object providing static methods used for - * creating object URLs. - * - * @category URL - */ -interface URL { - hash: string; - host: string; - hostname: string; - href: string; - toString(): string; - readonly origin: string; - password: string; - pathname: string; - port: string; - protocol: string; - search: string; - readonly searchParams: URLSearchParams; - username: string; - toJSON(): string; -} + /** + * Stops a timer that was previously started + * @param label Timer label to stop. Defaults to 'default' + * @example + * ```ts + * console.time('operation'); + * // ... some code + * console.timeEnd('operation'); // Prints: operation: 1234ms + * ``` + */ + timeEnd(label?: string): void; -/** The URL interface represents an object providing static methods used for - * creating object URLs. - * - * @category URL - */ -declare var URL: { - readonly prototype: URL; - new (url: string | URL, base?: string | URL): URL; - parse(url: string | URL, base?: string | URL): URL | null; - canParse(url: string | URL, base?: string | URL): boolean; - createObjectURL(blob: Blob): string; - revokeObjectURL(url: string): void; -}; + /** + * Logs the current value of a timer that was previously started + * @param label Timer label + * @param data Additional data to log + * @example + * ```ts + * console.time('process'); + * // ... some code + * console.timeLog('process', 'Checkpoint A'); + * ``` + */ + timeLog(label?: string, ...data: any[]): void; -/** @category URL */ -interface URLPatternInit { - protocol?: string; - username?: string; - password?: string; - hostname?: string; - port?: string; - pathname?: string; - search?: string; - hash?: string; - baseURL?: string; -} - -/** @category URL */ -type URLPatternInput = string | URLPatternInit; + /** + * Outputs a stack trace to the console + * @param data Values to be printed to the console + * @example + * ```ts + * console.trace('Trace message'); + * ``` + */ + trace(...data: any[]): void; -/** @category URL */ -interface URLPatternComponentResult { - input: string; - groups: Record; -} + /** + * Outputs a warning message to the console + * @param data Values to be printed to the console + * @example + * ```ts + * console.warn('Deprecated feature used'); + * ``` + */ + warn(...data: any[]): void; -/** `URLPatternResult` is the object returned from `URLPattern.exec`. - * - * @category URL - */ -interface URLPatternResult { - /** The inputs provided when matching. */ - inputs: [URLPatternInit] | [URLPatternInit, string]; + /** + * Adds a marker to the DevTools Performance panel + * @param label Label for the timestamp + * @example + * ```ts + * console.timeStamp('Navigation Start'); + * ``` + */ + timeStamp(label?: string): void; - /** The matched result for the `protocol` matcher. */ - protocol: URLPatternComponentResult; - /** The matched result for the `username` matcher. */ - username: URLPatternComponentResult; - /** The matched result for the `password` matcher. */ - password: URLPatternComponentResult; - /** The matched result for the `hostname` matcher. */ - hostname: URLPatternComponentResult; - /** The matched result for the `port` matcher. */ - port: URLPatternComponentResult; - /** The matched result for the `pathname` matcher. */ - pathname: URLPatternComponentResult; - /** The matched result for the `search` matcher. */ - search: URLPatternComponentResult; - /** The matched result for the `hash` matcher. */ - hash: URLPatternComponentResult; -} + /** + * Starts recording a performance profile + * @param label Profile label + * @example + * ```ts + * console.profile('Performance Profile'); + * // ... code to profile + * console.profileEnd('Performance Profile'); + * ``` + */ + profile(label?: string): void; -/** - * Options for the {@linkcode URLPattern} constructor. - * - * @category URL - */ -interface URLPatternOptions { /** - * Enables case-insensitive matching. - * - * @default {false} + * Stops recording a performance profile + * @param label Profile label to stop + * @example + * ```ts + * console.profile('Performance Profile'); + * // ... code to profile + * console.profileEnd('Performance Profile'); + * ``` */ - ignoreCase: boolean; + profileEnd(label?: string): void; } +// Copyright 2018-2026 the Deno authors. MIT license. + +// deno-lint-ignore-file no-explicit-any no-var + +/// +/// + /** - * The URLPattern API provides a web platform primitive for matching URLs based - * on a convenient pattern syntax. - * - * The syntax is based on path-to-regexp. Wildcards, named capture groups, - * regular groups, and group modifiers are all supported. + * Iterator for the URLSearchParams class, used to iterate over key-value pairs in search parameters. * + * @example * ```ts - * // Specify the pattern as structured data. - * const pattern = new URLPattern({ pathname: "/users/:user" }); - * const match = pattern.exec("https://blog.example.com/users/joe"); - * console.log(match.pathname.groups.user); // joe + * const url = new URL('https://example.org/path?a=1&b=2'); + * const queryString = url.search.substring(1); // Remove the leading '?' + * const params = new URLSearchParams(queryString); + * const iterator = params.entries(); + * console.log(iterator.next().value); // ['a', '1'] + * console.log(iterator.next().value); // ['b', '2'] * ``` * - * ```ts - * // Specify a fully qualified string pattern. - * const pattern = new URLPattern("https://example.com/books/:id"); - * console.log(pattern.test("https://example.com/books/123")); // true - * console.log(pattern.test("https://deno.land/books/123")); // false - * ``` + * @category URL + */ +interface URLSearchParamsIterator + extends IteratorObject { + [Symbol.iterator](): URLSearchParamsIterator; +} + +/** + * URLSearchParams provides methods for working with the query string of a URL. * - * ```ts - * // Specify a relative string pattern with a base URL. - * const pattern = new URLPattern("/article/:id", "https://blog.example.com"); - * console.log(pattern.test("https://blog.example.com/article")); // false - * console.log(pattern.test("https://blog.example.com/article/123")); // true - * ``` + * Use this interface to: + * - Parse query parameters from URLs + * - Build and modify query strings + * - Handle form data (when used with FormData) + * - Safely encode/decode URL parameter values * * @category URL */ -interface URLPattern { - /** - * Test if the given input matches the stored pattern. +interface URLSearchParams { + /** Appends a specified key/value pair as a new search parameter. * - * The input can either be provided as an absolute URL string with an optional base, - * relative URL string with a required base, or as individual components - * in the form of an `URLPatternInit` object. + * ```ts + * let searchParams = new URLSearchParams(); + * searchParams.append('name', 'first'); + * searchParams.append('name', 'second'); + * ``` + */ + append(name: string, value: string): void; + + /** Deletes search parameters that match a name, and optional value, + * from the list of all search parameters. * * ```ts - * const pattern = new URLPattern("https://example.com/books/:id"); + * let searchParams = new URLSearchParams([['name', 'value']]); + * searchParams.delete('name'); + * searchParams.delete('name', 'value'); + * ``` + */ + delete(name: string, value?: string): void; + + /** Returns all the values associated with a given search parameter + * as an array. * - * // Test an absolute url string. - * console.log(pattern.test("https://example.com/books/123")); // true + * ```ts + * searchParams.getAll('name'); + * ``` + */ + getAll(name: string): string[]; + + /** Returns the first value associated to the given search parameter. * - * // Test a relative url with a base. - * console.log(pattern.test("/books/123", "https://example.com")); // true + * ```ts + * searchParams.get('name'); + * ``` + */ + get(name: string): string | null; + + /** Returns a boolean value indicating if a given parameter, + * or parameter and value pair, exists. * - * // Test an object of url components. - * console.log(pattern.test({ pathname: "/books/123" })); // true + * ```ts + * searchParams.has('name'); + * searchParams.has('name', 'value'); * ``` */ - test(input: URLPatternInput, baseURL?: string): boolean; + has(name: string, value?: string): boolean; - /** - * Match the given input against the stored pattern. + /** Sets the value associated with a given search parameter to the + * given value. If there were several matching values, this method + * deletes the others. If the search parameter doesn't exist, this + * method creates it. * - * The input can either be provided as an absolute URL string with an optional base, - * relative URL string with a required base, or as individual components - * in the form of an `URLPatternInit` object. + * ```ts + * searchParams.set('name', 'value'); + * ``` + */ + set(name: string, value: string): void; + + /** Sort all key/value pairs contained in this object in place and + * return undefined. The sort order is according to Unicode code + * points of the keys. * * ```ts - * const pattern = new URLPattern("https://example.com/books/:id"); + * searchParams.sort(); + * ``` + */ + sort(): void; + + /** Calls a function for each element contained in this object in + * place and return undefined. Optionally accepts an object to use + * as this when executing callback as second argument. * - * // Match an absolute url string. - * let match = pattern.exec("https://example.com/books/123"); - * console.log(match.pathname.groups.id); // 123 + * ```ts + * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); + * params.forEach((value, key, parent) => { + * console.log(value, key, parent); + * }); + * ``` + */ + forEach( + callbackfn: (value: string, key: string, parent: this) => void, + thisArg?: any, + ): void; + + /** Returns an iterator allowing to go through all keys contained + * in this object. * - * // Match a relative url with a base. - * match = pattern.exec("/books/123", "https://example.com"); - * console.log(match.pathname.groups.id); // 123 + * ```ts + * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); + * for (const key of params.keys()) { + * console.log(key); + * } + * ``` + */ + keys(): URLSearchParamsIterator; + + /** Returns an iterator allowing to go through all values contained + * in this object. * - * // Match an object of url components. - * match = pattern.exec({ pathname: "/books/123" }); - * console.log(match.pathname.groups.id); // 123 + * ```ts + * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); + * for (const value of params.values()) { + * console.log(value); + * } * ``` */ - exec(input: URLPatternInput, baseURL?: string): URLPatternResult | null; + values(): URLSearchParamsIterator; - /** The pattern string for the `protocol`. */ - readonly protocol: string; - /** The pattern string for the `username`. */ - readonly username: string; - /** The pattern string for the `password`. */ - readonly password: string; - /** The pattern string for the `hostname`. */ - readonly hostname: string; - /** The pattern string for the `port`. */ - readonly port: string; - /** The pattern string for the `pathname`. */ - readonly pathname: string; - /** The pattern string for the `search`. */ - readonly search: string; - /** The pattern string for the `hash`. */ - readonly hash: string; + /** Returns an iterator allowing to go through all key/value + * pairs contained in this object. + * + * ```ts + * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); + * for (const [key, value] of params.entries()) { + * console.log(key, value); + * } + * ``` + */ + entries(): URLSearchParamsIterator<[string, string]>; - /** Whether or not any of the specified groups use regexp groups. */ - readonly hasRegExpGroups: boolean; + /** Returns an iterator allowing to go through all key/value + * pairs contained in this object. + * + * ```ts + * const params = new URLSearchParams([["a", "b"], ["c", "d"]]); + * for (const [key, value] of params) { + * console.log(key, value); + * } + * ``` + */ + [Symbol.iterator](): URLSearchParamsIterator<[string, string]>; + + /** Returns a query string suitable for use in a URL. + * + * ```ts + * searchParams.toString(); + * ``` + */ + toString(): string; + + /** Contains the number of search parameters + * + * ```ts + * searchParams.size + * ``` + */ + readonly size: number; } -/** - * The URLPattern API provides a web platform primitive for matching URLs based - * on a convenient pattern syntax. - * - * The syntax is based on path-to-regexp. Wildcards, named capture groups, - * regular groups, and group modifiers are all supported. - * - * ```ts - * // Specify the pattern as structured data. - * const pattern = new URLPattern({ pathname: "/users/:user" }); - * const match = pattern.exec("https://blog.example.com/users/joe"); - * console.log(match.pathname.groups.user); // joe - * ``` +/** @category URL */ +declare var URLSearchParams: { + readonly prototype: URLSearchParams; + /** + * Creates a new URLSearchParams object for parsing query strings. + * + * URLSearchParams is Deno's built-in query string parser, providing a standard + * way to parse, manipulate, and stringify URL query parameters. Instead of manually + * parsing query strings with regex or string operations, use this API for robust + * handling of URL query parameters. + * + * @example + * ```ts + * // From a URL object's query string (recommended approach for parsing query strings in URLs) + * const url = new URL('https://example.org/path?foo=bar&baz=qux'); + * const params = url.searchParams; // No need to manually extract the query string + * console.log(params.get('foo')); // Logs "bar" + * + * // Manually parsing a query string from a URL + * const urlString = 'https://example.org/path?foo=bar&baz=qux'; + * const queryString = urlString.split('?')[1]; // Extract query string part + * const params2 = new URLSearchParams(queryString); + * console.log(params2.get('foo')); // Logs "bar" + * + * // Empty search parameters + * const params3 = new URLSearchParams(); + * console.log(params3.toString()); // Logs "" + * + * // From a string + * const params4 = new URLSearchParams("foo=bar&baz=qux"); + * console.log(params4.get("foo")); // Logs "bar" + * + * // From an array of pairs + * const params5 = new URLSearchParams([["foo", "1"], ["bar", "2"]]); + * console.log(params5.toString()); // Logs "foo=1&bar=2" + * + * // From a record object + * const params6 = new URLSearchParams({"foo": "1", "bar": "2"}); + * console.log(params6.toString()); // Logs "foo=1&bar=2" + * ``` + */ + new ( + init?: + | Iterable + | Record + | string + | URLSearchParams, + ): URLSearchParams; +}; + +/** The URL interface represents an object providing static methods used for + * creating, parsing, and manipulating URLs in Deno. * - * ```ts - * // Specify a fully qualified string pattern. - * const pattern = new URLPattern("https://example.com/books/:id"); - * console.log(pattern.test("https://example.com/books/123")); // true - * console.log(pattern.test("https://deno.land/books/123")); // false - * ``` + * Use the URL API for safely parsing, constructing, normalizing, and encoding URLs. + * This is the preferred way to work with URLs in Deno rather than manual string + * manipulation which can lead to errors and security issues. * - * ```ts - * // Specify a relative string pattern with a base URL. - * const pattern = new URLPattern("/article/:id", "https://blog.example.com"); - * console.log(pattern.test("https://blog.example.com/article")); // false - * console.log(pattern.test("https://blog.example.com/article/123")); // true - * ``` + * @see https://developer.mozilla.org/docs/Web/API/URL * * @category URL */ -declare var URLPattern: { - readonly prototype: URLPattern; - new ( - input: URLPatternInput, - baseURL: string, - options?: URLPatternOptions, - ): URLPattern; - new (input?: URLPatternInput, options?: URLPatternOptions): URLPattern; -}; +interface URL { + /** + * The hash property of the URL interface is a string that starts with a `#` and is followed by the fragment identifier of the URL. + * It returns an empty string if the URL does not contain a fragment identifier. + * + * @example + * ```ts + * const myURL = new URL('https://example.org/foo#bar'); + * console.log(myURL.hash); // Logs "#bar" + * + * const myOtherURL = new URL('https://example.org'); + * console.log(myOtherURL.hash); // Logs "" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/hash + */ + hash: string; -// Copyright 2018-2025 the Deno authors. MIT license. + /** + * The `host` property of the URL interface is a string that includes the {@linkcode URL.hostname} and the {@linkcode URL.port} if one is specified in the URL includes by including a `:` followed by the port number. + * + * @example + * ```ts + * const myURL = new URL('https://example.org/foo'); + * console.log(myURL.host); // Logs "example.org" + * + * const myOtherURL = new URL('https://example.org:8080/foo'); + * console.log(myOtherURL.host); // Logs "example.org:8080" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/host + */ + host: string; -// deno-lint-ignore-file no-explicit-any no-var + /** + * The `hostname` property of the URL interface is a string that represents the fully qualified domain name of the URL. + * + * @example + * ```ts + * const myURL = new URL('https://foo.example.org/bar'); + * console.log(myURL.hostname); // Logs "foo.example.org" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/hostname + */ + hostname: string; -/// -/// + /** + * The `href` property of the URL interface is a string that represents the complete URL. + * + * @example + * ```ts + * const myURL = new URL('https://foo.example.org/bar?baz=qux#quux'); + * console.log(myURL.href); // Logs "https://foo.example.org/bar?baz=qux#quux" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/href + */ + href: string; -/** @category Platform */ -interface DOMException extends Error { - readonly name: string; - readonly message: string; - /** @deprecated */ - readonly code: number; - readonly INDEX_SIZE_ERR: 1; - readonly DOMSTRING_SIZE_ERR: 2; - readonly HIERARCHY_REQUEST_ERR: 3; - readonly WRONG_DOCUMENT_ERR: 4; - readonly INVALID_CHARACTER_ERR: 5; - readonly NO_DATA_ALLOWED_ERR: 6; - readonly NO_MODIFICATION_ALLOWED_ERR: 7; - readonly NOT_FOUND_ERR: 8; - readonly NOT_SUPPORTED_ERR: 9; - readonly INUSE_ATTRIBUTE_ERR: 10; - readonly INVALID_STATE_ERR: 11; - readonly SYNTAX_ERR: 12; - readonly INVALID_MODIFICATION_ERR: 13; - readonly NAMESPACE_ERR: 14; - readonly INVALID_ACCESS_ERR: 15; - readonly VALIDATION_ERR: 16; - readonly TYPE_MISMATCH_ERR: 17; - readonly SECURITY_ERR: 18; - readonly NETWORK_ERR: 19; - readonly ABORT_ERR: 20; - readonly URL_MISMATCH_ERR: 21; - readonly QUOTA_EXCEEDED_ERR: 22; - readonly TIMEOUT_ERR: 23; - readonly INVALID_NODE_TYPE_ERR: 24; - readonly DATA_CLONE_ERR: 25; -} + /** + * The `toString()` method of the URL interface returns a string containing the complete URL. + * + * @example + * ```ts + * const myURL = new URL('https://foo.example.org/bar'); + * console.log(myURL.toString()); // Logs "https://foo.example.org/bar" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/toString + */ + toString(): string; -/** @category Platform */ -declare var DOMException: { - readonly prototype: DOMException; - new (message?: string, name?: string): DOMException; - readonly INDEX_SIZE_ERR: 1; - readonly DOMSTRING_SIZE_ERR: 2; - readonly HIERARCHY_REQUEST_ERR: 3; - readonly WRONG_DOCUMENT_ERR: 4; - readonly INVALID_CHARACTER_ERR: 5; - readonly NO_DATA_ALLOWED_ERR: 6; - readonly NO_MODIFICATION_ALLOWED_ERR: 7; - readonly NOT_FOUND_ERR: 8; - readonly NOT_SUPPORTED_ERR: 9; - readonly INUSE_ATTRIBUTE_ERR: 10; - readonly INVALID_STATE_ERR: 11; - readonly SYNTAX_ERR: 12; - readonly INVALID_MODIFICATION_ERR: 13; - readonly NAMESPACE_ERR: 14; - readonly INVALID_ACCESS_ERR: 15; - readonly VALIDATION_ERR: 16; - readonly TYPE_MISMATCH_ERR: 17; - readonly SECURITY_ERR: 18; - readonly NETWORK_ERR: 19; - readonly ABORT_ERR: 20; - readonly URL_MISMATCH_ERR: 21; - readonly QUOTA_EXCEEDED_ERR: 22; - readonly TIMEOUT_ERR: 23; - readonly INVALID_NODE_TYPE_ERR: 24; - readonly DATA_CLONE_ERR: 25; -}; + /** + * The `origin` property of the URL interface is a string that represents the origin of the URL, that is the {@linkcode URL.protocol}, {@linkcode URL.host}, and {@linkcode URL.port}. + * + * @example + * ```ts + * const myURL = new URL('https://foo.example.org/bar'); + * console.log(myURL.origin); // Logs "https://foo.example.org" + * + * const myOtherURL = new URL('https://example.org:8080/foo'); + * console.log(myOtherURL.origin); // Logs "https://example.org:8080" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/origin + */ + readonly origin: string; -/** @category Events */ -interface EventInit { - bubbles?: boolean; - cancelable?: boolean; - composed?: boolean; -} + /** + * The `password` property of the URL interface is a string that represents the password specified in the URL. + * + * @example + * ```ts + * const myURL = new URL('https://someone:somepassword@example.org/baz'); + * console.log(myURL.password); // Logs "somepassword" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/password + */ + password: string; -/** An event which takes place in the DOM. - * - * @category Events - */ -interface Event { - /** Returns true or false depending on how event was initialized. True if - * event goes through its target's ancestors in reverse tree order, and - * false otherwise. */ - readonly bubbles: boolean; - /** @deprecated */ - cancelBubble: boolean; - /** Returns true or false depending on how event was initialized. Its return - * value does not always carry meaning, but true can indicate that part of the - * operation during which event was dispatched, can be canceled by invoking - * the preventDefault() method. */ - readonly cancelable: boolean; - /** Returns true or false depending on how event was initialized. True if - * event invokes listeners past a ShadowRoot node that is the root of its - * target, and false otherwise. */ - readonly composed: boolean; - /** Returns the object whose event listener's callback is currently being - * invoked. */ - readonly currentTarget: EventTarget | null; - /** Returns true if preventDefault() was invoked successfully to indicate - * cancellation, and false otherwise. */ - readonly defaultPrevented: boolean; - /** Returns the event's phase, which is one of NONE, CAPTURING_PHASE, - * AT_TARGET, and BUBBLING_PHASE. */ - readonly eventPhase: number; - /** Returns true if event was dispatched by the user agent, and false - * otherwise. */ - readonly isTrusted: boolean; - /** @deprecated */ - returnValue: boolean; - /** @deprecated */ - readonly srcElement: EventTarget | null; - /** Returns the object to which event is dispatched (its target). */ - readonly target: EventTarget | null; - /** Returns the event's timestamp as the number of milliseconds measured - * relative to the time origin. */ - readonly timeStamp: number; - /** Returns the type of event, e.g. "click", "hashchange", or "submit". */ - readonly type: string; - /** Returns the invocation target objects of event's path (objects on which - * listeners will be invoked), except for any nodes in shadow trees of which - * the shadow root's mode is "closed" that are not reachable from event's - * currentTarget. */ - composedPath(): EventTarget[]; - /** @deprecated */ - initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void; - /** If invoked when the cancelable attribute value is true, and while - * executing a listener for the event with passive set to false, signals to - * the operation that caused event to be dispatched that it needs to be - * canceled. */ - preventDefault(): void; - /** Invoking this method prevents event from reaching any registered event - * listeners after the current one finishes running and, when dispatched in a - * tree, also prevents event from reaching any other objects. */ - stopImmediatePropagation(): void; - /** When dispatched in a tree, invoking this method prevents event from - * reaching any objects other than the current object. */ - stopPropagation(): void; - readonly NONE: 0; - readonly CAPTURING_PHASE: 1; - readonly AT_TARGET: 2; - readonly BUBBLING_PHASE: 3; -} + /** + * The `pathname` property of the URL interface is a string that represents the path of the URL. + * + * @example + * ```ts + * const myURL = new URL('https://example.org/foo/bar'); + * console.log(myURL.pathname); // Logs "/foo/bar" + * + * const myOtherURL = new URL('https://example.org'); + * console.log(myOtherURL.pathname); // Logs "/" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/pathname + */ + pathname: string; -/** An event which takes place in the DOM. - * - * @category Events - */ -declare var Event: { - readonly prototype: Event; - new (type: string, eventInitDict?: EventInit): Event; - readonly NONE: 0; - readonly CAPTURING_PHASE: 1; - readonly AT_TARGET: 2; - readonly BUBBLING_PHASE: 3; -}; + /** + * The `port` property of the URL interface is a string that represents the port of the URL if an explicit port has been specified in the URL. + * + * @example + * ```ts + * const myURL = new URL('https://example.org:8080/foo'); + * console.log(myURL.port); // Logs "8080" + * + * const myOtherURL = new URL('https://example.org/foo'); + * console.log(myOtherURL.port); // Logs "" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/port + */ + port: string; -/** - * EventTarget is a DOM interface implemented by objects that can receive events - * and may have listeners for them. - * - * @category Events - */ -interface EventTarget { - /** Appends an event listener for events whose type attribute value is type. - * The callback argument sets the callback that will be invoked when the event - * is dispatched. + /** + * The `protocol` property of the URL interface is a string that represents the protocol scheme of the URL and includes a trailing `:`. * - * The options argument sets listener-specific options. For compatibility this - * can be a boolean, in which case the method behaves exactly as if the value - * was specified as options's capture. + * @example + * ```ts + * const myURL = new URL('https://example.org/foo'); + * console.log(myURL.protocol); // Logs "https:" + * ``` * - * When set to true, options's capture prevents callback from being invoked - * when the event's eventPhase attribute value is BUBBLING_PHASE. When false - * (or not present), callback will not be invoked when event's eventPhase - * attribute value is CAPTURING_PHASE. Either way, callback will be invoked if - * event's eventPhase attribute value is AT_TARGET. + * @see https://developer.mozilla.org/docs/Web/API/URL/protocol + */ + protocol: string; + + /** + * The `search` property of the URL interface is a string that represents the search string, or the query string, of the URL. + * This includes the `?` character and the but excludes identifiers within the represented resource such as the {@linkcode URL.hash}. More granular control can be found using {@linkcode URL.searchParams} property. * - * When set to true, options's passive indicates that the callback will not - * cancel the event by invoking preventDefault(). This is used to enable - * performance optimizations described in § 2.8 Observing event listeners. + * @example + * ```ts + * const myURL = new URL('https://example.org/foo?bar=baz'); + * console.log(myURL.search); // Logs "?bar=baz" * - * When set to true, options's once indicates that the callback will only be - * invoked once after which the event listener will be removed. + * const myOtherURL = new URL('https://example.org/foo?bar=baz#quux'); + * console.log(myOtherURL.search); // Logs "?bar=baz" + * ``` * - * The event listener is appended to target's event listener list and is not - * appended if it has the same type, callback, and capture. */ - addEventListener( - type: string, - listener: EventListenerOrEventListenerObject | null, - options?: boolean | AddEventListenerOptions, - ): void; - /** Dispatches a synthetic event to event target and returns true if either - * event's cancelable attribute value is false or its preventDefault() method - * was not invoked, and false otherwise. */ - dispatchEvent(event: Event): boolean; - /** Removes the event listener in target's event listener list with the same - * type, callback, and options. */ - removeEventListener( - type: string, - callback: EventListenerOrEventListenerObject | null, - options?: EventListenerOptions | boolean, - ): void; + * @see https://developer.mozilla.org/docs/Web/API/URL/search + */ + search: string; + + /** + * The `searchParams` property of the URL interface provides a direct interface to + * query parameters through a {@linkcode URLSearchParams} object. + * + * This property offers a convenient way to: + * - Parse URL query parameters + * - Manipulate query strings + * - Add, modify, or delete URL parameters + * - Work with form data in a URL-encoded format + * - Handle query string encoding/decoding automatically + * + * @example + * ```ts + * // Parse and access query parameters from a URL + * const myURL = new URL('https://example.org/search?term=deno&page=2&sort=desc'); + * const params = myURL.searchParams; + * + * console.log(params.get('term')); // Logs "deno" + * console.log(params.get('page')); // Logs "2" + * + * // Check if a parameter exists + * console.log(params.has('sort')); // Logs true + * + * // Add or modify parameters (automatically updates the URL) + * params.append('filter', 'recent'); + * params.set('page', '3'); + * console.log(myURL.href); // URL is updated with new parameters + * + * // Remove a parameter + * params.delete('sort'); + * + * // Iterate over all parameters + * for (const [key, value] of params) { + * console.log(`${key}: ${value}`); + * } + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/searchParams + */ + readonly searchParams: URLSearchParams; + + /** + * The `username` property of the URL interface is a string that represents the username of the URL. + * + * @example + * ```ts + * const myURL = new URL('https://someone:somepassword@example.org/baz'); + * console.log(myURL.username); // Logs "someone" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/username + */ + username: string; + + /** + * The `toJSON()` method of the URL interface returns a JSON representation of the URL. + * + * @example + * ```ts + * const myURL = new URL('https://example.org/foo'); + * console.log(myURL.toJSON()); // Logs "https://example.org/foo" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/toJSON + */ + toJSON(): string; } -/** - * EventTarget is a DOM interface implemented by objects that can receive events - * and may have listeners for them. +/** The URL interface represents an object providing static methods used for + * creating, parsing, and manipulating URLs. * - * @category Events + * @see https://developer.mozilla.org/docs/Web/API/URL + * + * @category URL */ -declare var EventTarget: { - readonly prototype: EventTarget; - new (): EventTarget; -}; +declare var URL: { + readonly prototype: URL; + /** + * Creates a new URL object by parsing the specified URL string with an optional base URL. + * Throws a TypeError If the URL is invalid or if a relative URL is provided without a base. + * + * Use this to parse and validate URLs safely. Use this instead of string + * manipulation to ensure correct URL handling, proper encoding, and protection against + * security issues like path traversal attacks. + * + * @example + * ```ts + * // Creating a URL from an absolute URL string + * const url1 = new URL('https://example.org/foo'); + * console.log(url1.href); // Logs "https://example.org/foo" + * + * // Creating a URL from a relative URL string with a base URL + * const url2 = new URL('/bar', 'https://example.org'); + * console.log(url2.href); // Logs "https://example.org/bar" + * + * // Joining path segments safely (prevents path traversal) + * const baseUrl = 'https://api.example.com/v1'; + * const userInput = '../secrets'; // Potentially malicious input + * const safeUrl = new URL(userInput, baseUrl); + * console.log(safeUrl.href); // Correctly resolves to "https://api.example.com/secrets" + * + * // Constructing URLs with proper encoding + * const search = 'query with spaces'; + * const url3 = new URL('https://example.org/search'); + * url3.searchParams.set('q', search); // Automatically handles URL encoding + * console.log(url3.href); // "https://example.org/search?q=query+with+spaces" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/URL + */ + new (url: string | URL, base?: string | URL): URL; -/** @category Events */ -interface EventListener { - (evt: Event): void; -} + /** + * Parses a URL string or URL object and returns a URL object. + * + * @example + * ```ts + * const myURL = URL.parse('https://example.org'); + * console.log(myURL.href); // Logs "https://example.org/" + * console.log(myURL.hostname); // Logs "example.org" + * console.log(myURL.pathname); // Logs "/" + * console.log(myURL.protocol); // Logs "https:" + * + * const baseURL = new URL('https://example.org'); + * const myNewURL = URL.parse('/foo', baseURL); + * console.log(myNewURL.href); // Logs "https://example.org/foo" + * console.log(myNewURL.hostname); // Logs "example.org" + * console.log(myNewURL.pathname); // Logs "/foo" + * console.log(myNewURL.protocol); // Logs "https:" + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/parse_static + */ + parse(url: string | URL, base?: string | URL): URL | null; -/** @category Events */ -interface EventListenerObject { - handleEvent(evt: Event): void; -} + /** + * Returns a boolean value indicating if a URL string is valid and can be parsed. + * + * @example + * ```ts + * // Check if an absolute URL string is valid + * console.log(URL.canParse('https://example.org')); // Logs true + * console.log(URL.canParse('https:://example.org')); // Logs false + * + * // Check if a relative URL string with a base is valid + * console.log(URL.canParse('/foo', 'https://example.org')); // Logs true + * console.log(URL.canParse('/foo', 'https:://example.org')); // Logs false + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/canParse_static + */ + canParse(url: string | URL, base?: string | URL): boolean; -/** @category Events */ -type EventListenerOrEventListenerObject = - | EventListener - | EventListenerObject; + /** + * Creates a unique, temporary URL that represents a given Blob, File, or MediaSource object. + * + * This method is particularly useful for: + * - Creating URLs for dynamically generated content + * - Working with blobs in a browser context + * - Creating workers from dynamically generated code + * - Setting up temporary URL references for file downloads + * + * Note: Always call URL.revokeObjectURL() when you're done using the URL to prevent memory leaks. + * + * @example + * ```ts + * // Create a URL string for a Blob + * const blob = new Blob(["Hello, world!"], { type: "text/plain" }); + * const url = URL.createObjectURL(blob); + * console.log(url); // Logs something like "blob:null/1234-5678-9101-1121" + * + * // Dynamic web worker creation in Deno + * const workerCode = ` + * self.onmessage = (e) => { + * self.postMessage(e.data.toUpperCase()); + * }; + * `; + * const workerBlob = new Blob([workerCode], { type: "application/javascript" }); + * const workerUrl = URL.createObjectURL(workerBlob); + * const worker = new Worker(workerUrl, { type: "module" }); + * + * worker.onmessage = (e) => console.log(e.data); + * worker.postMessage("hello from deno"); + * + * // Always revoke when done to prevent memory leaks + * URL.revokeObjectURL(workerUrl); + * ``` + * + * @see https://developer.mozilla.org/docs/Web/API/URL/createObjectURL_static + */ + createObjectURL(blob: Blob): string; -/** @category Events */ -interface AddEventListenerOptions extends EventListenerOptions { - once?: boolean; - passive?: boolean; - signal?: AbortSignal; -} + /** + * Revokes a previously created object URL, freeing the memory associated with it. + * + * Important for memory management in applications that create dynamic URLs. + * Once an object URL is revoked: + * - It can no longer be used to fetch the content it referenced + * - The browser/runtime is allowed to release the memory or resources associated with it + * - Workers created via the URL will continue to run, but the URL becomes invalid for new creations + * + * For security and performance in Deno applications, always revoke object URLs as soon as + * they're no longer needed, especially when processing large files or generating many URLs. + * + * @see https://developer.mozilla.org/docs/Web/API/URL/revokeObjectURL_static + */ + revokeObjectURL(url: string): void; +}; -/** @category Events */ -interface EventListenerOptions { - capture?: boolean; +/** @category URL */ +interface URLPatternInit { + protocol?: string; + username?: string; + password?: string; + hostname?: string; + port?: string; + pathname?: string; + search?: string; + hash?: string; + baseURL?: string; } -/** @category Events */ -interface ProgressEventInit extends EventInit { - lengthComputable?: boolean; - loaded?: number; - total?: number; +/** @category URL */ +type URLPatternInput = string | URLPatternInit; + +/** @category URL */ +interface URLPatternComponentResult { + input: string; + groups: Record; } -/** Events measuring progress of an underlying process, like an HTTP request - * (for an XMLHttpRequest, or the loading of the underlying resource of an - * ,