ts2moonbit-migration

name

ts2moonbit-migration

description

Migrate a TypeScript codebase to MoonBit on the `js` target while keeping the same JavaScript API contract, using mizchi/js (JS/Web/Node bindings), mizchi/x (cross-target async backend: process/fs/http/ws), and mizchi/npm_typed (npm bindings). Use when porting a TS library, Node service, npm package, or Cloudflare Worker to MoonBit and the existing JS/TS consumers, `.d.ts`, and tests must keep working unchanged.

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:

Class	What it is	Port shape	Example (verified)
Domain-logic	parsing, algorithms, data transforms, validation	rich idiomatic core (enum/match/struct) + thin boundary — the Architecture pattern shines	semver: enum Ident / struct SemVer core + match-based precedence; 198/198 parity vs semver@7.8.1
Runtime-mechanics	Proxy / getter-setter / prototype tricks, reflection, JS-engine behaviors	little-to-no idiomatic core; stays FFI-heavy in extern "js". Consider whether to port at all	immer: Proxy copy-on-write in FFI; 12/12 contract parity (incl. structural sharing) vs immer@10 — but no idiomatic core, and MoonBit needs no immer ({ ..base, x: v } is native)

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.

Source TypeScript uses…	MoonBit package	moon add
JS built-ins, Web Standard APIs, node:* built-ins	mizchi/js	moon add mizchi/js
DOM, canvas, IndexedDB, storage, service workers	mizchi/js_browser	moon add mizchi/js_browser
Deno / Bun runtime APIs	mizchi/js_deno, mizchi/js_bun	per runtime
npm packages (React, Hono, Zod, AI SDK, Drizzle…)	mizchi/npm_typed	moon add mizchi/npm_typed
Node backend I/O that must run on both native and js (spawn, fs, http server, ws, tcp/tls)	mizchi/x	moon add mizchi/x
Cloudflare Workers runtime	mizchi/cloudflare	moon add mizchi/cloudflare

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.

TypeScript	MoonBit (with mizchi/js)	Watch out for
boolean	Bool	—
number (int, < 2^53)	Int / UInt	beyond 2^53 → BigInt
number (float)	Double	—
bigint	BigInt / Int64	Int64 surfaces as bigint in .d.ts
string (text)	String	UTF-16 length, not bytes
string (binary)	Bytes	classify by meaning
Uint8Array	Bytes	no-copy
T[]	Array[T]	—
any / unknown	Any (mizchi/js)	cast with Any::cast
object / record	struct	don't pass Map/trait objects across the boundary
discriminated union	enum	data-carrying enums are awkward from JS; prefer constructor fns
T | undefined	T? via is_undefined	—
T | null	Nullable[T] wrapper	null ≠ undefined
Promise<T>	async fn + .wait(); export via @core.promisify*	exported async surfaces as any in .d.ts, not Promise<T>
(…) => R callback	FuncRef/closure	—
Date	mizchi/js Date binding	—

Decision Table

Situation	Do this
Need to call a JS/Web/Node built-in	mizchi/js binding; FFI only if missing
Need DOM / browser API	mizchi/js_browser
Need an npm package	mizchi/npm_typed; else minimal #module() wrapper
Backend I/O that should also run native	mizchi/x (not raw node:*)
Value can exceed 2^53	BigInt/Int64, confirm against contract
string is actually bytes	Bytes
Union with both null and undefined	split, don't use T? alone
Exported function is async	return @core.Promise[T] via @core.promisify*/from_async; JS receives a real Promise (.d.ts type is any)
Original package was dual ESM/CJS	dual-build; match package.json exports
.d.ts signature changed after build	contract break — fix the MoonBit signature, don't patch the .d.ts
Unsure a behavior matches	run the original TS test against the built .js

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