tswasm 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,326 @@
+# tswasm
+
+Alpha package for running the TypeScript Go compiler from JavaScript runtimes
+through WebAssembly.
+
+This repository keeps `microsoft/typescript-go` as a git subtree, then builds a
+small wasm command from inside that subtree. Building from inside the upstream Go
+module lets the command legally import `typescript-go/internal/...` without
+patching upstream compiler packages.
+
+The current API compiles one in-memory TypeScript file, `/input.ts` by default,
+with modern ECMAScript lib definitions and returns diagnostics plus emitted
+JavaScript.
+
+`tswasm` is published as an alpha. The package is useful for experiments,
+browser-side tools, Cloudflare Worker prototypes, and performance comparisons,
+but the API is intentionally narrow while `typescript-go` is still moving.
+
+## Install
+
+```bash
+npm install tswasm
+```
+
+## Usage
+
+When the JavaScript file and `tswasm.wasm` asset are served from the same
+package location, `createCompiler()` loads the packaged wasm automatically:
+
+```ts
+import { createCompiler } from 'tswasm'
+
+const ts = await createCompiler()
+const result = ts.compile('const x: number = 123')
+
+console.log(result.success) // true
+
+ts.compile('const s: string = 42') // { success: false, diagnostics: [{..., message: "Type 'number' is not assignable to type 'string'.", ...}] }
+```
+
+For bundlers and worker runtimes, pass the wasm module or URL explicitly:
+
+```ts
+import { createCompiler } from 'tswasm'
+import wasm from 'tswasm/tswasm.wasm'
+
+let tsPromise: ReturnType<typeof createCompiler>
+
+function getCompiler() {
+  tsPromise ||= createCompiler({ wasm })
+  return tsPromise
+}
+
+export default {
+  async fetch(request: Request) {
+    const code = new URL(request.url).searchParams.get('code') || 'const x = 1'
+    const ts = await getCompiler()
+    return Response.json(ts.compile(code))
+  },
+}
+```
+
+If the runtime serves wasm as a normal static file, compile it yourself and pass
+the `WebAssembly.Module`:
+
+```ts
+import { createCompiler } from 'tswasm'
+
+const bytes = await fetch('/tswasm.wasm').then(response => response.arrayBuffer())
+const wasm = await WebAssembly.compile(bytes)
+const ts = await createCompiler({ wasm })
+```
+
+## Current Limits
+
+- Compiles one in-memory input file per call. Pass `fileName` when diagnostics
+  should use a path other than `/input.ts`.
+- Uses bundled `lib.es2024.d.ts` files, `strict: true`, `target: ES2024`, and
+  `module: ESNext`.
+- Does not load a `tsconfig.json`, file graph, package dependencies, or custom
+  declaration files yet.
+- Has no disposal API. Reusing one `createCompiler()` result is cheaper than
+  repeatedly creating new runtimes.
+- Ships a large wasm payload: about 29 MiB raw and about 6.8 MiB compressed in
+  the current package.
+
+## Why
+
+If a compiler needs to run in a browser, Cloudflare Worker, or another
+JavaScript runtime where native subprocesses are not available, the practical
+implementation choices are JavaScript or WebAssembly. Native `tsgo` is the
+obvious choice when native code is allowed, but it does not cover those
+environments.
+
+That matters because TypeScript is moving toward the native compiler and
+language service for TypeScript 7.0. The TypeScript team describes the native
+port as a way to improve raw performance, memory use, and parallelism:
+<https://devblogs.microsoft.com/typescript/progress-on-typescript-7-december-2025/>.
+TypeScript 6.0 is also explicitly a transition release for TypeScript 7.0:
+<https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html>.
+Microsoft says the existing JavaScript/TypeScript implementation will be
+maintained for the foreseeable future, but that the eventual intent is to
+develop only the native codebase:
+<https://github.com/microsoft/typescript-go/discussions/454>.
+
+`tswasm` explores the practical middle ground: keep the supported native
+compiler path available in wasm-capable environments, and measure whether that
+path is also faster than the JavaScript compiler APIs those environments can
+use today.
+
+## Size
+
+This repo includes a size report for the current package contents:
+
+```bash
+pnpm size
+```
+
+The script builds `tswasm`, runs `npm pack --dry-run --json`, rejects
+benchmark-only native binaries if they would be packed, and prints raw,
+gzip, and brotli sizes for the runtime assets. The local JS compiler reference
+rows are direct local package/file sizes, not full browser bundle graphs.
+
+Representative local run on 2026-06-19:
+
+### Packed Package
+
+| Package | packed tarball | unpacked install | files |
+|---|---:|---:|---:|
+| tswasm@0.1.0-alpha.0 | 6.84 MiB | 29.05 MiB | 10 |
+
+### Runtime Assets
+
+| Asset | raw | gzip | brotli |
+|---|---:|---:|---:|
+| API JS | 4.17 KiB | 1.45 KiB | 1.25 KiB |
+| Types | 1.19 KiB | 490 B | 397 B |
+| Go wasm runtime JS | 16.93 KiB | 4.40 KiB | 3.79 KiB |
+| TypeScript Go wasm | 28.96 MiB | 6.81 MiB | 5.15 MiB |
+| Runtime payload total | 28.98 MiB | 6.82 MiB | 5.16 MiB |
+
+### Local JS Compiler References
+
+| Reference | raw/install | gzip | brotli |
+|---|---:|---:|---:|
+| TypeScript JS compiler file | 8.69 MiB | 1.56 MiB | 1.10 MiB |
+| TypeScript JS package | 22.53 MiB | - | - |
+| ts-morph bundled JS | 932.10 KiB | 127.57 KiB | 97.12 KiB |
+| ts-morph package | 1.41 MiB | - | - |
+
+## Performance
+
+This repo includes a local benchmark runner for the current one-file compiler
+API:
+
+```bash
+pnpm bench
+pnpm bench:quick
+pnpm bench:profile
+pnpm exec tsx bench/compile.bench.ts --filter=warm
+pnpm exec tsx bench/compile.bench.ts --skip-native --json=tasks/bench-results.ignoreme.json
+```
+
+`pnpm bench` builds `tswasm`, builds a local native `tsgo` CLI from
+`typescript-go/`, and then prints Markdown tables. `bench:quick` uses shorter
+sample windows for iteration while changing benchmark code. `bench:profile`
+adds internal diagnostic rows for the wasm path and a spawn-only `tsgo` row.
+
+The benchmark has two source cases:
+
+- `simple snippet`: the existing compile-test async function using `Map`,
+  `Array.from`, and `Promise.all`.
+- `type-heavy snippet`: a compact source using recursive conditional types,
+  mapped type key remapping, template literal types, and generic call-site
+  inference.
+
+The rows are grouped by comparison category. The first category is the main one:
+portable full compile, where every row typechecks and emits and can run in the
+same wasm-capable environments as `tswasm`.
+
+- `tswasm warm compile`: one shared `createCompiler()` result for the whole
+  process; timed work is only `ts.compile(code)`.
+- `tswasm cold createCompiler+compile`: timed work includes `createCompiler()`
+  and one compile. Repeated samples currently accumulate Go wasm runtimes
+  because the public API has no disposal hook.
+- `TypeScript JS full program (in-memory)`: recreates an in-memory
+  `ts.createProgram`, collects pre-emit diagnostics, and emits.
+- `ts-morph full program (in-memory)`: creates an in-memory ts-morph project,
+  collects pre-emit diagnostics, and emits to memory.
+- `TypeScript JS transpileModule (emit only)`: intentionally favorable baseline
+  for the classic JS compiler. It does not typecheck.
+- `tsgo native CLI (process+files)`: runs the local native TypeScript CLI in a
+  subprocess against a temp project. This includes process startup and file
+  reads/writes, so it is a native-Go curiosity rather than a portable
+  wasm-environment comparison.
+
+The comparison framing follows:
+
+- Microsoft's native TypeScript announcement measured project-level `tsc` runs
+  and reported roughly order-of-magnitude speedups for native TypeScript:
+  <https://devblogs.microsoft.com/typescript/typescript-native-port/>
+- The TypeScript Compiler API docs distinguish full `createProgram` compilation
+  from `transpileModule` emit-only transforms:
+  <https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API>
+- ts-morph's performance docs call out the wrapper costs around program resets,
+  node tracking, and batching:
+  <https://ts-morph.com/manipulation/performance>
+
+Representative local run on 2026-06-18:
+
+- Runtime: node v26.0.0 darwin/arm64
+- CPU: Apple M4 Max
+- TypeScript JS: 5.9.3
+- ts-morph: 28.0.0
+- tsgo native: Version 7.0.0-dev
+
+Lower latency is better. Tinybench rows use a time-driven loop; startup-heavy
+rows use fixed samples.
+
+### Simple Snippet: Portable Full Compile
+
+These rows typecheck and emit, and can run in the same wasm-capable environments
+as `tswasm`.
+
+| Benchmark | mean ms | median ms | samples | vs fastest | notes |
+|---|---:|---:|---:|---:|---|
+| tswasm warm compile | 28.90 | 28.11 | 18 | fastest | rme 4.63% |
+| tswasm cold createCompiler+compile | 60.51 | 60.86 | 5 | 2.09x slower | fixed samples |
+| ts-morph full program (in-memory) | 75.53 | 74.58 | 10 | 2.61x slower | rme 3.99% |
+| TypeScript JS full program (in-memory) | 163.2 | 162.2 | 10 | 5.65x slower | rme 3.26% |
+
+### Simple Snippet: Emit-Only Baseline
+
+This classic TypeScript JS row emits without typechecking. It is useful, but not
+apples-to-apples. `tswasm` warm compile and TypeScript JS full program are
+repeated here as reference points.
+
+| Benchmark | mean ms | median ms | samples | vs fastest | notes |
+|---|---:|---:|---:|---:|---|
+| TypeScript JS transpileModule (emit only) | 0.2819 | 0.1908 | 1774 | fastest | rme 7.55% |
+| tswasm warm compile | 28.90 | 28.11 | 18 | 102.52x slower | rme 4.63% |
+| TypeScript JS full program (in-memory) | 163.2 | 162.2 | 10 | 579.0x slower | rme 3.26% |
+
+### Simple Snippet: Native Go Curiosity
+
+These rows require native Go or a native helper process. If native Go is
+available, use it; these are not portable wasm-environment comparisons. The
+`tswasm` rows are repeated here as reference points.
+
+| Benchmark | mean ms | median ms | samples | vs fastest | notes |
+|---|---:|---:|---:|---:|---|
+| tsgo native CLI (process+files) | 27.73 | 26.91 | 5 | fastest | fixed samples |
+| tswasm warm compile | 28.90 | 28.11 | 18 | 1.04x slower | rme 4.63% |
+| tswasm cold createCompiler+compile | 60.51 | 60.86 | 5 | 2.18x slower | fixed samples |
+
+### Type-Heavy Snippet: Portable Full Compile
+
+These rows typecheck and emit, and can run in the same wasm-capable environments
+as `tswasm`.
+
+| Benchmark | mean ms | median ms | samples | vs fastest | notes |
+|---|---:|---:|---:|---:|---|
+| tswasm warm compile | 24.21 | 23.53 | 21 | fastest | rme 6.99% |
+| tswasm cold createCompiler+compile | 56.63 | 56.72 | 5 | 2.34x slower | fixed samples |
+| ts-morph full program (in-memory) | 68.35 | 66.82 | 10 | 2.82x slower | rme 3.97% |
+| TypeScript JS full program (in-memory) | 161.9 | 157.8 | 10 | 6.69x slower | rme 4.59% |
+
+### Type-Heavy Snippet: Emit-Only Baseline
+
+This classic TypeScript JS row emits without typechecking. It is useful, but not
+apples-to-apples. `tswasm` warm compile and TypeScript JS full program are
+repeated here as reference points.
+
+| Benchmark | mean ms | median ms | samples | vs fastest | notes |
+|---|---:|---:|---:|---:|---|
+| TypeScript JS transpileModule (emit only) | 0.4030 | 0.3025 | 1241 | fastest | rme 5.93% |
+| tswasm warm compile | 24.21 | 23.53 | 21 | 60.07x slower | rme 6.99% |
+| TypeScript JS full program (in-memory) | 161.9 | 157.8 | 10 | 401.7x slower | rme 4.59% |
+
+### Type-Heavy Snippet: Native Go Curiosity
+
+These rows require native Go or a native helper process. If native Go is
+available, use it; these are not portable wasm-environment comparisons. The
+`tswasm` rows are repeated here as reference points.
+
+| Benchmark | mean ms | median ms | samples | vs fastest | notes |
+|---|---:|---:|---:|---:|---|
+| tswasm warm compile | 24.21 | 23.53 | 21 | fastest | rme 6.99% |
+| tsgo native CLI (process+files) | 28.64 | 27.41 | 5 | 1.18x slower | fixed samples |
+| tswasm cold createCompiler+compile | 56.63 | 56.72 | 5 | 2.34x slower | fixed samples |
+
+## Upstream Layout
+
+- `typescript-go/` is a git subtree of `microsoft/typescript-go`.
+- `go/tswasm-wasm/` is this package's wasm command source.
+- `scripts/build-wasm.ts` overlays the command into
+  `typescript-go/cmd/tswasm-wasm`, copies the needed lib definition files, and
+  builds `dist/tswasm.wasm`.
+
+That keeps the public package separate from upstream while still allowing the Go
+entrypoint to reach tsgo's current internal compiler APIs.
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+pnpm test
+```
+
+## Release Checks
+
+```bash
+pnpm run release:check
+```
+
+The release check builds the wasm and JavaScript output, runs the default Vitest
+suite, prints the package size report, and runs `npm pack --dry-run --json`.
+That default suite includes the Node and Miniflare Worker tests. Run these
+additional environment checks before claiming browser or Expo web support for a
+release:
+
+```bash
+pnpm test:browser
+pnpm test:expo
+```

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,80 @@
+# Third-party notices
+
+This package redistributes generated runtime artifacts from the projects listed
+below. The package source is licensed under Apache-2.0; these notices describe
+the redistributed third-party material.
+
+## TypeScript Go
+
+`dist/tswasm.wasm` is built from `microsoft/typescript-go`, plus the local
+`go/tswasm-wasm` command in this repository.
+
+- Source: <https://github.com/microsoft/typescript-go>
+- License: Apache-2.0
+- Notice file: see `NOTICE`
+
+## Go wasm runtime
+
+`dist/wasm_exec.js` is copied from the Go toolchain and patched at build time so
+the runtime can use Web Crypto, Node Web Crypto, or a deterministic fallback in
+restricted worker-like runtimes.
+
+- Source: <https://go.dev/>
+- License: BSD-style license below
+
+```text
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
+The installed Go toolchain also includes this patent grant:
+
+```text
+Additional IP Rights Grant (Patents)
+
+"This implementation" means the copyrightable works distributed by
+Google as part of the Go project.
+
+Google hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section)
+patent license to make, have made, use, offer to sell, sell, import,
+transfer and otherwise run, modify and propagate the contents of this
+implementation of Go, where such license applies only to those patent
+claims, both currently owned or controlled by Google and acquired in
+the future, licensable by Google that are necessarily infringed by this
+implementation of Go.  This grant does not include claims that would be
+infringed only as a consequence of further modification of this
+implementation.  If you or your agent or exclusive licensee institute or
+order or agree to the institution of patent litigation against any
+entity (including a cross-claim or counterclaim in a lawsuit) alleging
+that this implementation of Go or any code incorporated within this
+implementation of Go constitutes direct or contributory patent
+infringement, or inducement of patent infringement, then any patent
+rights granted to you under this License for this implementation of Go
+shall terminate as of the date such litigation is filed.
+```

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import "./wasm_exec.js";
+export interface CompileRequest {
+    code: string;
+    fileName?: string;
+}
+export interface CompileResult {
+    js: string;
+    diagnostics: Diagnostic[];
+    success: boolean;
+    compiler: CompilerInfo;
+}
+export interface Diagnostic {
+    message: string;
+    code: number;
+    category: "error" | "warning" | "suggestion" | "message";
+    line?: number;
+    column?: number;
+}
+export interface CompilerInfo {
+    name: string;
+    runtime: string;
+    mode: string;
+    lib: string;
+}
+export interface Compiler {
+    compile(code: string): CompileResult;
+    compile(request: CompileRequest): CompileResult;
+}
+export interface CreateCompilerOptions {
+    wasm?: WebAssembly.Module | URL | string;
+}
+export declare const compilerInfo: CompilerInfo;
+type NativeCompile = (requestJson: string) => string;
+interface GoRuntime {
+    importObject: WebAssembly.Imports;
+    run(instance: WebAssembly.Instance): Promise<void>;
+}
+interface GoConstructor {
+    new (): GoRuntime;
+}
+declare global {
+    var Go: GoConstructor | undefined;
+    var __tswasmCompile: NativeCompile | undefined;
+}
+export declare function createCompiler(options?: CreateCompilerOptions): Promise<Compiler>;
+export {};

package/dist/index.js

@@ -0,0 +1,114 @@
+// @ts-ignore Generated into dist by scripts/build-wasm.ts.
+import "./wasm_exec.js";
+export const compilerInfo = {
+    name: "typescript-go (tsgo)",
+    runtime: "Go wasm",
+    mode: "single in-memory /input.ts",
+    lib: "bundled TypeScript lib.es2024.d.ts",
+};
+export async function createCompiler(options = {}) {
+    const wasm = options.wasm || defaultWasmUrl();
+    const nativeCompile = await createNativeCompile(wasm);
+    return {
+        compile(input) {
+            const request = typeof input === "string" ? { code: input } : input;
+            const nativeResult = JSON.parse(nativeCompile(JSON.stringify(request)));
+            return {
+                ...nativeResult,
+                compiler: compilerInfo,
+            };
+        },
+    };
+}
+function defaultWasmUrl() {
+    // Keep module-url syntax out of this module so Metro-style classic script
+    // bundles can parse the package when callers provide options.wasm.
+    const stack = new Error().stack || "";
+    const urlMatch = stack.match(/(?:file|https?):\/\/[^\s)]+\/index\.js(?::\d+:\d+)?/u);
+    if (urlMatch) {
+        return new URL("./tswasm.wasm", urlMatch[0].replace(/:\d+:\d+$/u, ""));
+    }
+    const pathMatch = stack.match(/(?:\/|[A-Za-z]:\\)[^\s)]+[/\\]index\.js(?::\d+:\d+)?/u);
+    const nodeUrl = nodeBuiltin("url");
+    if (pathMatch && nodeUrl?.pathToFileURL) {
+        return new URL("./tswasm.wasm", nodeUrl.pathToFileURL(pathMatch[0].replace(/:\d+:\d+$/u, "")));
+    }
+    const nodeProcess = globalThis.process;
+    const nodeFs = nodeBuiltin("fs");
+    const nodePath = nodeBuiltin("path");
+    if (nodeProcess?.cwd && nodeUrl?.pathToFileURL && nodeFs?.existsSync && nodePath?.join) {
+        const repoLocalWasm = nodePath.join(nodeProcess.cwd(), "dist", "tswasm.wasm");
+        if (nodeFs.existsSync(repoLocalWasm)) {
+            return nodeUrl.pathToFileURL(repoLocalWasm);
+        }
+    }
+    const location = globalThis.location;
+    if (location?.href) {
+        return new URL("./tswasm.wasm", location.href);
+    }
+    throw new Error("createCompiler requires options.wasm when tswasm.wasm cannot be resolved automatically");
+}
+async function createNativeCompile(wasmInput) {
+    if (!globalThis.Go) {
+        throw new Error("Go wasm runtime did not initialize");
+    }
+    const go = new globalThis.Go();
+    const instance = await instantiateWasm(wasmInput, go.importObject);
+    void go.run(instance).catch((error) => {
+        console.error("tswasm runtime exited", error);
+    });
+    return waitForNativeCompileRegistration();
+}
+async function waitForNativeCompileRegistration() {
+    for (let attempt = 0; attempt < 10; attempt++) {
+        const compile = globalThis.__tswasmCompile;
+        if (compile) {
+            return compile;
+        }
+        await Promise.resolve();
+    }
+    throw new Error("tswasm compiler did not register __tswasmCompile");
+}
+async function instantiateWasm(wasmInput, imports) {
+    if (wasmInput instanceof WebAssembly.Module) {
+        return WebAssembly.instantiate(wasmInput, imports);
+    }
+    const wasmBytes = await readWasmBytes(wasmInput);
+    const instantiated = await WebAssembly.instantiate(wasmBytes, imports);
+    return instantiated.instance;
+}
+async function readWasmBytes(input) {
+    const url = resolveWasmUrl(input);
+    if (url.protocol === "file:") {
+        const { readFile } = await importNodeFsPromises();
+        const bytes = await readFile(url);
+        return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    }
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`failed to load tswasm wasm: ${response.status}`);
+    }
+    return response.arrayBuffer();
+}
+function resolveWasmUrl(input) {
+    if (input instanceof URL) {
+        return input;
+    }
+    try {
+        return new URL(input);
+    }
+    catch {
+        return new URL(input, defaultWasmUrl());
+    }
+}
+async function importNodeFsPromises() {
+    const fs = nodeBuiltin("fs");
+    if (!fs?.promises?.readFile) {
+        throw new Error("file: wasm URLs require Node.js process.getBuiltinModule('fs')");
+    }
+    return fs.promises;
+}
+function nodeBuiltin(name) {
+    const nodeProcess = globalThis.process;
+    return nodeProcess?.getBuiltinModule?.(name);
+}