Merge branch 'main' into tsgo

Author: iuioiua

.github/CODEOWNERS

@@ -22,6 +22,10 @@ Example
 
 <!-- A clear and concise description of what you expected to happen. -->
 
+**Actual behavior**
+
+<!-- Actual output of the steps, in your environment. -->
+
 **Environment**
 
 <!-- please complete the following information -->

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,7 +1,7 @@
 name: ci
 
 permissions:
-  contents: write
+  contents: read
 
 on:
   push:

.github/workflows/ci.yml

@@ -22,3 +22,4 @@ _tmp/
 
 # tsconfig for bun
 /tsconfig.json
+.claude/

.gitignore

@@ -0,0 +1,134 @@
+# Deno Standard Library
+
+The Deno Standard Library is a collection of high-quality packages for Deno and
+the web, distributed via JSR as `@std/*`. It supports multiple runtimes: Deno,
+Node.js, Bun, browsers, and Cloudflare Workers.
+
+## Repository Structure
+
+- Each top-level directory is a package (e.g., `async/`, `http/`,
+  `collections/`)
+- `_tools/` contains internal CI/dev tooling (lint plugins, doc checkers, etc.)
+- Root `deno.json` defines the workspace, tasks, and compiler options
+- `import_map.json` maps all `@std/*` packages and dev dependencies
+
+### Package Layout
+
+Every package follows this structure:
+
+```
+<package>/
+├── deno.json              # Name (@std/<package>), version, exports
+├── mod.ts                 # Public entry point
+├── <api>.ts               # Implementation (one function/class per file)
+├── <api>_test.ts          # Tests for the corresponding source file
+└── unstable_<api>.ts      # Experimental APIs (stable packages only)
+```
+
+- **Minimal exports**: each file exports a single function/class and related
+  types
+- **Unstable APIs** (`unstable_*.ts`): used in packages with version >= 1.0.0;
+  must have `@experimental` TSDoc tag; must NOT be exported from `mod.ts`
+- Packages with version < 1.0.0 have no unstable file restrictions
+
+## Quality Gate
+
+Run `deno task ok` before submitting. This runs:
+
+- `deno lint` (includes custom style-guide plugin at `_tools/lint_plugin.ts`)
+- `deno fmt --check`
+- `deno task test:browser` (browser compatibility check)
+- `deno task test` (full test suite with coverage and doc tests)
+
+Additional lint tasks available:
+
+- `deno task lint:circular` — circular dependency detection
+- `deno task lint:mod-exports` — validates `mod.ts` exports
+- `deno task lint:docs` — validates JSDoc completeness
+- `deno task lint:import-map` — validates import map
+- `deno task lint:export-names` — verifies export naming
+- `deno task lint:unstable-deps` — tracks unstable feature usage
+- `deno task typos` — spell checking
+
+## PR Conventions
+
+### Title Format
+
+PR titles must follow semantic format with a package scope:
+
+```
+feat(http): add streaming response support
+fix(csv): handle escaped quotes correctly
+docs(fmt): update docstrings
+deprecation(encoding): base32hex
+```
+
+The scope must match an existing package name. New packages must first add their
+name to the `scopes` list in `.github/workflows/title.yml`.
+
+### Commit Messages
+
+Follow the same semantic format as PR titles.
+
+## Testing
+
+- Framework: `Deno.test()` with `@std/assert` for assertions
+- Test names: descriptive, include the symbol and criteria
+  - `delay() resolves immediately with ms = 0`
+  - `ensureDirSync() creates dir if it does not exist`
+- Each source file gets a corresponding `_test.ts` file
+- Do NOT use `@std/assert` in implementation code — only in tests
+
+## Documentation Requirements
+
+All public symbols must have JSDoc with:
+
+1. Short description
+2. `@typeParam` for each type parameter
+3. `@param` for each parameter
+4. `@returns` for return value
+5. At least one `@example` with a title and runnable code snippet
+
+Example snippets must be reproducible and use `@std/assert` assertions. Use
+`ignore` directive to skip running a snippet, `expect-error` for expected
+failures.
+
+Module files (`mod.ts`) need a `@module` tag.
+
+## Error Message Style
+
+- Sentence case, no trailing period
+- Active voice: "Cannot parse input x" not "Input x cannot be parsed"
+- No contractions: "Cannot" not "Can't"
+- Quote string values: `Cannot parse input "hello, world"`
+- Use colons for context: `Cannot parse input x: value is empty`
+- State current and desired state when possible
+
+Exception: `@std/assert` uses periods in error messages (downstream compat).
+
+## CI Pipeline
+
+Tests run on Ubuntu, Windows, and macOS against Deno v1.x, v2.x, and canary.
+Cross-runtime testing includes Node.js and Bun. Timezone-sensitive tests run
+across Sydney, London, and Toronto.
+
+## Versioning and Releases
+
+- Packages >= 1.0.0: follow semver
+- Packages < 1.0.0: follow semver proposal
+  (https://github.com/semver/semver/pull/923)
+- Release tags: `release-YYYY.MM.DD`
+- Publishing: `workspace_publish` workflow pushes to JSR
+
+## Deprecation Policy
+
+Deprecated APIs use the format:
+
+```ts
+/**
+ * @deprecated This will be removed in X.Y.Z. Use {@linkcode bar} instead.
+ */
+```
+
+Deprecated symbols are removed in the next major version. PRs use the title
+format `deprecation(<package>): <symbol>`.

AGENTS.md

@@ -177,6 +177,7 @@ function assertHasExampleTag(
       "@example tag must have a title and TypeScript code snippet",
       document,
     );
+    if (tag.doc === undefined) continue;
     /**
      * Otherwise, if the example title is undefined, it is given the title
      * "Example #" by default.
@@ -202,6 +203,7 @@ function assertHasTypeParamTags(
     `Symbol must have a @typeParam tag for ${typeParamName}`,
     document,
   );
+  if (tag === undefined) return;
   assert(
     // @ts-ignore doc is defined
     tag.doc !== undefined,

_tools/check_docs.ts

@@ -45,8 +45,6 @@ export type SettledRecord<T extends Record<PropertyKey, unknown>> = {
  * {@link https://github.com/tc39/proposal-await-dictionary | Await Dictionary}
  * proposal (`Promise.allKeyed`).
  *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
  * @typeParam T The record shape with resolved (unwrapped) value types. For
  * example, if passing `{ foo: Promise<number> }`, `T` would be `{ foo: number }`.
  * @param record A record where values are promise-like (thenables) or plain values.
@@ -57,7 +55,7 @@ export type SettledRecord<T extends Record<PropertyKey, unknown>> = {
  *
  * @example Basic usage
  * ```ts
- * import { allKeyed } from "@std/async/unstable-all-keyed";
+ * import { allKeyed } from "@std/async/all-keyed";
  * import { assertEquals } from "@std/assert";
  *
  * const result = await allKeyed({
@@ -70,7 +68,7 @@ export type SettledRecord<T extends Record<PropertyKey, unknown>> = {
  *
  * @example Parallel HTTP requests
  * ```ts no-assert ignore
- * import { allKeyed } from "@std/async/unstable-all-keyed";
+ * import { allKeyed } from "@std/async/all-keyed";
  *
  * const { user, posts } = await allKeyed({
  *   user: fetch("/api/user").then((r) => r.json()),
@@ -80,7 +78,7 @@ export type SettledRecord<T extends Record<PropertyKey, unknown>> = {
  *
  * @example Mixed promises and plain values
  * ```ts
- * import { allKeyed } from "@std/async/unstable-all-keyed";
+ * import { allKeyed } from "@std/async/all-keyed";
  * import { assertEquals } from "@std/assert";
  *
  * const result = await allKeyed({
@@ -124,8 +122,6 @@ export function allKeyed<T extends Record<PropertyKey, unknown>>(
  * {@link https://github.com/tc39/proposal-await-dictionary | Await Dictionary}
  * proposal (`Promise.allSettledKeyed`).
  *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
  * @typeParam T The record shape with resolved (unwrapped) value types. For
  * example, if passing `{ foo: Promise<number> }`, `T` would be `{ foo: number }`.
  * @param record A record where values are promise-like (thenables) or plain values.
@@ -134,7 +130,7 @@ export function allKeyed<T extends Record<PropertyKey, unknown>>(
  *
  * @example Basic usage
  * ```ts
- * import { allSettledKeyed } from "@std/async/unstable-all-keyed";
+ * import { allSettledKeyed } from "@std/async/all-keyed";
  * import { assertEquals } from "@std/assert";
  *
  * const settled = await allSettledKeyed({
@@ -148,7 +144,7 @@ export function allKeyed<T extends Record<PropertyKey, unknown>>(
  *
  * @example Error handling
  * ```ts
- * import { allSettledKeyed } from "@std/async/unstable-all-keyed";
+ * import { allSettledKeyed } from "@std/async/all-keyed";
  * import { assertEquals, assertExists } from "@std/assert";
  *
  * const settled = await allSettledKeyed({

async/unstable_all_keyed.ts async/all_keyed.tsasync/unstable_all_keyed.ts renamed to async/all_keyed.ts

@@ -1,5 +1,5 @@
 // Copyright 2018-2026 the Deno authors. MIT license.
-import { allKeyed, allSettledKeyed } from "./unstable_all_keyed.ts";
+import { allKeyed, allSettledKeyed } from "./all_keyed.ts";
 import {
   assertEquals,
   assertFalse,
@@ -195,3 +195,25 @@ Deno.test("allKeyed() ignores non-enumerable symbol keys", async () => {
   assertEquals(Object.keys(result), ["visible"]);
   assertFalse(sym in result);
 });
+
+Deno.test("allKeyed() resolves custom thenables", async () => {
+  const thenable = {
+    then(resolve: (value: number) => void) {
+      resolve(99);
+    },
+  } as PromiseLike<number>;
+  const result = await allKeyed({ val: thenable });
+
+  assertEquals(result.val, 99);
+});
+
+Deno.test("allSettledKeyed() resolves custom thenables", async () => {
+  const thenable = {
+    then(resolve: (value: string) => void) {
+      resolve("from thenable");
+    },
+  } as PromiseLike<string>;
+  const result = await allSettledKeyed({ val: thenable });
+
+  assertEquals(result.val, { status: "fulfilled", value: "from thenable" });
+});

async/unstable_all_keyed_test.ts async/all_keyed_test.tsasync/unstable_all_keyed_test.ts renamed to async/all_keyed_test.ts

@@ -2,8 +2,8 @@
 // This module is browser compatible.
 
 /**
- * A debounced function that will be delayed by a given `wait`
- * time in milliseconds. If the method is called again before
+ * A debounced function whose execution is delayed by a given `wait`
+ * time in milliseconds. If the function is called again before
  * the timeout expires, the previous call will be aborted.
  */
 export interface DebouncedFunction<T extends Array<unknown>> {
@@ -36,45 +36,50 @@ export interface DebouncedFunction<T extends Array<unknown>> {
  *   log(event);
  * }
  * // wait 200ms ...
- * // output: Function debounced after 200ms with baz
+ * // output: [modify] /path/to/file
  * ```
  *
  * @typeParam T The arguments of the provided function.
  * @param fn The function to debounce.
  * @param wait The time in milliseconds to delay the function.
+ * Must be a positive integer.
+ * @throws {RangeError} If `wait` is not a non-negative integer.
  * @returns The debounced function.
  */
 // deno-lint-ignore no-explicit-any
 export function debounce<T extends Array<any>>(
   fn: (this: DebouncedFunction<T>, ...args: T) => void,
   wait: number,
 ): DebouncedFunction<T> {
+  if (!Number.isInteger(wait) || wait < 0) {
+    throw new RangeError("'wait' must be a positive integer");
+  }
   let timeout: number | null = null;
-  let flush: (() => void) | null = null;
+  let pendingFlush: (() => void) | null = null;
 
   const debounced: DebouncedFunction<T> = ((...args: T) => {
     debounced.clear();
-    flush = () => {
+    pendingFlush = () => {
       debounced.clear();
       fn.call(debounced, ...args);
     };
-    timeout = Number(setTimeout(flush, wait));
+    timeout = Number(setTimeout(pendingFlush, wait));
   }) as DebouncedFunction<T>;
 
   debounced.clear = () => {
-    if (typeof timeout === "number") {
+    if (timeout !== null) {
       clearTimeout(timeout);
       timeout = null;
-      flush = null;
+      pendingFlush = null;
     }
   };
 
   debounced.flush = () => {
-    flush?.();
+    pendingFlush?.();
   };
 
   Object.defineProperty(debounced, "pending", {
-    get: () => typeof timeout === "number",
+    get: () => timeout !== null,
   });
 
   return debounced;