Add UnwrapIfPromiseAsync extension method for non-blocking promise resolution

[Copilot]

UnwrapIfPromise blocks the calling thread while waiting for a JsPromise to settle, which causes thread pool exhaustion in async .NET environments. EvaluateAsync/InvokeAsync cover the common cases, but there's no async path when you already hold a JsValue that may be a promise (e.g., from Call(), GetValue(), etc.).

Changes

• Engine.Async.cs: UnwrapResultAsync promoted from private to internal to allow delegation from extension methods.
• JsValueExtensions.cs: New UnwrapIfPromiseAsync(this JsValue, CancellationToken = default) extension — delegates to promise.Engine.UnwrapResultAsync for promises, short-circuits with Task.FromResult for non-promise values.
• README.md: Added a new "Asynchronous Execution" section documenting EvaluateAsync/ExecuteAsync/InvokeAsync and UnwrapIfPromiseAsync with code examples and guidance on when to use each.

Usage

// Blocking (old):
var result = engine.Invoke("fetchData", url).UnwrapIfPromise();

// Non-blocking (new):
var result = await engine.Invoke("fetchData", url).UnwrapIfPromiseAsync(cancellationToken);

Respects Options.Constraints.PromiseTimeout and cancellation, matching the behaviour of EvaluateAsync.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Feature Request: Add an Async Version of UnwrapIfPromise for JsValue</issue_title>
<issue_description>The engine currently provides UnwrapIfPromise, which allows synchronously waiting for a JsPromise and retrieving its result.

However, when the underlying JsPromise represents an I/O-bound asynchronous operation (for example, await httpClient.GetAsync(url)), UnwrapIfPromise blocks the calling thread while waiting for completion.

This blocking behavior can cause several issues:

• Thread pool exhaustion in ASP.NET Core or other asynchronous environments
• Inability to integrate naturally with existing async/await call chains
• Reduced scalability and throughput in high-concurrency scenarios

To address this, would it be possible to introduce an asynchronous alternative, such as:

ValueTask<JsValue> UnwrapIfPromiseAsync(this JsValue value)

This method would asynchronously await the completion of a JsPromise instead of blocking the calling thread.

Benefits would include:

• Preserving the async call chain end-to-end
• Avoiding thread blocking
• Better support for I/O-bound workloads and modern .NET async patterns

An async API would significantly improve integration in environments where non-blocking execution is critical.
</issue_description>

<agent_instructions>Check of there's real value here. Engine already has EvaluateAsync, will it suffice?</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Feature Request: Add an Async Version of UnwrapIfPromise for JsValue #2297

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[lahma]

@copilot update readme to contain both evaluateasync and this new feature.

[Copilot]

@copilot update readme to contain both evaluateasync and this new feature.

Added a new "Asynchronous Execution" section to the README in commit 4f86077. It covers EvaluateAsync/ExecuteAsync/InvokeAsync (with an HTTP fetch example, cancellation, and timeout notes) and UnwrapIfPromiseAsync (with examples for the "already have a JsValue" scenario), plus a note on when to prefer async over the synchronous UnwrapIfPromise.

[lahma]

@copilot tests seem to hang