feat: Add setDisableFakeTimersDetection to opt out of fake-timer fingerprinting

[nev21]

_isFakeTimersEnabled() detects Sinon-style fake timers by checking for a patched setTimeout.clock property, and uses that to decide whether deferred promise continuations hop via a 0ms timeout (fake-timer-friendly) or a real microtask. This fingerprint is always active in production, so any code that patches setTimeout and happens to expose a .clock property (not necessarily Sinon) silently changes the library's internal scheduling.

Rather than stripping the check via a #ifdef DEBUG build flag, add setDisableFakeTimersDetection(disable?: boolean) so consumers can opt out at runtime while keeping the affordance available by default. Passing undefined restores the default (detection enabled); any other value is coerced via !!.

[Copilot]

Pull request overview

Adds a runtime opt-out for the library’s Sinon-style fake-timer detection (setTimeout.clock fingerprint) so consumers can force deferred continuations to use real microtasks even when a patched setTimeout.clock exists. This extends the existing internal scheduling behavior while keeping default behavior unchanged unless the new setter is called.

Changes:

• Added setDisableFakeTimersDetection(disable?: boolean) and integrated it into _isFakeTimersEnabled() so detection can be disabled at runtime.
• Exported the new API from the package root and added a dedicated test suite validating default/disabled/restored behavior under Sinon fake timers.
• Documented the behavior and side effects in both README.md and docs/README.md, and added an unreleased changelog entry.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Adds a top-level section pointing readers to the new fake-timer detection docs and opt-out API.
lib/test/src/promise/fakeTimersDetection.test.ts	Adds tests covering default detection behavior, opt-out behavior, and restoring defaults.
lib/src/promise/itemProcessor.ts	Implements the opt-out flag and exposes setDisableFakeTimersDetection(); updates fake-timer detection path.
lib/src/index.ts	Exports setDisableFakeTimersDetection from the package root entrypoint.
docs/README.md	Adds detailed documentation on fake timer detection, usage, and side effects.
CHANGELIST.md	Adds an Unreleased feature entry describing the new API and its behavior.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.66%. Comparing base (efbcfb2) to head (fe14baf).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #532      +/-   ##
==========================================
+ Coverage   97.57%   97.66%   +0.08%     
==========================================
  Files          28       28              
  Lines        1527     1540      +13     
  Branches      358      362       +4     
==========================================
+ Hits         1490     1504      +14     
+ Misses         37       36       -1     

Files with missing lines	Coverage Δ
lib/src/promise/itemProcessor.ts	100.00% <100.00%> (+1.33%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nevware21-bot]

Approved by nevware21-bot