feat(timer): add cancellable microtask scheduling with cross-runtime fallback support#570
Open
nev21 wants to merge 1 commit into
Open
feat(timer): add cancellable microtask scheduling with cross-runtime fallback support#570nev21 wants to merge 1 commit into
nev21 wants to merge 1 commit into
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #570 +/- ##
==========================================
+ Coverage 99.39% 99.41% +0.02%
==========================================
Files 154 158 +4
Lines 4659 4821 +162
Branches 998 1036 +38
==========================================
+ Hits 4631 4793 +162
Misses 28 28
🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new Timer microtask scheduling API (scheduleMicrotask + related helpers/types) that provides cancellable microtasks with consistent fallback behavior across runtimes (native queueMicrotask → Promise microtasks → timer-backed queue), plus supporting documentation, tests, and size/metadata updates.
Changes:
- Introduces new
timer/microtaskpublic API surface (helpers + types) and exports it from the main index. - Implements Promise- and timer-backed microtask fallbacks, including timeout integration to preserve ordering.
- Adds common-runtime tests and updates README/CHANGELOG/package metadata and size limits for the new API.
Reviewed changes
Copilot reviewed 13 out of 14 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Documents the new microtask helpers and adds them to the categorized API listing. |
| package.json | Adds microtask-related keywords to package metadata. |
| lib/package.json | Adds microtask-related keywords to the published library package metadata. |
| CHANGELOG.md | Adds an Unreleased entry describing the new microtask API and behavior. |
| .size-limit.json | Updates size budgets and adds new size-limit entries for the new exports. |
| lib/test/bundle-size-check.js | Adjusts bundle size thresholds to accommodate new API additions. |
| lib/test/src/common/timer/microtask.test.ts | Adds comprehensive tests for ordering, cancellation, fallback behavior, and error surfacing. |
| lib/test/src/common/object/for_each_key.test.ts | Minor formatting/indentation adjustment in an existing test. |
| lib/src/timer/timeout.ts | Adds a microtask-flush hook so timer-backed microtasks can run before timeout callbacks. |
| lib/src/timer/microtasks/timerMicrotask.ts | Implements a timer-backed microtask queue and flush scheduling logic. |
| lib/src/timer/microtasks/runMicrotask.ts | Adds a helper to run microtasks while rethrowing exceptions via a task. |
| lib/src/timer/microtasks/promiseMicrotask.ts | Adds a Promise-based microtask scheduler wrapper. |
| lib/src/timer/microtask.ts | Adds the public microtask API (getters, options, scheduling, cancellable handler). |
| lib/src/index.ts | Exports the new microtask APIs (and also re-exports IGetLength). |
Comment on lines
+16
to
+38
| let _promiseFn: ICachedValue<ScheduleMicrotaskFn>; | ||
|
|
||
| /** | ||
| * @internal | ||
| * @since 0.15.0 | ||
| */ | ||
| function _promiseScheduleFn(promiseCls: PromiseConstructor): ScheduleMicrotaskFn { | ||
| return function (callback: () => void ): void { | ||
| promiseCls.resolve().then(() => { | ||
| _runMicroTask(callback); | ||
| }); | ||
| }; | ||
| } | ||
|
|
||
| /** | ||
| * @internal | ||
| * @since 0.15.0 | ||
| */ | ||
| function _initPromiseFn(): void { | ||
| let promiseCls = getInst<PromiseConstructor>("Promise"); | ||
|
|
||
| _promiseFn = createCachedValue((promiseCls && isFunction(promiseCls.resolve)) ? _promiseScheduleFn(promiseCls) : UNDEF_VALUE as any); | ||
| } |
Comment on lines
+22
to
+27
| function _promiseScheduleFn(promiseCls: PromiseConstructor): ScheduleMicrotaskFn { | ||
| return function (callback: () => void ): void { | ||
| promiseCls.resolve().then(() => { | ||
| _runMicroTask(callback); | ||
| }); | ||
| }; |
Comment on lines
+42
to
+55
| export interface MicroTaskOptions { | ||
| /** | ||
| * Provide a custom scheduling function to use ONLY when native `queueMicrotask` and Promise support | ||
| * is unavailable. When specified, this option takes precedence over `disablePromise`. | ||
| */ | ||
| scheduleFn?: ScheduleMicrotaskFn; | ||
|
|
||
| /** | ||
| * Disable Promise fallback usage and use `scheduleTimeout(..., 0)` instead. When `scheduleFn` is | ||
| * not provided, this option controls whether to use `scheduleTimeout(..., 0)` as the fallback | ||
| * instead of `Promise.resolve().then(...)`. | ||
| */ | ||
| disablePromise?: boolean; | ||
| } |
Comment on lines
+194
to
+206
| function _createCancellableMicroTask(callback: () => void, queueFn: ScheduleMicrotaskFn): ITimerHandler { | ||
| let handler: _TimerHandler; | ||
| // Used to track the currently scheduled task, incremented to cancel pending tasks when needed | ||
| let currentTask = 0; | ||
|
|
||
| function _scheduleTask() { | ||
| let taskId = ++currentTask; | ||
| queueFn(() => { | ||
| if (taskId === currentTask) { | ||
| handler.dn(); | ||
| callback(); | ||
| } | ||
| }); |
| let handler: _TimerHandler; | ||
| // Used to track the currently scheduled task, incremented to cancel pending tasks when needed | ||
| let currentTask = 0; | ||
|
|
Comment on lines
+61
to
+62
| // Run and pending microtasks before running the timeout callback to allow any microtasks | ||
| // scheduled within the callback to run before the next timeout |
| * Reset the timer-backed microtask queue state. Intended for tests that need a clean queue/timer instance. | ||
| * @since 0.15.0 | ||
| */ | ||
| export function _resetMicrotaskQueue(): void { |
|
|
||
| import { UNDEF_VALUE } from "../../internal/constants"; | ||
| import { ITimerHandler } from "../handler"; | ||
| import { MicrotaskFn, ScheduleMicrotaskFn } from "../microtask"; |
…fallback support Add a new microtask scheduling API that extends standard microtasks with cancellable handlers while preserving runtime parity across Node.js, browsers, and web workers. - Add timer microtask API surface: - scheduleMicrotask - hasQueueMicrotask - getQueueMicrotask - setMicroTaskFallbackOptions - ScheduleMicrotaskFn and MicroTaskOptions types - Implement fallback chain: - native queueMicrotask when available - Promise.resolve().then fallback - timer-backed microtask queue fallback - Return ITimerHandler from scheduled microtasks to support cancellation and refresh semantics. - Ensure thrown microtask callback errors are surfaced via task rethrow handling. - Integrate timer-backed microtask flushing with timeout scheduling behavior for correct ordering. - Export new public APIs from index entrypoints. - Add comprehensive common-runtime tests for ordering, cancellation, fallback behavior, nested microtasks, batching across ticks, and throw surfacing. - Update documentation and release notes: - README and CHANGELOG now describe runtime parity and that helpers extend standard microtasks as cancellable. - Update package metadata: - add microtask-related keywords to both package manifests. - Refresh size/check expectations and related tests for new API additions.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add a new microtask scheduling API that extends standard microtasks with cancellable handlers while preserving runtime parity across Node.js, browsers, and web workers.