Skip to main content

MEP-72 research bundle

This bundle is the informative companion to MEP-72. It documents the design space the TypeScript / JavaScript bridge sits in: prior art, the choices considered and rejected, the trade-offs accepted, and the open risks. The bundle is meant to be read alongside the spec, not in place of it.

Notes​

NoteSubject
01. Language surfaceThe import ts "<pkg>@<semver>" as <alias> import shape, the mochi.toml [ts-dependencies] + [ts] tables, the dual-registry selector (npm: and jsr: prefixes), the CLI surface (mochi pkg add ts, mochi pkg publish --to=npm + --to=jsr + --to=both), and the per-import alias semantics.
02. Design philosophyWhy a bidirectional bridge, why the TypeScript compiler API over a hand-written .d.ts parser, why NO synthesised wrapper package on the consume side (the key structural simplification), why no async runtime singleton is needed for JS, why dual-registry support ships at once, why Sigstore Trusted Publishing is mandatory on both registries.
03. Prior-art bridgesdts-gen, ts-morph, api-extractor, dts-bundle-generator, swc, esbuild, Bun's bundler, Deno's deno_npm resolver, tsd, expect-type, tsc --build. What each gets right, what each requires the user to write, and what MEP-72 borrows.
04. TypeScript compiler API + .d.ts ingestThe ts.createProgram flow, the ts.TypeChecker discriminator tree, the stability story across TS 3-5 majors, why no nightly toolchain is needed, the Node-side helper binary shape, the JSON ApiSurface schema.
05. Type mapping tableThe complete closed translation table, the refusal cases, the generic monomorphisation rule, the Promise<T> and AsyncIterable<T> mappings, the `null
06. npm + JSR publish flowThe npm registry's npm publish --provenance --access=public flow, the JSR registry's deno publish --token-source=github-actions flow, the dual-publish from one workflow run, the per-registry metadata requirements, the publish-side gate against verdaccio-mock + JSR-mock.
07. Sigstore on npm + JSRThe npm Sigstore attestation format, the JSR Sigstore attestation format, the OIDC token exchange model, the actions/attest-build-provenance@v2 integration, the consumer-side verification path.
08. Promise / async bridgeThe host JS event loop, why no runtime singleton is needed (unlike Rust tokio or Go cgo handle), the Promise<T> ↔ Mochi async fun translation, the AsyncIterable<T> ↔ Mochi stream<T> translation, the microtask scheduling cost.
09. ESM vs CJS interopThe CJS vs ESM module shape distinction, the exports map conditional resolution, the dual-package hazard, the Node 22 / Deno 2 / Bun 1.1 / browser per-runtime interop semantics, the browser bundle path's CJS rejection.
10. Runtime target matrixNode 22 LTS, Deno 2, Bun 1.1, browser ES2024, edge (Cloudflare Workers + Vercel Edge + Deno Deploy). What each runtime supports, what API surface differs, what the bridge promises per target.
11. Browser bundle surfaceThe bun build and esbuild paths from MEP-52 Phase 17, the tree-shaking rules for consumed packages, the node: import rejection on browser, the WebAssembly capability flag.
12. Risks and alternativesThe risk register (compiler-API RAM footprint, .d.ts quality variance, conditional-type resolution, CJS-only browser refusal, JSR attestation gap, dual-package hazard) and the rejected alternatives (hand-written .d.ts parser, DT-as-primary, tsserver protocol, wrapper-package synthesis on consume side, long-lived NPM_TOKEN).

Cross-references​

  • MEP-72 spec — the normative document.
  • MEP-52 — the TypeScript transpiler this bridge builds on.
  • MEP-57 — the source-level package system whose manifest and lockfile the bridge extends.
  • MEP-73 — the sister Rust bridge whose spec template MEP-72 mirrors.
  • MEP-74 — the sister Go bridge whose spec template MEP-72 mirrors.
  • Implementation tracking — the per-phase delivery status.