#mizchi/js

#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

See src/npm/README.md for full npm package documentation

#Limited Support APIs

#Project Status

• ✅ React SPA - Full support with SSR/CSR
• ✅ Node.js Core APIs - fs, path, process, child_process, etc.
• ✅ Cloudflare Workers - KV, D1, R2, Durable Objects
• ✅ Deno Runtime - File system, permissions, testing
• ✅ DOM APIs - Full browser DOM manipulation
• 🤖 AI-Generated Bindings - Many APIs generated from TypeScript definitions

#Goals

• Provide comprehensive JavaScript bindings for MoonBit
• Platform Coverage
  • ✅ Browser + React for frontend development
  • ✅ Node.js/Deno support to replace TypeScript
  • ✅ Cloudflare Workers for edge computing
  • ✅ MCP server/client support

#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

// Create objects
let obj = @core.Object::new()
obj["name"] = "Alice" |> @js.any
obj["agen"] = 25 |> @js.any

// Get properties
let name: String = obj["name"].cast()  // Returns @js.Any
let age: Int = obj["age"].cast()  // Manual casting

// Call methods
let has_name: Bool = obj._call("hasOwnProperty", ["name"]).cast()

// Create from map
let obj2 = @js.from_map({ "x": @core.any(10), "y": @core.any(20) })

#Type Casting

// Using cast() method (recommended)
let value: Int = js_value.cast()
let str: String = js_value.cast()

// Using identity() for low-level FFI
let value: Int = @js.identity(js_value)

// Optional types
let nullable: Int? = @js.identity_option(js_value)

#Promises and Async

// Create and use promises
let promise = @js.Promise::resolve(42)
promise.then_(fn(value) {
  @console.log(value)
})

// Async/await
async fn example() -> Int {
  let promise = @js.Promise::resolve(42)
  let value = promise.wait()
  value
}

// Run async code
@js.run_async(async fn() {
  let value = some_promise.wait()
  @console.log(value)
})

#Async Helpers

// Sleep
async fn delayed() -> Unit {
  @js.sleep(1000)  // Sleep for 1 second
  @console.log("Delayed!")
}

// Promisify callbacks
let async_fn = async fn(x: Int) -> String {
  @js.sleep(100)
  x.to_string()
}
let promise_fn = @js.promisify1(async_fn)
let promise = promise_fn(42)  // Returns Promise[String]

#Arrays

// Create arrays
let arr = @js.JsArray::new()
arr.push(1)
arr.push(2)
arr.push(3)

// Array operations
let length = arr.length()
let first = arr._get(0)
arr.set(1, 42)

// From MoonBit Array
let mbt_arr = [1, 2, 3]
let js_arr = @js.JsArray::from_array(mbt_arr)

#Error Handling

// Create errors
let err = @js.Error::new("Something went wrong")

// Throw errors (use in FFI functions marked with `raise`)
fn example() -> Int raise {
  fail("Error message")
}

// Catch errors in async
async fn safe_operation() -> Unit {
  try {
    let result = risky_operation().wait()
    @console.log(result)
  } catch {
    e => @console.error("Error: " + e.to_string())
  }
}

#JSON Operations

// Parse JSON
let json_str = "{\"name\":\"Alice\",\"age\":30}"
let obj = @js.JSON::parse(json_str)

// Stringify
let obj = @js.from_map({ "name": @core.any("Alice"), "age": @core.any(30) })
let json_str = @js.JSON::stringify(obj)

// With formatting
let pretty = @js.JSON::stringify_with_indent(obj, 2)

#Nullish Handling

// Nullish[T] handles both null and undefined
let nullish: @js.Nullish[Int] = @js.null()

match nullish.to_option() {
  Some(value) => @console.log(value)
  None => @console.log("null or undefined")
}

// Nullable[T] only handles null
let nullable: @js.Nullable[Int] = @js.Nullable::null()

#Iterators

// JavaScript iterator
let iter = js_array.values()
loop {
  let next = iter.next()
  if next.done {
    break
  }
  @console.log(next.value)
}

// Async iterator
async fn iterate_async(iter: @js.AsyncIterator) -> Unit {
  loop {
    let next = iter.next().wait()
    if next.done {
      break
    }
    @console.log(next.value)
  }
}

#Understanding Core FFI Types

#@core.Any - The Universal JavaScript Type

// @core.Any can hold any JavaScript value
let num : @core.Any = @core.any(42)        // number
let str : @core.Any = @core.any("hello")   // string
let obj : @core.Any = @core.Object::new()  // object

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

// Convert MoonBit values to JavaScript
let js_int = @core.any(42)           // Int → @core.Any
let js_str = @core.any("hello")      // String → @core.Any
let js_bool = @core.any(true)        // Bool → @core.Any
let js_arr = @core.any([1, 2, 3])    // Array → @core.Any

#@js.identity() - Unsafe Type Casting

// Cast @core.Any to specific types (unsafe!)
let js_value : @core.Any = obj._get("count")
let count : Int = @js.identity(js_value)

// Common pattern: inline casting
let name : String = @js.identity(obj._get("name"))

let count : Int = obj._get("count").cast()

#JsImpl Trait - Types That Can Interop with JavaScript

// These types implement JsImpl:
// - @core.Any, @js.Object, @js.JsArray, @js.Promise[T], etc.
// - MoonBit primitives: String, Int, Double, Bool, etc.
// - Array[T] where T : JsImpl

// JsImpl provides these methods:
trait JsImpl {
  as_any(Self) -> Any           // Convert to @core.Any
  get(Self, key) -> Any         // JS: self[key]
  set(Self, key, val) -> Unit   // JS: self[key] = val
  call(Self, key, args) -> Any  // JS: self[key](...args)
  // ... and more
}

#Common Patterns in Test Code

#Pattern 1: Getting typed values from JavaScript objects

// JavaScript: const name = obj.name
let name : String = @js.identity(obj._get("name"))

// Alternative using cast()
let age : Int = obj._get("age").cast()

#Pattern 2: Creating JavaScript objects with MoonBit values

// Using from_map (recommended)
let obj = @js.from_map({
  "name": @core.any("Alice"),
  "age": @core.any(30)
})

// Manual construction
let obj = @core.Object::new()
obj.set("name", "Alice")  // String implements JsImpl
obj.set("age", 30)        // Int implements JsImpl

#Pattern 3: Handling nullable/optional values

// JavaScript null/undefined → MoonBit Option
let maybe_value : Int? = @js.identity_option(obj._get("optional_field"))

// MoonBit Option → JavaScript null
let js_value = @js.from_option(Some(42))  // → 42
let js_null = @js.from_option(None)       // → null

#Pattern 4: Calling JavaScript methods

// No arguments: obj.method()
let result = obj.call0("method")

// With arguments: obj.method(arg1, arg2)
let result = obj._call("method", [arg1, arg2])

// With type casting
let str_result : String = obj.call0("toString").cast()

#Summary Table

#Advanced Patterns

#Escape Hatch Pattern

// Define external FFI function
extern "js" fn ffi_my_custom_api(arg: @core.Any) -> @core.Any =
  #|arg => {
  #|  // JavaScript code here
  #|  return arg.customMethod();
  #|}

// Wrap it in a type-safe function
pub fn my_custom_api(value: String) -> String {
  let result = ffi_my_custom_api(value)
  result.cast()
}

#Type Reference

#Core Types

• @core.Any - Universal JavaScript value type (was @js.Js before v0.5.0)
• @js.Object - JavaScript object
• @js.JsArray - JavaScript array
• @js.Promise[T] - JavaScript Promise
• @js.Function - JavaScript function
• @js.Error - JavaScript Error

#Nullish Types

• @js.Nullish[T] - Handles both null and undefined (converts to Option[T])
• @js.Nullable[T] - Handles only null
• @js.Undefinedable[T] - Handles only undefined

#Binary Data

#Related Packages

• mizchi/js/web/* - Web Standard APIs
• mizchi/js/browser/* - Browser DOM APIs
• mizchi/js/node/* - Node.js runtime APIs
• mizchi/js/npm/* - NPM package bindings

#Migration from v0.4.0

#Breaking Changes in v0.5.0

// Type rename: @js.Js → @core.Any
let value: @core.Any = obj._get("key")

// Method rename: to_js() → as_any()
let any = obj.as_any()

// Function rename: @js.js() → @core.any()
let converted = @core.any(value)

// Casting: unsafe_cast() → identity() or cast()
let typed: Int = value.cast()

#Contributing