feat(runtime): backfill util debounce and throttle

[jdalton]

Backfill Node.js 26.10's util.debounce and util.throttle on older supported Node versions. Nub exposes them through CommonJS, named ESM imports, and compiled artifacts while leaving native implementations untouched; the feature matrix, documentation, and @nubjs/types describe the same boundary.

Node source and validation

The implementations are ported from nodejs/node#65899 at a2c8da5. The standalone runner stages the same helper files.

Validation

• node scripts/util-rate.test.mjs: 9 passed on Node 24.10 and 26.9.
• node npm/nub-types/test/run.mjs: 22 expected outcomes across TypeScript 5.8, 5.9, 6.0, and 7.0.
• scripts/rust-build.sh build -p nub-cli --profile fast --features compile: passed.
• scripts/rust-build.sh test -p nub-core --profile fast polyfill_rows_are_backed_by_runtime_files: passed.
• Static and dynamic compile-augmentation fixtures on Node 26.9: plain Node fails; Nub and both compiled artifacts print debounce,throttle.
• node scripts/build-runner-npm.mjs: staged all 19 runtime files.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
nub	Ready	Preview	Oct 7, 2026 5:45pm UTC

[pullfrog]

Important

Compiled named imports and abort semantics still regress on pre-26.10 Node, and the new public APIs are not yet represented in Nub's type and documentation contract.

Reviewed changes in 141fed4, covering the complete 12-file runtime, loader, packaging, and test diff.

• Runtime shims — ports Node 26.10's debounce and throttle implementations and installs missing methods on the native node:util singleton.
• ESM exposure — redirects util and node:util imports through a data-URL facade on both loader tiers while preserving native implementations.
• Distribution and tests — stages the helper files in @nubjs/runner and adds focused behavior, loader-tier, cancellation, and validation coverage.

⚠️ The public API contract is incomplete

The new methods are absent from the canonical feature matrix, Modern APIs documentation, and @nubjs/types; the package's pinned @types/node@26.2.0 does not declare either export. TypeScript users therefore cannot consume the backfilled named imports without local declarations, and the repository has no version-band record for the promised runtime behavior.

Technical details

# Complete the public API surfaces

## Affected sites
- `crates/nub-core/src/node/feature_matrix.rs:165` — no `util.debounce` or `util.throttle` feature rows record the polyfill-to-native boundary at Node 26.10.
- `site/content/docs/runtime/modern-apis.mdx:26` — the runtime API reference does not document either method or its delivery band.
- `npm/nub-types/common.d.ts:24` — neither named `node:util` export is declared, and the positive type fixture cannot exercise the API.

## Required outcome
- Record both features in the matrix, document their availability and delivery, and add conflict-safe declarations plus inference coverage for the supported TypeScript matrix.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[jdalton]

Addressed the public API gap in 2c6626a: the feature matrix, Modern APIs page, and @nubjs/types now cover both methods and the Node 26.10 boundary. The positive fixture checks both util import spellings across TypeScript 5.8–7.0; all 22 expected outcomes pass.

[pullfrog]

Important

The new @nubjs/types declarations omit the documented callback this contract, so the type surface is not yet complete.

Reviewed changes since the prior Pullfrog review at 141fed4, covering the follow-up fix in 2c6626a and the complete current diff.

• Added compiled import support — redirected static and dynamic util imports through a target-gated virtual facade and added compile-augmentation fixtures.
• Hardened runtime internals — adopted propagation-resistant abort handling and captured mutable intrinsic operations with focused regressions.
• Completed public surfaces — added feature-matrix rows, Modern APIs documentation, and ambient declarations with inference coverage.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

Important

The callback context remains non-callable, so the type surface still rejects Node's documented recursive callback usage.

Reviewed changes since the prior Pullfrog review at 2c6626a, covering the follow-up fix in f7fdd12 and the complete current diff.

• Typed callback context — added debounce/throttle callback context interfaces and strict fixture assertions for control properties and inferred return types.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

Important

The callback contexts are callable now, but their broad unknown signatures still reject valid typed recursive-result use and accept invalid argument lists.

Reviewed changes since the prior Pullfrog review at f7fdd12, covering the follow-up fix in 7e4ebf5 and the complete current diff.

• Made callback contexts callable — added recursive call signatures for debounce and throttle plus positive fixture invocations across the supported TypeScript matrix.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[jdalton]

[agent] Addressed the latest type-safety feedback in debd1cf. Callback this now uses the matching debounced/throttled function type, preserving exact argument and result types; added positive recursive-result assertions and a negative fixture for wrong/missing arguments. I could not add the opt-in ci label with this GitHub credential.

[pullfrog]

Important

The new callback this signatures regress inference and reject valid callbacks on every pinned TypeScript compiler.

Reviewed changes since the prior Pullfrog review at 7e4ebf5, covering debd1cf with the full PR diff as context.

• Replaced callback contexts with the generic returned-function interfaces to preserve recursive arguments and results.
• Strengthened type fixtures with concrete recursive-result assertions and an expected-failure argument fixture.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using gpt-6.1-sol ｜ 𝕏}

[jdalton]

[agent] Reverted the recursive this typing in 6c00a37. The review reproduced a real inference regression: valid function-expression callbacks lost their inferred arguments and results across all pinned TypeScript versions. The public callback context still exposes its controls; recursive calls through this remain a declaration limitation because the attempted recursive typing breaks ordinary inference. Removed the false-positive arity fixture and verified all 22 remaining fixture outcomes with node npm/nub-types/test/run.mjs.

[pullfrog]

✅ No new issues found.

Reviewed changes since the prior Pullfrog review at debd1cf, covering the revert in 6c00a37 with the full PR diff as context.

• Restored callback inference by returning to generic-neutral callable this contexts while preserving typed controls and inferred outer arguments/results.
• Removed the false-positive arity fixture and restored recursive-result assertions to the previously acknowledged Promise<unknown> limitation.

All 22 expected fixture outcomes passed across TypeScript 5.8, 5.9, 6.0, and 7.0, with two existing TypeScript 5.8 DOM checks explicitly skipped. Restoring the regressed signatures in memory made the positive fixture fail with TS2345 on TypeScript 5.8, 5.9, and 6.0, confirming that it detects the inference regression.

  ^{｜ View workflow run ｜ Using gpt-6.1-sol ｜ 𝕏}