@ttsc/wasm 0.12.2 → 0.12.4

package/src/MemFS.ts

@@ -20,6 +20,15 @@ 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;
@@ -37,7 +46,10 @@ export interface IWasmExecFS {
     mode: number,
     callback: (err: NodeJS.ErrnoException | null, fd: number) => void,
   ): void;
-  close(fd: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+  close(
+    fd: number,
+    callback: (err: NodeJS.ErrnoException | null) => void,
+  ): void;
   read(
     fd: number,
     buffer: Uint8Array,
@@ -67,7 +79,10 @@ export interface IWasmExecFS {
     fd: number,
     callback: (err: NodeJS.ErrnoException | null, stats: IFileStats) => void,
   ): void;
-  fsync(fd: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+  fsync(
+    fd: number,
+    callback: (err: NodeJS.ErrnoException | null) => void,
+  ): void;
   unlink(
     path: string,
     callback: (err: NodeJS.ErrnoException | null) => void,
@@ -152,6 +167,12 @@ export interface IWasmExecFS {
   ): 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;
@@ -170,12 +191,19 @@ export interface IFileStats {
   blocks: number;
 }
 
+/** Internal filesystem tree node. Directories carry an empty `data` buffer. */
 interface INode {
   kind: "file" | "dir";
   data: Uint8Array;
   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;
@@ -190,6 +218,7 @@ export class MemFSError extends Error {
   }
 }
 
+/** Map a POSIX error name to its Linux numeric errno (negative by convention). */
 function errnoForCode(code: string): number {
   switch (code) {
     case "ENOENT":
@@ -207,6 +236,11 @@ function errnoForCode(code: string): number {
   }
 }
 
+/**
+ * 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;
@@ -222,6 +256,12 @@ export interface IMemFSHost {
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
+/**
+ * Resolve a path to an absolute, normalized POSIX path.
+ *
+ * Collapses `.` and `..` segments and converts backslashes. Returns `"/"` for
+ * empty input.
+ */
 function normalize(p: string): string {
   if (!p) return "/";
   const parts = p.replace(/\\/g, "/").split("/").filter(Boolean);
@@ -237,6 +277,15 @@ function normalize(p: string): string {
   return "/" + stack.join("/");
 }
 
+/**
+ * Create an in-memory filesystem suitable for use as `globalThis.fs` inside a
+ * Go/wasm runtime.
+ *
+ * The returned host exposes the low-level `fs` object (install it on
+ * `globalThis.fs` before loading `wasm_exec.js`) and convenience helpers
+ * (`writeFile`, `readFile`, `mkdirp`, …) for seeding source files and reading
+ * compiler output without touching the real filesystem.
+ */
 export function createMemFS(): IMemFSHost {
   const nodes = new Map<string, INode>();
   nodes.set("/", { kind: "dir", data: new Uint8Array(), mtimeMs: Date.now() });
@@ -271,6 +320,10 @@ export function createMemFS(): IMemFSHost {
   }
   const pipes = new Map<number, IPipeState>();
 
+  /**
+   * Drain buffered pipe data into `buffer[offset..offset+length]`. Returns
+   * bytes copied.
+   */
   function drainPipeInto(
     state: IPipeState,
     buffer: Uint8Array,
@@ -289,19 +342,29 @@ export function createMemFS(): IMemFSHost {
     return written;
   }
 
+  /**
+   * Satisfy any pending blocked readers using available pipe data or EOF
+   * signal.
+   */
   function flushPipeReaders(state: IPipeState): void {
     while (
       state.pendingReaders.length > 0 &&
       (state.buffers.length > 0 || state.writeClosed)
     ) {
       const reader = state.pendingReaders.shift()!;
-      const n = drainPipeInto(state, reader.buffer, reader.offset, reader.length);
+      const n = drainPipeInto(
+        state,
+        reader.buffer,
+        reader.offset,
+        reader.length,
+      );
       // Even at EOF (writeClosed && empty buffers) we satisfy with n=0 which
       // signals EOF to the Go-side caller.
       reader.callback(null, n);
     }
   }
 
+  /** Silently create any missing ancestor directories for path `p`. */
   function ensureParentDirs(p: string): void {
     const segments = normalize(p).split("/").filter(Boolean);
     segments.pop();
@@ -358,6 +421,7 @@ export function createMemFS(): IMemFSHost {
     return nodes.has(normalize(p));
   }
 
+  /** Synchronously stat `p`; throws `MemFSError("ENOENT")` if not found. */
   function statSync(p: string): IFileStats {
     const norm = normalize(p);
     const node = nodes.get(norm);
@@ -365,6 +429,7 @@ export function createMemFS(): IMemFSHost {
     return makeStats(node);
   }
 
+  /** Build an `IFileStats` object from a filesystem node. */
   function makeStats(node: INode): IFileStats {
     const isDir = node.kind === "dir";
     return {
@@ -386,6 +451,12 @@ export function createMemFS(): IMemFSHost {
     };
   }
 
+  /**
+   * Return immediate children of directory `p`, sorted alphabetically.
+   *
+   * Uses a linear scan over the node map and a `Set` to deduplicate nested
+   * paths into direct-child names — O(n) in the number of total nodes.
+   */
   function readdirSync(p: string): string[] {
     const norm = normalize(p);
     const node = nodes.get(norm);
@@ -438,9 +509,12 @@ 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.
           const incoming = buf.subarray(0);
           const existing = node.data;
-          const next = new Uint8Array(existing.byteLength + incoming.byteLength);
+          const next = new Uint8Array(
+            existing.byteLength + incoming.byteLength,
+          );
           next.set(existing, 0);
           next.set(incoming, existing.byteLength);
           node.data = next;
@@ -455,7 +529,11 @@ export function createMemFS(): IMemFSHost {
       stderr.buffer += decoder.decode(buf);
       // eslint-disable-next-line no-console
       console.error(
-        "[wasm] writeSync to unknown fd " + fd + " (" + buf.byteLength + " bytes); routed to stderr buffer",
+        "[wasm] writeSync to unknown fd " +
+          fd +
+          " (" +
+          buf.byteLength +
+          " bytes); routed to stderr buffer",
       );
       return buf.length;
     },
@@ -599,7 +677,10 @@ export function createMemFS(): IMemFSHost {
       try {
         callback(null, statSync(p));
       } catch (err) {
-        callback(err as NodeJS.ErrnoException, undefined as unknown as IFileStats);
+        callback(
+          err as NodeJS.ErrnoException,
+          undefined as unknown as IFileStats,
+        );
       }
     },
 
@@ -614,7 +695,11 @@ export function createMemFS(): IMemFSHost {
       if (pipes.has(fd)) {
         callback(
           null,
-          makeStats({ kind: "file", data: new Uint8Array(), mtimeMs: Date.now() }),
+          makeStats({
+            kind: "file",
+            data: new Uint8Array(),
+            mtimeMs: Date.now(),
+          }),
         );
         return;
       }

package/src/api.ts

@@ -3,28 +3,40 @@
 // `playground.wasm`, typia's `ttsc-typia.wasm`) exposes the same surface, so
 // one set of types covers them all.
 
+/**
+ * API object that every host-built wasm binds to `globalThis[apiName]`.
+ *
+ * Obtain an instance via `bootTtsc`, which waits for the wasm to signal
+ * readiness and returns the typed handle together with its `IMemFSHost`.
+ */
 export interface ITtscApi {
   /** Build metadata reported by the wasm. Useful for diagnostics. */
   version(): ITtscVersion;
 
-  /** Compile a project: typecheck + emit. `result` is JSON; `parseResult<ITtscCompileResult>` deserializes it. */
+  /**
+   * Compile a project: typecheck + emit. `result` is JSON;
+   * `parseResult<ITtscCompileResult>` deserializes it.
+   */
   build(opts: ITtscBuildOpts): Promise<ITtscResult>;
 
-  /** Typecheck without emit. `result` is JSON; `parseResult<ITtscCompileResult>` deserializes it. */
+  /**
+   * Typecheck without emit. `result` is JSON; `parseResult<ITtscCompileResult>`
+   * deserializes it.
+   */
   check(opts: ITtscBuildOpts): Promise<ITtscResult>;
 
   /**
-   * Return every source file the program saw, keyed by project-relative
-   * path. Used by playgrounds that want to render the TypeScript view after
-   * a source rewriter (e.g. paths) has run. `result` is JSON; use
+   * Return every source file the program saw, keyed by project-relative path.
+   * Used by playgrounds that want to render the TypeScript view after a source
+   * rewriter (e.g. paths) has run. `result` is JSON; use
    * `parseResult<ITtscTransformResult>` to deserialize.
    */
   transform(opts: ITtscBuildOpts): Promise<ITtscResult>;
 
   /**
    * Dispatch a registered plugin's subcommand. Returns the captured stdout /
-   * stderr (the same streams the native sidecar binary would write to)
-   * together with the exit code.
+   * stderr (the same streams the native sidecar binary would write to) together
+   * with the exit code.
    */
   plugin(opts: ITtscPluginOpts): Promise<ITtscResult>;
 
@@ -32,6 +44,7 @@ export interface ITtscApi {
   plugins(): string[];
 }
 
+/** Build metadata embedded in the wasm by the Go linker at compile time. */
 export interface ITtscVersion {
   version: string;
   commit: string;
@@ -41,13 +54,15 @@ export interface ITtscVersion {
   goarch: string;
 }
 
+/** Options shared by `build`, `check`, and `transform`. */
 export interface ITtscBuildOpts {
   /** Absolute virtual path the project lives at inside the MemFS. */
   cwd: string;
-  /** tsconfig path, relative to `cwd`. Defaults to `tsconfig.json`. */
+  /** Tsconfig path, relative to `cwd`. Defaults to `tsconfig.json`. */
   tsconfig?: string;
 }
 
+/** Options for dispatching a named plugin subcommand via `api.plugin`. */
 export interface ITtscPluginOpts {
   /** Plugin id registered with `host.Expose` (e.g. `@ttsc/banner`). */
   name: string;
@@ -61,6 +76,7 @@ export interface ITtscPluginOpts {
   [key: string]: string | boolean | number | undefined;
 }
 
+/** Envelope returned by every `ITtscApi` method. */
 export interface ITtscResult {
   /** Exit code. 0 = success, 2 = usage error, 3 = runtime error. */
   code: number;
@@ -69,23 +85,40 @@ export interface ITtscResult {
   /** Anything the wasm wrote to its stderr stream. */
   stderr: string;
   /**
-   * For the base endpoints, the JSON-encoded compile/transform result. For
-   * the plugin endpoint, this is empty — the plugin's own output sits in
+   * For the base endpoints, the JSON-encoded compile/transform result. For the
+   * plugin endpoint, this is empty — the plugin's own output sits in
    * stdout/stderr. Use `parseResult<T>` to deserialize.
    */
   result: string;
 }
 
+/**
+ * Structured payload inside `ITtscResult.result` for `build` and `check`.
+ *
+ * `output` maps emit-destination paths (relative to `outDir`) to file contents.
+ * It is empty when `check` is called without emit.
+ */
 export interface ITtscCompileResult {
   diagnostics?: ITtscDiagnostic[];
   output: Record<string, string>;
 }
 
+/**
+ * Structured payload inside `ITtscResult.result` for `transform`.
+ *
+ * `typescript` maps source file paths (relative to `cwd`) to their
+ * post-transform TypeScript text — useful for playgrounds that want to show the
+ * rewritten source before it is emitted.
+ */
 export interface ITtscTransformResult {
   diagnostics?: ITtscDiagnostic[];
   typescript: Record<string, string>;
 }
 
+/**
+ * A single TypeScript compiler diagnostic emitted during `build`, `check`, or
+ * `transform`. `line` and `character` are 0-based.
+ */
 export interface ITtscDiagnostic {
   file: string | null;
   category: "error" | "warning";
@@ -98,9 +131,9 @@ export interface ITtscDiagnostic {
 }
 
 /**
- * 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.
+ * 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;

package/src/index.ts

@@ -9,11 +9,7 @@ export { bootTtsc } from "./instantiate";
 export type { IBootTtscOptions, IBootResult } from "./instantiate";
 
 export { createMemFS, MemFSError } from "./MemFS";
-export type {
-  IMemFSHost,
-  IWasmExecFS,
-  IFileStats,
-} from "./MemFS";
+export type { IMemFSHost, IWasmExecFS, IFileStats } from "./MemFS";
 
 export type {
   ITtscApi,

package/src/instantiate.ts

@@ -7,39 +7,43 @@
 // 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, type IMemFSHost } from "./MemFS";
+import { type IMemFSHost, createMemFS } from "./MemFS";
 import type { ITtscApi } from "./api";
 
 declare const importScripts: (...urls: string[]) => void;
 
+/** 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".
+   * 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.
+   * 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;
 }
 
+/** 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;
 }
 
 /** Boot a host-built wasm. Re-entrant only if you reuse the same `host`. */
-export async function bootTtsc(options: IBootTtscOptions): Promise<IBootResult> {
+export async function bootTtsc(
+  options: IBootTtscOptions,
+): Promise<IBootResult> {
   const wasmUrl = options.wasmUrl;
   const wasmExecUrl = options.wasmExecUrl ?? defaultWasmExecUrl(wasmUrl);
   const apiName = options.apiName ?? "ttsc";
@@ -64,11 +68,12 @@ export async function bootTtsc(options: IBootTtscOptions): Promise<IBootResult>
 
   const response = await fetch(wasmUrl);
   if (!response.ok) {
-    throw new Error(
-      `bootTtsc: failed to fetch ${wasmUrl}: ${response.status}`,
-    );
+    throw new Error(`bootTtsc: failed to fetch ${wasmUrl}: ${response.status}`);
   }
-  const wasm = await WebAssembly.instantiateStreaming(response, go.importObject);
+  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;
@@ -81,17 +86,35 @@ export async function bootTtsc(options: IBootTtscOptions): Promise<IBootResult>
   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,