Ts2moonbit Migration

TypeScript → MoonBit Migration

Port a TypeScript module, library, npm package, or Node service to MoonBit, compile it back to JavaScript with moon build, and ship it so existing JS/TS consumers cannot tell the implementation changed. The compiled .js + generated .d.ts must satisfy the same API contract the TypeScript version exposed.

This skill is the playbook that composes three lower-level skills — it does not duplicate them:

• moonbit-js-binding — the mechanics of extern "js", opaque types, Promise bridging, moon.pkg exports. Load it when you write FFI by hand.
• translate-programming-language — the general parity methodology (oracles, fixtures, shadow testing, cutover). Load it for the verification discipline.
• moonbit-practice — MoonBit syntax, tests, moon commands.

What this skill adds on top of those: the mizchi toolkit map, a TypeScript-specific type-classification pass, and the "preserve the JS API contract" build/publish loop that lets you swap the implementation without touching downstream code.

When To Use

Use this skill when all of these hold:

• The source is TypeScript (a library, npm package, Node CLI/server, or Worker).
• The output must remain consumable as JavaScript — same module shape, same exported signatures, ideally the same .d.ts and the same test suite.
• You will build with the MoonBit js backend (moon build), not WASM-for-the-browser-only.

Do not use this skill (reach for the named alternative instead) when:

• You only need to call a few JS APIs from an existing MoonBit project → moonbit-js-binding.
• You are migrating between two non-JS languages, or the target is not MoonBit → translate-programming-language.
• You are bundling MoonBit core + a TS entry for Cloudflare → cloudflare/mbt-worker-bundle (this skill covers the porting, that skill covers the bundling).

The Governing Principle: the contract is the spec

The TypeScript public surface — exported names, parameter/return types, async-ness, error shapes, module format (ESM/CJS) — is the test oracle. Capture it first, never improvise it. Every porting decision is judged by one question: does a consumer importing the built .js still see the same thing?

Concretely, before porting a single function:

1. Inventory the exported symbols and their .d.ts signatures (references/contract-capture.md).
2. Snapshot the existing test suite — it becomes the parity gate, run against the MoonBit-built artifact.
3. Decide the contract level per export: byte-exact (serializers, hashers), structural (objects/JSON), or semantic (a value that round-trips). Most exports are structural.

Architecture: JS-compatible boundary, idiomatic MoonBit core

The contract governs only the exported boundary. Behind it, write the implementation as clean, idiomatic MoonBit — the code you'd be happy to show a MoonBit reviewer, not a transliteration of the TypeScript. Two layers, kept separate (details + verified example in references/boundary-and-core.md):

• Boundary adapter (one thin file per exported surface, gated ["js"]): the only place @core.Any, _get/_set/cast, throw_error, and promisify* appear. It parses JS values into core types, delegates, and marshals results back into the JS shapes the contract demands. It contains no business logic.
• Idiomatic core: rich enum + match, struct, Result/raise, Map, Option, generics. No JS types reach this layer. It is backend-agnostic and tested directly against the Phase 0 fixtures (no Node round-trip).

If Any or _get/throw_error shows up in a core module, the abstraction leaked — push it back out to the adapter. Any is a bootstrapping and boundary tool, never the destination: use it to get the port compiling, then pull the logic down into typed core modules. The boundary signatures are frozen by the contract; the core types are yours to refactor freely once parity holds.

Before You Port: Library Triage

When the thing you're replacing is a library, run two checks before Phase 0 — they decide whether and how to port.

1. Does the library's reason-to-exist survive in MoonBit? Many JS libraries exist to paper over a JS gap that MoonBit doesn't have (ergonomic immutable updates, structural deep-equal, tiny typed utilities). For a MoonBit consumer, the right move is often to not port the library and use the native idiom instead. Porting is justified when existing JS consumers must keep importing the same module — then you reproduce the contract even if MoonBit wouldn't need the library internally.

2. Classify the library — it predicts how much idiomatic core you'll get:

If the library is runtime-mechanics and the consumer could be MoonBit, prefer exposing the native idiom over porting. If it's domain-logic, expect a clean core and proceed to Phase 0.

The mizchi Toolkit Map

Pick the binding layer by surface, not by habit. Full install lines and import paths are in references/toolkit-map.md.

Rules of thumb:

• Reach for a binding before writing FFI. Hand-rolled extern "js" is a last resort for APIs no package covers. When you do write it, follow moonbit-js-binding.
• mizchi/js's Any is a boundary tool, not the destination. Its Any type + zero-cost casts (any(x), Any::cast, property access _get/_set, method _call/_invoke) mirror TypeScript's any and let you get the port compiling. Keep them in the boundary adapter and replace them with typed core code as you go (see the Architecture section).
• mizchi/x is the cross-target backend. If the TS service does process/fs/http/websocket work and you want it to also run on --target native later, port onto mizchi/x (which delegates to moonbitlang/async natively and to JS FFI on the js target) instead of binding node:* directly.

Workflow

Eight phases. Do not skip Phase 0 — porting without the captured contract is how you ship a silent behavior change.

Phase 0 — Capture the contract

Read references/contract-capture.md.

• Enumerate every exported symbol and its type signature (from .d.ts, tsc --declaration, or package.json exports).
• Pin the source runtime; freeze the existing test suite as the oracle. Generate fixtures from the TS implementation for ordinary, boundary, malformed, and error cases — never hand-author expected values.
• Record the module format(s) the package ships (esm, cjs, dual) and the entry points in package.json.

Phase 1 — Project setup

• moon.mod.json: set "preferred-target": "js" so moon check/build/test default to JS.
• moon add the toolkit packages you mapped in Phase 0.
• Lay out src/moon.pkg with link.js (exports + format) — empty exports for now, filled in Phase 6.
• Decide the npm interop shape: a thin package.json whose exports point at the moon build --release output (see references/build-and-publish.md).

Phase 2 — Classify types

Read references/type-mapping.md. This is the TypeScript analog of the OCaml string-vs-Bytes hazard. Classify every field and parameter by meaning before choosing a MoonBit type:

• number → Int/Double only if |x| < 2^53; anything that can exceed it (ids, timestamps-as-int, bitfields) → BigInt/Int64, and check the contract for which the JS side expects.
• string carrying bytes (base64-decoded, binary protocols) → Bytes, not String.
• T | null | undefined unions → do not collapse to T?; split with is_null/is_undefined.
• Object/record literals, discriminated unions, Date, Promise<T>, callbacks — see the reference table.

Phase 3 — Port leaf modules (idiomatic core + thin adapter)

Read references/boundary-and-core.md.

• Port pure/leaf modules first, then shared helpers, then I/O adapters, then orchestration/entry.
• Write the logic as idiomatic MoonBit core (enum/match, struct, Result/raise) with no JS types; keep Any/_get/throw_error/FFI confined to a thin boundary adapter file per exported surface.
• Test the core directly against the Phase 0 fixtures (no Node round-trip needed); test the adapter through Node to confirm the contract.

Phase 4 — Port backend / async I/O

• Map Promise<T> to MoonBit async fn + .wait() (Promise bridging — moonbit-js-binding).
• For process/fs/http/ws/tcp, port onto mizchi/x so the same source runs on native and js. Add moonbitlang/async (for "test") for async test.

Phase 5 — Port npm dependencies

• Replace each npm import with its mizchi/npm_typed binding where one exists.
• For an npm package with no binding: write a minimal extern "js" + #module("pkg") wrapper (named-export rules in moonbit-js-binding), exposing only the surface you actually call. Don't bind the whole library.

Phase 6 — Re-export to satisfy the contract

Read references/build-and-publish.md.

• List the Phase 0 export names in link.js.exports (use "moonbit_name:js_name" to match the original casing/naming).
• Set link.js.format to match what the package shipped (esm/cjs; dual-build if the original was dual).
• moon build --release; diff the generated .d.ts against the Phase 0 .d.ts. Reconcile every difference — a changed signature is a broken contract. Watch the leak-prone shapes: Int64→bigint, enums-with-data, trait objects (see references/type-mapping.md).

Phase 7 — Verify parity and cut over

Read references/parity-verification.md (and translate-programming-language for the full gate discipline).

• Point the original TypeScript test suite at the MoonBit-built .js and run it. Green here is the primary signal.
• For services, shadow/replay real traffic and diff responses, headers, and side effects before switching.
• Canary with a rollback window; keep the TS implementation deployable until the window closes.

Type Mapping (quick reference)

Full table with edge cases in references/type-mapping.md.

Decision Table

Common Pitfalls

1. Porting before capturing the contract. Without the Phase 0 .d.ts + test snapshot you have no parity oracle and will ship silent changes.
2. number → Int reflex. JS number is IEEE-754. Ids, epoch-millis-as-int, and bitmasks overflow Int semantics or lose precision past 2^53. Classify first.
3. Collapsing T | null | undefined into T?. Some(null) is nonsense; the contract distinguishes the two. Split with is_null/is_undefined.
4. Binding node:* directly when you wanted cross-target. If the service should later run native, port onto mizchi/x, not hand-rolled node:fs/node:http FFI.
5. Leaking MoonBit internals in the .d.ts. Passing Map, Result, data-carrying enum, or trait objects across the boundary emits MoonBit's internal runtime shape into the .d.ts. Expose plain structs / opaque #external types / pairs of constructor functions.
6. Wrong link.js.format. Shipping ESM where the package was CJS (or vice-versa) breaks every consumer even if signatures match. Match Phase 0; dual-build if the original was dual.
7. Exporting a raw async fn. A sync JS caller can't await a bare MoonBit async fn. Wrap the internal async logic with @core.promisify* (or from_async) so the export returns @core.Promise[T] and JS receives a real Promise. Note the generated .d.ts types it as any, not Promise<T>.
8. Binding the whole npm library. Bind only the surface you call. Over-binding wastes effort and bloats output.
9. Trusting unit parity alone. Run the original TS suite against the built artifact and shadow real traffic before cutover (translate-programming-language gates).

Verified Against

The build/export/FFI workflow and the mizchi/js Any API in this skill were verified end-to-end with moon 0.1.20260522 / moonc v0.9.3 and mizchi/js 0.12.1 (round-tripping objects and Promises through Node). Package boundaries and the Any method names (_get/_set/_call/cast) shift across releases — re-check against the resolved version in your moon.mod.json if a signature mismatches.

References

@references/contract-capture.md @references/toolkit-map.md @references/boundary-and-core.md @references/type-mapping.md @references/build-and-publish.md @references/parity-verification.md