feat(mock): support asynchronous reply options callbacks

[Develop-KIM]

This relates to...

Fixes #1348 (see my comment there clarifying the scope vs #1757/#1758)

Rationale

#1758 made the data argument awaitable (reply(200, async (opts) => body)), but the ask in #1348 — an async reply options callback — still fails on main:

mockPool.intercept({ path: '/fixture' }).reply(async (opts) => ({
  statusCode: 200,
  data: await readFile('./fixture.json')
}))
// InvalidArgumentError: statusCode must be defined

wrappedDefaultsCallback assumes the callback returns a plain object: a Promise passes the typeof === 'object' check, contributes nothing when spread into { data: '', responseOptions: {}, ...promise }, and validation throws. This is what Polly.JS/nock-style record-and-replay adapters need (loading recorded responses from disk asynchronously).

Changes

Extends the existing isPromise pattern from #1758:

• lib/mock/mock-interceptor.js: wrappedDefaultsCallback detects a promise result and resolves the dispatch data (format check + validation + createMockScopeDispatchData) once it settles.
• lib/mock/mock-utils.js: mockDispatch detects a promise from the dispatch-data callback and defers the reply (extracted into dispatchMockReply) until it resolves. A rejection can no longer throw synchronously from dispatch, so it is surfaced via handler.onResponseError — the same route as replyWithError. Sync callbacks keep their synchronous-throw semantics.
• Consumed/pending bookkeeping now happens before callback resolution, so a dispatch pending on an async callback cannot be re-matched beyond its allowed times — consistent with how async data callbacks already behave (they mark consumption at dispatch time).
• Types: MockReplyOptionsCallback may return a Promise of the reply options (extracted a named MockReplyOptions type).
• Docs: MockPool.md — callback description + a new async example.
• Tests: async happy path, defaultReplyHeaders/replyContentLength interaction, times() bookkeeping, invalid resolved format, and rejection propagation; tsd assertions for the async signature.

Features

• MockInterceptor.reply() accepts an asynchronous reply options callback.

Bug Fixes

N/A

Breaking Changes and Deprecations

N/A

Status

• I have read and agreed to the Developer's Certificate of Origin
• Tested
• Benchmarked (optional)
• Documented
• Review ready
• In review
• Merge ready

🤖 Generated with Claude Code

[mcollina]

lgtm

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.45%. Comparing base (3c662a5) to head (48ba2e5).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5534   +/-   ##
=======================================
  Coverage   93.44%   93.45%           
=======================================
  Files         110      110           
  Lines       37329    37376   +47     
=======================================
+ Hits        34883    34928   +45     
- Misses       2446     2448    +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 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.