skills.rest
openharmonyinsight
openharmonyinsightOFFICIAL
Explore all skills by this author →
GitHub

interop-promise

Debug ETS to JavaScript cross-VM Promise interop conversion and settlement.

31|6|Updated Jan 29, 2026
Search Tags:#javascript#arkts#promise interop#arkcompiler#interop debugging#coroutine await#napi deferred
One-click install
npx skills add https://github.com/openharmonyinsight/openharmony-skills --skill interop-promise
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: interop-promise
Source: https://github.com/openharmonyinsight/openharmony-skills/tree/main/skills/oh-arkruntime-interop-promise
Command: npx skills add https://github.com/openharmonyinsight/openharmony-skills --skill interop-promise

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you understand and troubleshoot cross-language Promise bridging between ETS (ArkTS) and JavaScript in ArkCompiler’s hybrid runtime, so resolved/rejected async results propagate correctly across VM boundaries.

Core Features & Use Cases

  • Promise Bridging (Wrap/Unwrap): Convert JS Promise ↔ ETS Promise proxy/wrapper with correct identity reuse and state handling (pending/linked/settled).
  • Await & Coroutine Safety: Diagnose stuck awaits by validating proxy detection, coroutine scheduling (yield-before-wait), and callback queue execution.
  • Interop State Machine Debugging: Trace fast-path vs slow-path behavior for JSCONVERT_WRAP(Promise) and JSCONVERT_UNWRAP(Promise), including SettleJsPromise and PromiseInterop.connectPromise.
  • Targets & Hotspots to Inspect: JSConvertPromise in js_convert.h, EtsPromise/EtsPromiseRef in ets_promise(.h/.cpp)/ets_promise_ref.h, JsJobQueue/Promise link in js_job_queue, and PromiseInterop.ets.

Quick Start

Use the interop-promise skill to diagnose why an awaited ArkTS Promise never resolves when it wraps a JavaScript Promise by reviewing EtsPromise proxy state, JsJobQueue callback wiring, and SettleJsPromise execution.

Frequently Asked Questions about interop-promise

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my ArkTS await hang when wrapping a JavaScript Promise?▼

An ArkTS await hangs when wrapping a JavaScript Promise due to failed proxy detection or incorrect coroutine scheduling during EtsAwaitPromise suspension. Diagnosing the JsJobQueue callback wiring and SettleJsPromise execution reveals where the cross-VM settlement propagation breaks.

How does Promise interop handle state conversion between ArkTS and JavaScript?▼

Promise interop handles state conversion by mapping JS Promise to ETS Promise proxy wrappers, ensuring correct identity reuse and state transitions across pending, linked, and settled phases during JSCONVERT_WRAP and JSCONVERT_UNWRAP operations.

How do I debug napi_deferred settlement propagation in a cross-VM ArkTS environment?▼

Debug napi_deferred settlement propagation by tracing the main-worker-thread execution of SettleJsPromise and verifying SharedReferenceStorage mappings to ensure resolved or rejected async results correctly cross the ArkCompiler runtime boundary.

What is the difference between fast-path and slow-path JSCONVERT_WRAP Promise execution?▼

Fast-path JSCONVERT_WRAP Promise execution optimizes direct proxy reuse, while the slow-path manages complex EtsPromiseRef state transitions and PromiseInterop.connectPromise linking when standard JS .then callback registration requires deeper interop state machine debugging.

Does ArkTS to JavaScript Promise bridging require specific runtime components?▼

ArkTS to JavaScript Promise bridging requires specific ArkCompiler runtime components including js_convert.h for JSConvertPromise logic, ets_promise files for EtsPromise state handling, and js_job_queue for JsJobQueue callback execution.

Related Skills

Explore More Software Engineering Skills→
markpittmarkpitt
22

blazor-expert

Provide expert guidance on Blazor components, state management, routing, and JS interop.

Community
Advanced
ComplianceAsCodeComplianceAsCode
2.8k

test-rule

Validate ComplianceAsCode security rules with Automatus and virsh.

Official
Advanced
eykdeykd

wrangler-sprite-auth

Authenticate Cloudflare Wrangler users in Sprite environments via OAuth proxy.

Community
Intermediate
cyoteecyotee

tevm-debugging

Trace EVM transactions with execution steps and gas profiling.

Community
Advanced