@ttsc/wasm 0.13.0 → 0.14.0-dev.20260528

package/src/MemFSError.ts

@@ -0,0 +1,43 @@
+/**
+ * Filesystem error with a POSIX error code and numeric `errno`.
+ *
+ * Matches the shape of `NodeJS.ErrnoException` so Go's `os` package interprets
+ * it as a proper `os.PathError` with a numeric error code. Thrown by the
+ * MemFS implementation when a callback would otherwise pass `null` for an
+ * impossible filesystem operation (missing path, type mismatch, …).
+ */
+export class MemFSError extends Error {
+  public code: string;
+  public errno: number;
+  public path?: string;
+  public syscall?: string;
+  constructor(code: string, syscall: string, path?: string) {
+    super(`${code}: ${syscall} ${path ?? ""}`.trim());
+    this.code = code;
+    this.errno = errnoForCode(code);
+    this.path = path;
+    this.syscall = syscall;
+  }
+}
+
+/** Map a POSIX error name to its Linux numeric errno (negative by convention). */
+function errnoForCode(code: string): number {
+  switch (code) {
+    case "ENOENT":
+      return -2;
+    case "EBADF":
+      return -9;
+    case "EEXIST":
+      return -17;
+    case "ENOTDIR":
+      return -20;
+    case "EISDIR":
+      return -21;
+    case "EINVAL":
+      return -22;
+    case "ESPIPE":
+      return -29;
+    default:
+      return -1;
+  }
+}

package/src/bootTtsc.ts

@@ -0,0 +1,214 @@
+// Boots a host-built wasm and returns the JS-side handle.
+//
+// Order of operations matters: wasm_exec.js installs default no-op fs/process
+// shims if `globalThis.fs` is missing at load time, so we must install our
+// MemFS BEFORE importing wasm_exec.js.
+//
+// The boot helper is parameterized by `apiName` so any wasm built with
+// `host.Expose(...)` can be loaded the same way. The base wasm uses "ttsc";
+// downstream consumers pick their own (e.g. "ttscPlayground", "ttscTypia").
+
+import { createMemFS } from "./createMemFS";
+import type { IBootResult } from "./structures/IBootResult";
+import type { IBootTtscOptions } from "./structures/IBootTtscOptions";
+import type { ITtscApi } from "./structures/ITtscApi";
+
+declare const importScripts: (...urls: string[]) => void;
+
+/**
+ * Per-(apiName, wasmUrl) single-flight cache for boots. Keying on apiName
+ * alone would let a second call with the same apiName but a different
+ * wasmUrl silently return the cached IBootResult of the first wasm — the
+ * caller would think they booted a fresh binary while the cached one
+ * stayed in place. The composite key lets HMR / cache-busting query
+ * strings get a fresh boot while still single-flighting genuine concurrent
+ * duplicate calls.
+ */
+const bootsInFlight = new Map<string, Promise<IBootResult>>();
+
+/**
+ * Per-apiName serialization chain. Two concurrent boots with the same
+ * apiName but different wasmUrls each install their own `globalThis[apiName
+ * + "Ready"]` resolver — they would race and the second would overwrite
+ * the first, stranding the first boot's await. The chain serializes them
+ * so one boot's Go-side `Ready.Invoke()` always lands on the resolver
+ * that boot installed.
+ */
+const bootChainByApiName = new Map<string, Promise<unknown>>();
+
+function bootKey(apiName: string, wasmUrl: string): string {
+  return `${apiName}|${resolveWasmUrl(wasmUrl)}`;
+}
+
+/**
+ * Resolve `wasmUrl` against the current document base before keying so
+ * that `./playground.wasm`, `/compiler/playground.wasm`, and the fully
+ * qualified absolute href all collapse to the same cache entry instead
+ * of spawning duplicate boots. Falls back to the raw string when no
+ * base is available (Node-side tests, non-DOM workers).
+ */
+function resolveWasmUrl(wasmUrl: string): string {
+  try {
+    const base =
+      typeof location !== "undefined" ? location.href : "http://local/";
+    return new URL(wasmUrl, base).href;
+  } catch {
+    return wasmUrl;
+  }
+}
+
+/**
+ * Boot a host-built wasm. Re-entrant only if you reuse the same `host`.
+ *
+ * Concurrent calls with the same `(apiName, wasmUrl)` pair share the same
+ * in-flight boot. Calls with the same `apiName` but different `wasmUrl`
+ * are serialized via `bootChainByApiName` so they don't race on the
+ * shared `globalThis[apiName+"Ready"]` resolver slot. On rejection the
+ * cache entries are cleared so the next call retries from scratch.
+ *
+ * **Single-Worker caveat.** Even with the chain, a second boot loaded
+ * into the SAME Worker after a first boot completes will overlay its
+ * Go runtime on top of the first — `importScripts(wasmExecUrl)` rebinds
+ * `globalThis.Go`, and the first wasm's keepalive goroutine keeps
+ * running through the new runtime's js-bridge tables. The serialization
+ * is sufficient for the typical use case (one boot per Worker over the
+ * page's lifetime) but DOES NOT make a Worker safe to host two wasm
+ * instances at once. Create a fresh Worker per concurrent wasm.
+ */
+export function bootTtsc(options: IBootTtscOptions): Promise<IBootResult> {
+  const apiName = options.apiName ?? "ttsc";
+  const key = bootKey(apiName, options.wasmUrl);
+  const inflight = bootsInFlight.get(key);
+  if (inflight) return inflight;
+  const prior = bootChainByApiName.get(apiName) ?? Promise.resolve();
+  const promise = prior
+    .catch(() => {
+      /* don't propagate a prior boot's rejection — let this one run */
+    })
+    .then(() => bootTtscOnce(options, apiName))
+    .catch((err) => {
+      bootsInFlight.delete(key);
+      throw err;
+    });
+  bootsInFlight.set(key, promise);
+  // Track the chain head for this apiName so the next boot waits on it.
+  // Swallow on the chain head specifically: we already throw to the
+  // immediate caller; surfacing it through the chain would reject every
+  // subsequent boot just because this one failed.
+  bootChainByApiName.set(
+    apiName,
+    promise.catch(() => {}),
+  );
+  return promise;
+}
+
+async function bootTtscOnce(
+  options: IBootTtscOptions,
+  apiName: string,
+): Promise<IBootResult> {
+  const wasmUrl = options.wasmUrl;
+  const wasmExecUrl = options.wasmExecUrl ?? defaultWasmExecUrl(wasmUrl);
+
+  const host = options.host ?? createMemFS();
+  const globalAny = globalThis as Record<string, unknown>;
+  // Only install fs / process if they aren't already in place. A caller
+  // booting a second wasm over the same MemFS reuses the same shims.
+  if (!globalAny.fs) globalAny.fs = host.fs;
+  if (!globalAny.process) globalAny.process = createProcessShim();
+
+  // wasm_exec.js installs `globalThis.Go`. It also reads globalThis.fs at
+  // module-eval time, so this import must follow the assignment above.
+  importScripts(wasmExecUrl);
+
+  // Race the Ready resolver against a Failed signal so a wasm-side fault
+  // (e.g. `host.Expose` refusing a duplicate call) surfaces here instead of
+  // hanging on `await ready` forever. `go.run` is fire-and-forget so its
+  // own rejection cannot reach this promise without an explicit channel.
+  const ready = new Promise<void>((resolve, reject) => {
+    globalAny[apiName + "Ready"] = () => {
+      delete globalAny[apiName + "Failed"];
+      resolve();
+    };
+    globalAny[apiName + "Failed"] = (err: unknown) => {
+      delete globalAny[apiName + "Ready"];
+      reject(err instanceof Error ? err : new Error(String(err)));
+    };
+  });
+
+  const goCtor = (globalAny as { Go?: new () => IGoInstance }).Go;
+  if (typeof goCtor !== "function") {
+    throw new Error(
+      `bootTtsc: globalThis.Go was not installed by ${wasmExecUrl} — the file may not have loaded (CSP block, wrong content type, 404), or it is not the wasm_exec.js shipped with the Go toolchain.`,
+    );
+  }
+  const go = new goCtor();
+
+  const response = await fetch(wasmUrl);
+  if (!response.ok) {
+    throw new Error(`bootTtsc: failed to fetch ${wasmUrl}: ${response.status}`);
+  }
+  const wasm = await WebAssembly.instantiateStreaming(
+    response,
+    go.importObject,
+  );
+  // go.run never resolves until the wasm exits; we don't await it.
+  void go.run(wasm.instance);
+  await ready;
+
+  const api = (globalAny as Record<string, ITtscApi | undefined>)[apiName];
+  if (!api)
+    throw new Error(
+      `bootTtsc: ${apiName} global was not set — was the wasm built with host.Expose(${JSON.stringify(apiName)}, ...)?`,
+    );
+  return { api, host };
+}
+
+/**
+ * Derive the `wasm_exec.js` URL from the wasm URL by replacing the filename.
+ *
+ * If `wasmUrl` has no directory component, returns `"wasm_exec.js"` (same
+ * directory as the caller's base URL).
+ */
+function defaultWasmExecUrl(wasmUrl: string): string {
+  const slash = wasmUrl.lastIndexOf("/");
+  if (slash < 0) return "wasm_exec.js";
+  return wasmUrl.slice(0, slash + 1) + "wasm_exec.js";
+}
+
+/**
+ * Minimal shape of the `Go` constructor that `wasm_exec.js` exports on
+ * `globalThis`. Only the members we actually use are typed here.
+ */
+interface IGoInstance {
+  importObject: WebAssembly.Imports;
+  run(instance: WebAssembly.Instance): Promise<void>;
+}
+
+/**
+ * Minimal `process` shim required by `wasm_exec.js` in non-Node environments.
+ *
+ * Go's js/wasm bridge reads `process.pid`, `process.ppid`, and calls
+ * `process.cwd()`. `getuid`/`getgid` and friends return `-1` (root-less).
+ * `umask` and `getgroups` are never exercised by the compiler but are
+ * included for completeness so unexpected calls surface as clear errors.
+ */
+function createProcessShim(): Record<string, unknown> {
+  return {
+    getuid: () => -1,
+    getgid: () => -1,
+    geteuid: () => -1,
+    getegid: () => -1,
+    getgroups: () => {
+      throw new Error("not implemented");
+    },
+    pid: -1,
+    ppid: -1,
+    umask: () => {
+      throw new Error("not implemented");
+    },
+    cwd: () => "/",
+    chdir: () => {
+      /* no-op; the workspace lives inside the MemFS */
+    },
+  };
+}

package/src/{MemFS.ts → createMemFS.ts}

@@ -11,8 +11,14 @@
 // Errors carry a `code` (e.g. ENOENT, EBADF) so Go's os package sees them as
 // proper os.PathError values.
 //
-// Files are stored as Uint8Array. Text files written via writeFile are
-// encoded by the caller; reads return the raw bytes.
+// Files are stored as Uint8Array. String input passed to writeFile is encoded,
+// byte input is copied, and readFile returns a copy so callers cannot mutate
+// stored filesystem state by keeping a reference.
+
+import { MemFSError } from "./MemFSError";
+import type { IFileStats } from "./structures/IFileStats";
+import type { IMemFSHost } from "./structures/IMemFSHost";
+import type { IWasmExecFS } from "./structures/IWasmExecFS";
 
 /** Mode bits exposed by stat. We only differentiate file vs directory. */
 const S_IFDIR = 0o040000;
@@ -20,177 +26,6 @@ const S_IFREG = 0o100000;
 const DEFAULT_FILE_MODE = S_IFREG | 0o644;
 const DEFAULT_DIR_MODE = S_IFDIR | 0o755;
 
-/**
- * Subset of the Node.js `fs` module that `wasm_exec.js` calls into.
- *
- * Go's js/wasm runtime routes all `syscall/js` filesystem operations through
- * `globalThis.fs`. In a browser there is no real `fs`, so a MemFS
- * implementation fulfils this interface. Only the operations that
- * typescript-go's compiler exercises are required; the rest are no-ops or
- * return `EPERM`/`EINVAL`.
- */
-export interface IWasmExecFS {
-  constants: Record<string, number>;
-  writeSync(fd: number, buf: Uint8Array): number;
-  write(
-    fd: number,
-    buf: Uint8Array,
-    offset: number,
-    length: number,
-    position: number | null,
-    callback: (err: NodeJS.ErrnoException | null, n: number) => void,
-  ): void;
-  open(
-    path: string,
-    flags: number,
-    mode: number,
-    callback: (err: NodeJS.ErrnoException | null, fd: number) => void,
-  ): void;
-  close(
-    fd: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  read(
-    fd: number,
-    buffer: Uint8Array,
-    offset: number,
-    length: number,
-    position: number | null,
-    callback: (err: NodeJS.ErrnoException | null, n: number) => void,
-  ): void;
-  readdir(
-    path: string,
-    callback: (err: NodeJS.ErrnoException | null, entries: string[]) => void,
-  ): void;
-  mkdir(
-    path: string,
-    perm: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  stat(
-    path: string,
-    callback: (err: NodeJS.ErrnoException | null, stats: IFileStats) => void,
-  ): void;
-  lstat(
-    path: string,
-    callback: (err: NodeJS.ErrnoException | null, stats: IFileStats) => void,
-  ): void;
-  fstat(
-    fd: number,
-    callback: (err: NodeJS.ErrnoException | null, stats: IFileStats) => void,
-  ): void;
-  fsync(
-    fd: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  unlink(
-    path: string,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  rename(
-    from: string,
-    to: string,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  rmdir(
-    path: string,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  chmod(
-    path: string,
-    mode: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  fchmod(
-    fd: number,
-    mode: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  chown(
-    path: string,
-    uid: number,
-    gid: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  fchown(
-    fd: number,
-    uid: number,
-    gid: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  lchown(
-    path: string,
-    uid: number,
-    gid: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  utimes(
-    path: string,
-    atime: number,
-    mtime: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  link(
-    path: string,
-    link: string,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  symlink(
-    path: string,
-    link: string,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  readlink(
-    path: string,
-    callback: (err: NodeJS.ErrnoException | null, link: string) => void,
-  ): void;
-  truncate(
-    path: string,
-    length: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  ftruncate(
-    fd: number,
-    length: number,
-    callback: (err: NodeJS.ErrnoException | null) => void,
-  ): void;
-  // pipe2 is what Go's wasm `os.Pipe()` calls. Returns two fds: a read end
-  // and a write end. Used by the playground's host.runWithCapturedIO to
-  // capture plugin stdout/stderr; without it the plugin's typia transform
-  // output (multi-hundred-KB JSON) silently vanishes and Execute fails.
-  pipe2(
-    flags: number,
-    callback: (
-      err: NodeJS.ErrnoException | null,
-      fds: [number, number],
-    ) => void,
-  ): void;
-}
-
-/**
- * Stat-like object returned by `stat`, `lstat`, and `fstat`.
- *
- * Mirrors the subset of `fs.Stats` that `wasm_exec.js` reads. Fields not
- * relevant to Go's `os.FileInfo` (e.g. ownership) are zeroed.
- */
-export interface IFileStats {
-  isDirectory(): boolean;
-  isFile(): boolean;
-  size: number;
-  mode: number;
-  mtimeMs: number;
-  atimeMs: number;
-  ctimeMs: number;
-  dev: number;
-  ino: number;
-  nlink: number;
-  uid: number;
-  gid: number;
-  rdev: number;
-  blksize: number;
-  blocks: number;
-}
-
 /** Internal filesystem tree node. Directories carry an empty `data` buffer. */
 interface INode {
   kind: "file" | "dir";
@@ -198,61 +33,6 @@ interface INode {
   mtimeMs: number;
 }
 
-/**
- * Filesystem error with a POSIX error code and numeric `errno`.
- *
- * Matches the shape of `NodeJS.ErrnoException` so Go's os package interprets it
- * as a proper `os.PathError` with a numeric error code.
- */
-export class MemFSError extends Error {
-  public code: string;
-  public errno: number;
-  public path?: string;
-  public syscall?: string;
-  constructor(code: string, syscall: string, path?: string) {
-    super(`${code}: ${syscall} ${path ?? ""}`.trim());
-    this.code = code;
-    this.errno = errnoForCode(code);
-    this.path = path;
-    this.syscall = syscall;
-  }
-}
-
-/** Map a POSIX error name to its Linux numeric errno (negative by convention). */
-function errnoForCode(code: string): number {
-  switch (code) {
-    case "ENOENT":
-      return -2;
-    case "EBADF":
-      return -9;
-    case "EEXIST":
-      return -17;
-    case "ENOTDIR":
-      return -20;
-    case "EISDIR":
-      return -21;
-    default:
-      return -1;
-  }
-}
-
-/**
- * Handle returned by `createMemFS`. Provides the `fs` shim to install on
- * `globalThis` plus convenience methods for seeding the virtual filesystem
- * before booting the wasm.
- */
-export interface IMemFSHost {
-  fs: IWasmExecFS;
-  writeFile(path: string, data: string | Uint8Array): void;
-  readFile(path: string): Uint8Array | null;
-  readFileText(path: string): string | null;
-  exists(path: string): boolean;
-  mkdirp(path: string): void;
-  stdout: { buffer: string };
-  stderr: { buffer: string };
-  resetStdio(): void;
-}
-
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
@@ -402,14 +182,15 @@ export function createMemFS(): IMemFSHost {
   function writeFile(p: string, data: string | Uint8Array): void {
     const norm = normalize(p);
     ensureParentDirs(norm);
-    const bytes = typeof data === "string" ? encoder.encode(data) : data;
+    const bytes =
+      typeof data === "string" ? encoder.encode(data) : new Uint8Array(data);
     nodes.set(norm, { kind: "file", data: bytes, mtimeMs: Date.now() });
   }
 
   function readFile(p: string): Uint8Array | null {
     const node = nodes.get(normalize(p));
     if (!node || node.kind !== "file") return null;
-    return node.data;
+    return new Uint8Array(node.data);
   }
 
   function readFileText(p: string): string | null {
@@ -509,7 +290,8 @@ export function createMemFS(): IMemFSHost {
       if (entry) {
         const node = nodes.get(entry.path);
         if (node && node.kind === "file") {
-          // subarray(0) is a zero-copy view over the full incoming buffer.
+          // subarray(0) is a zero-copy view over the full incoming buffer; the
+          // bytes are copied into `next` before writeSync returns.
           const incoming = buf.subarray(0);
           const existing = node.data;
           const next = new Uint8Array(

package/src/index.ts

@@ -5,20 +5,8 @@
 // (`host/`) is shipped alongside on disk but loaded via `go build`, not
 // imported from JS.
 
-export { bootTtsc } from "./instantiate";
-export type { IBootTtscOptions, IBootResult } from "./instantiate";
-
-export { createMemFS, MemFSError } from "./MemFS";
-export type { IMemFSHost, IWasmExecFS, IFileStats } from "./MemFS";
-
-export type {
-  ITtscApi,
-  ITtscVersion,
-  ITtscBuildOpts,
-  ITtscPluginOpts,
-  ITtscResult,
-  ITtscCompileResult,
-  ITtscTransformResult,
-  ITtscDiagnostic,
-} from "./api";
-export { parseResult } from "./api";
+export * from "./bootTtsc";
+export * from "./createMemFS";
+export * from "./MemFSError";
+export * from "./parseResult";
+export * from "./structures/index";

package/src/parseResult.ts

@@ -0,0 +1,17 @@
+import type { ITtscResult } from "./structures/ITtscResult";
+
+/**
+ * Parse the `result` field of an ITtscResult into the structured payload.
+ *
+ * The wasm returns JSON as a string because `js.ValueOf` does not handle
+ * large nested maps efficiently. Callers JSON.parse exactly once at the
+ * boundary.
+ */
+export function parseResult<T>(result: ITtscResult): T | null {
+  if (!result.result) return null;
+  try {
+    return JSON.parse(result.result) as T;
+  } catch {
+    return null;
+  }
+}

package/src/structures/IBootResult.ts

@@ -0,0 +1,10 @@
+import type { IMemFSHost } from "./IMemFSHost";
+import type { ITtscApi } from "./ITtscApi";
+
+/** Handle returned by `bootTtsc` once the wasm is ready. */
+export interface IBootResult {
+  /** The typed API proxy bound by the wasm to `globalThis[apiName]`. */
+  api: ITtscApi;
+  /** The MemFS instance shared with the wasm's virtual filesystem. */
+  host: IMemFSHost;
+}

package/src/structures/IBootTtscOptions.ts

@@ -0,0 +1,22 @@
+import type { IMemFSHost } from "./IMemFSHost";
+
+/** Options for `bootTtsc`. All fields except `wasmUrl` have sensible defaults. */
+export interface IBootTtscOptions {
+  /** URL of the .wasm to fetch. */
+  wasmUrl: string;
+  /** URL of wasm_exec.js. Defaults to the same directory as wasmUrl. */
+  wasmExecUrl?: string;
+  /**
+   * GlobalThis property name the wasm binds. Must match the value the wasm
+   * was built with (the `apiName` passed to `host.Expose`). Defaults to
+   * `"ttsc"`.
+   */
+  apiName?: string;
+  /**
+   * Optional pre-existing MemFS host. When omitted, a fresh one is created
+   * and stored on the returned BootResult. Pass an existing host when you
+   * want to boot multiple wasms over the same filesystem (e.g. base ttsc + a
+   * typia wasm) so they share project sources.
+   */
+  host?: IMemFSHost;
+}

package/src/structures/IFileStats.ts

@@ -0,0 +1,23 @@
+/**
+ * Stat-like object returned by `stat`, `lstat`, and `fstat`.
+ *
+ * Mirrors the subset of `fs.Stats` that `wasm_exec.js` reads. Fields not
+ * relevant to Go's `os.FileInfo` (e.g. ownership) are zeroed.
+ */
+export interface IFileStats {
+  isDirectory(): boolean;
+  isFile(): boolean;
+  size: number;
+  mode: number;
+  mtimeMs: number;
+  atimeMs: number;
+  ctimeMs: number;
+  dev: number;
+  ino: number;
+  nlink: number;
+  uid: number;
+  gid: number;
+  rdev: number;
+  blksize: number;
+  blocks: number;
+}

package/src/structures/IMemFSHost.ts

@@ -0,0 +1,18 @@
+import type { IWasmExecFS } from "./IWasmExecFS";
+
+/**
+ * Handle returned by `createMemFS`. Provides the `fs` shim to install on
+ * `globalThis` plus convenience methods for seeding the virtual filesystem
+ * before booting the wasm.
+ */
+export interface IMemFSHost {
+  fs: IWasmExecFS;
+  writeFile(path: string, data: string | Uint8Array): void;
+  readFile(path: string): Uint8Array | null;
+  readFileText(path: string): string | null;
+  exists(path: string): boolean;
+  mkdirp(path: string): void;
+  stdout: { buffer: string };
+  stderr: { buffer: string };
+  resetStdio(): void;
+}