mizchi/js

Comprehensive JavaScript/ FFI bindings for MoonBit, supporting multiple runtimes and platforms.

Import only what you need

0.13.0 split this library into nine modules. Depend on the ones your target actually has, and nothing else — a Cloudflare Worker no longer drags in node:fs, a CLI no longer drags in the DOM.

Dependencies only ever point toward js_core:

js_core <- js_builtin <- js_web <- js_node / js_browser / js_deno
                     <- js_bun
        <- js_convert
        <- js_webextensions

You only declare what you import directly; the modules those pull in resolve on their own.

Bindings that live outside this repo:

📖 User Guide — which modules to pick, aliases, per-runtime recipes, and the 0.12.x → 0.13.0 migration table.

Installation

moon add mizchi/js_core
moon add mizchi/js_web       # ...and whatever else you need

moon.mod:

import {
  "mizchi/js_core@0.13.0",
  "mizchi/js_web@0.13.0",
}

moon.pkg — the default alias is the last path segment, so give the module-root packages a short one:

import {
  "mizchi/js_core" @core,
  "mizchi/js_web/http",
}

Version Requirements

Developed and CI-tested against:

moon 0.1.20260915
moonc v0.10.13

CI tracks the latest MoonBit release, so a recent toolchain is the supported configuration. For the older stable toolchain, use v0.8.x.

Quick Links

📚 API Documentation by Platform

📖 Learning Resources

• MoonBit Cheatsheet - Quick reference for MoonBit syntax
• FFI Best Practice - Best practice for MoonBit JavaScript FFI
• Escape Hatch Pattern - Advanced FFI techniques
• For TypeScript Users - Migration guide from TypeScript
• User Guide - Picking modules, aliases, per-runtime recipes, 0.12.x migration
• Package Split Guide - moon.work multi-module layout and the split rationale

Supported Modules

Status Legend

• 🧪 Tested: Comprehensive test coverage, production ready
• 🚧 Partially: Core functionality implemented, tests incomplete
• 🤖 AI Generated: FFI bindings created, needs testing
• 📅 Planned: Scheduled for future implementation
• ❌ Not Supported: Technical limitations

Core JavaScript APIs

mizchi/js_core - Core FFI Package

The mizchi/js_core package provides the foundation for JavaScript interoperability in MoonBit:

Type System

• Any - Opaque type for JavaScript values
• Nullable[T] - Represents null | T
• Nullish[T] - Represents null | undefined | T
• Union2[A,B] ~ Union5[A,B,C,D,E] - TypeScript union types (A | B)
• Promise[T] - JavaScript Promise wrapper

FFI Operations (zero-cost conversions)

• identity[A,B](value: A) -> B - Type casting using %identity
• any[T](value: T) -> Any - Convert to Any
• Any::cast[T](self) -> T - Cast from Any
• obj["key"], obj["key"] = value - Property access (or _get(key), _set(key, value))
• Any::_call(method, args), Any::_invoke(args) - Method calls

Object & JSON

• new_object(), new_array() - Create JS objects/arrays
• object_keys(), object_values(), object_assign(), object_has_own()
• json_stringify(), json_parse(), json_stringify_pretty()

Async/Promise Support

• run_async(f) - Execute async functions (MoonBit builtin %async.run)
• suspend(f) - Await promises (MoonBit builtin %async.suspend)
• promisify0 ~ promisify3 - Convert callbacks to promises
• Promise utilities: resolve, reject, all, race, any, withResolvers

Error Handling

• JsError - Generic JS error type
• ThrowError - Wrapper for thrown errors
• try_sync(op) - Safe wrapper converting JS exceptions to MoonBit errors
• throwable(f) - Convert JS exceptions to ThrowError
• export_sync(op) - Convert MoonBit errors to JS exceptions
• throw_error(msg) - Throw JS Error

Type Checking

• is_object(), is_array(), is_null(), is_undefined(), is_nullish()

Nullish Utilities

• Nullish::to_option(), Nullable::to_option() - Convert to MoonBit Option
• nullable(opt) - Convert Option to JS nullable
• as_any(opt) - Convert Option[Any] to Any

API Summary

JavaScript Built-ins

All JavaScript built-in objects are exported from mizchi/js:

Web Standard APIs

Platform-independent Web Standard APIs (browsers, Node.js, Deno, edge runtimes), shipped as the separate mizchi/js_web module:

See mizchi/js_web for detailed Web APIs documentation

Runtime-Specific APIs

Web Standard, Node.js, Browser, Deno, Bun, and WebExtensions APIs ship as separate mizchi/js_* modules — add each one to your moon.mod import list only if you need it.

NPM Package Bindings

Moved to separate repository: NPM package bindings are now maintained at mizchi/npm_typed

Limited Support APIs

Project Status

• 📦 FFI foundation (mizchi/js_core) - Any, Promise, Nullable, target-specific interop. Split out into its own module
• 📦 JS built-ins (mizchi/js_builtin) - Object, Array, JSON, RegExp, Symbol, Proxy, ... Split out into its own module
• 📦 MoonBit ⇔ JS conversion (mizchi/js_convert) - Map/Json/Option/Result ⇔ Any, runtime type inspection. Split out into its own module
• ✅ mizchi/js - meta package re-exporting js_core + js_builtin, plus the wasm-gc entry
• 📦 Web Standards (mizchi/js_web) - fetch, URL, Streams, Blob, Crypto, WebSocket, Workers. Split out into its own module
• 📦 Node.js Core APIs (mizchi/js_node) - fs, path, process, child_process, etc. Split out into its own module
• 📦 Browser / DOM (mizchi/js_browser) - Split out in v0.11.0
• 📦 Deno Runtime (mizchi/js_deno) - Split out in v0.11.0
• 📦 Bun Runtime (mizchi/js_bun) - Split out in v0.11.0
• 📦 WebExtensions (mizchi/js_webextensions) - Split out in v0.11.0
• 📦 React / NPM Packages - Maintained at mizchi/npm_typed
• 📦 Cloudflare Workers - Maintained at mizchi/cloudflare.mbt

Goals

• Provide comprehensive JavaScript FFI bindings for MoonBit
• Platform Coverage (split across mizchi/js_* modules)
  • ✅ Browser DOM and Web APIs (mizchi/js_browser)
  • ✅ Node.js (bundled with mizchi/js) / Deno (mizchi/js_deno) / Bun (mizchi/js_bun)
  • ✅ JavaScript built-in objects and Web Standard APIs (mizchi/js)
• Ecosystem
  • 📦 NPM package bindings: mizchi/npm_typed
  • 📦 Cloudflare Workers: mizchi/cloudflare.mbt

Quick Start

Basic FFI Operations

// Create JavaScript objects
let obj = @js.from_entries([
  ("name", @js.any("Alice")),
  ("age", @js.any(30))
])

// Get property
let name = obj["name"]

// Set property
obj["age"] = @js.any(31)

// Call method
let result = obj._call("toString", [])

// Type casting
let age: Int = obj["age"].cast()

LICENSE

MIT