用途:指导在 MoonBit 的 js 后端中编写 JavaScript 绑定,适用于为浏览器 DOM、Node 内置模块、Deno API 或 npm 包添加 FFI 声明,以及包装 JS 对象、桥接 Promise、生成 .d.ts。
主要能力:提供 extern "js" 声明方式(内联 #| JS 字面量、= "Math" "max" 模块加名称、#module("node:path") 编译期导入);JS 与 MoonBit 类型映射表(含 number 精度、BigInt、Uint8Array、Promise 等);用 #external pub type 与 %identity 包装不透明 JS 值;用 get/set/call_method 操作任意 JS 对象;区分 null 与 undefined;用 %async.suspend 与 %async.run 桥接 Promise;在 moon.pkg 中配置 targets、link.js.exports 与 format(esm/cjs/iife)。
使用方式:按四阶段工作流执行——项目设置(moon.mod.json 设 preferred-target,moon.pkg 用 targets 门控 FFI 文件并配置 link)、FFI 层(写私有 extern "js")、MoonBit API 层(写 pub 安全包装)、Promise 异步桥接;测试用 moon check、moon test、moon build,异步测试需 import { "moonbitlang/async" } for "test",版本 0.17.0 以上。
限制:JS 无整数类型,超过 2^53 的 Int64/UInt64 会丢精度,需用 BigInt;Map、Result、Json 等非 #external trait 对象不可直接跨 FFI;#module 仅支持具名导出且模块名须为编译期常量;moon test 固定用 CJS,ESM-only 包测试可能失败;不要用 supported-targets 包级门控。具体价格、平台支持等资料暂未提供。