#mizchi/js

#Version Requirements

moon 0.1.20251209 (8d6e473 2025-12-09)
moonc v0.6.34+7262739a4-nightly (2025-12-09)
moonrun 0.1.20251209 (8d6e473 2025-12-09)

#Breaking Change in v0.10.0

#Installation

$ moon add mizchi/js

{
  "import": ["mizchi/js/core", "mizchi/js"]
}

⚠️ Future Plans: Platform-specific APIs (Node.js, Browser, Deno) will be split into separate packages in the future. The core mizchi/js package will focus on JavaScript built-ins and Web Standard APIs.

Note: Cloudflare Workers bindings have been moved to a separate package: @mizchi/cloudflare-mbt

#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

#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

• 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

• 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

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

• 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

• 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

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

• 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

#Web Standard APIs

See mizchi/js/web for detailed Web APIs documentation

#Runtime-Specific APIs

#NPM Package Bindings

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

#Limited Support APIs

#Project Status

• ✅ Node.js Core APIs - fs, path, process, child_process, etc.
• ✅ Deno Runtime - File system, permissions, testing
• ✅ Bun Runtime - Process, hashing, glob, file operations
• ✅ DOM APIs - Full browser DOM manipulation
• ✅ Web Standard APIs - fetch, URL, Streams, Crypto, WebSocket
• 📦 React/NPM Packages - Moved to mizchi/npm_typed
• 📦 Cloudflare Workers - Moved to mizchi/cloudflare.mbt

#Goals

• Provide comprehensive JavaScript FFI bindings for MoonBit
• Platform Coverage
  • ✅ Browser DOM and Web APIs
  • ✅ Node.js/Deno/Bun runtime support
  • ✅ JavaScript built-in objects and Web Standard APIs
• 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

#mizchi/js - Core Package

• Core FFI operations (_get, _set, _call, cast, etc.)
• JavaScript built-in types (Object, Array, Promise, Function, Error, etc.)
• Async helpers (run_async, suspend, sleep, promisify)
• Type conversion utilities

#Installation

moon add mizchi/js

{
  "import": ["mizchi/js"]
}

#Basic Usage

#Core FFI Operations

///|
test {
  // Create objects
  let obj = @core.new_object()
  obj["name"] = @core.any("Alice")
  obj["age"] = @core.any(25)

  // Get properties
  let name : String = obj["name"].cast()
  let age : Int = obj["age"].cast()
  inspect(name, content="Alice")
  inspect(age, content="25")

  // Call methods
  let has_name : Bool = obj._call("hasOwnProperty", [@core.any("name")]).cast()
  inspect(has_name, content="true")

  // Create from entries
  let obj2 = @core.from_entries([("x", @core.any(10)), ("y", @core.any(20))])
  let x : Int = obj2["x"].cast()
  inspect(x, content="10")
}

#Type Casting

///|
test {
  // Using cast() method (recommended)
  let js_value : @core.Any = @core.any(42)
  let value : Int = js_value.cast()
  inspect(value, content="42")

  // Using identity() for low-level FFI
  let value2 : Int = @core.identity(js_value)
  inspect(value2, content="42")

  // Optional types
  let nullable : Int? = @core.identity_option(@core.null())
  inspect(nullable, content="None")
  let some_value : Int? = @core.identity_option(@core.any(100))
  inspect(some_value, content="Some(100)")
}

#JSON Operations

///|
test {
  // Parse JSON
  let json_str = "{\"name\":\"Alice\",\"age\":30}"
  let obj = @core.json_parse(json_str)
  let name : String = obj["name"].cast()
  inspect(name, content="Alice")

  // Stringify
  let obj2 = @core.from_entries([("x", @core.any(1))])
  let json_str2 = @core.json_stringify(obj2)
  inspect(json_str2, content="{\"x\":1}")
}

#Nullish Handling

///|
test {
  // Check nullish values
  let null_val = @core.null()
  let undefined_val = @core.undefined()
  inspect(@core.is_nullish(null_val), content="true")
  inspect(@core.is_nullish(undefined_val), content="true")
  inspect(@core.is_nullish(@core.any(42)), content="false")

  // identity_option for safe conversion
  let maybe_null : Int? = @core.identity_option(null_val)
  inspect(maybe_null, content="None")

  // from_option for MoonBit Option -> JS
  let js_some = @core.from_option(Some(42))
  let js_none = @core.from_option((None : Int?))
  inspect(@core.is_nullish(js_some), content="false")
  inspect(@core.is_nullish(js_none), content="true")
}

#Understanding Core FFI Types

#@core.Any - The Universal JavaScript Type

///|
test {
  // @core.Any can hold any JavaScript value
  let num : @core.Any = @core.any(42)
  let str : @core.Any = @core.any("hello")
  let obj : @core.Any = @core.new_object()
  inspect(@core.typeof_(num), content="number")
  inspect(@core.typeof_(str), content="string")
  inspect(@core.typeof_(obj), content="object")
}

#@core.any() - Converting MoonBit Values to JavaScript

///|
test {
  // Convert MoonBit values to JavaScript
  let js_int = @core.any(42)
  let js_str = @core.any("hello")
  let js_bool = @core.any(true)
  let int_val : Int = js_int.cast()
  let str_val : String = js_str.cast()
  let bool_val : Bool = js_bool.cast()
  inspect(int_val, content="42")
  inspect(str_val, content="hello")
  inspect(bool_val, content="true")
}

#Common Patterns

#Pattern 1: Getting typed values from JavaScript objects

///|
test {
  let obj = @core.from_entries([
    ("name", @core.any("Alice")),
    ("age", @core.any(30)),
  ])

  // Using cast()
  let name : String = obj["name"].cast()
  let age : Int = obj["age"].cast()
  inspect(name, content="Alice")
  inspect(age, content="30")
}

#Pattern 2: Handling nullable/optional values

///|
test {
  let obj = @core.from_entries([("name", @core.any("Alice"))])

  // Existing field
  let name : String? = @core.identity_option(obj["name"])
  inspect(
    name,
    content=(
      #|Some("Alice")
    ),
  )

  // Missing field returns undefined
  let missing : String? = @core.identity_option(obj["missing"])
  inspect(missing, content="None")
}

#Pattern 3: Calling JavaScript methods

///|
test {
  let arr = @core.any([1, 2, 3])

  // Call method with arguments
  let joined : String = arr._call("join", [@core.any("-")]).cast()
  inspect(joined, content="1-2-3")

  // Get property
  let length : Int = arr["length"].cast()
  inspect(length, content="3")
}

#TypeOf[T] - JavaScript Constructor Type

///|
extern "js" fn get_array_constructor() -> @core.TypeOf[Array[Int]] =
  #| () => Array

///|
test "TypeOf usage" {
  let arr_ctor = get_array_constructor()

  // Create instance using constructor
  let arr : Array[Int] = @core.new_instance(arr_ctor, [])
  inspect(arr.length(), content="0")

  // instanceof check
  let js_arr = @core.any([1, 2, 3])
  inspect(arr_ctor.is_instanceof(js_arr), content="true")
  inspect(arr_ctor.is_instanceof(@core.any("not array")), content="false")
}

#Summary Table

#Related Packages

• mizchi/js/web/* - Web Standard APIs
• mizchi/js/browser/* - Browser DOM APIs
• mizchi/js/node/* - Node.js runtime APIs
• mizchi/npm_typed - NPM package bindings (React, Hono, AI SDK, etc.)