xbintsc 0.5.6 → 0.5.21

package/doc/implemented/extensions.md

@@ -0,0 +1,19 @@
+# Extension mechanism
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/extensions.md)
+
+Location: `src/extensions/registry.ts`, `src/extensions/node/`
+
+- An extension is a plain object: `runtimeSources()` (extra C sources), `linkerFlags()` (extra link flags), `builtins()` (global identifier → runtime symbol, uniform `(argc, argv)` ABI) and `modules()` (import specifier → named exports / namespace).
+- `ExtensionRegistry`: register / unregister / lookup / aggregate builtins, modules, runtime sources and link flags.
+- The built-in core extension `core`: exposes `print` (mapped to `xt_println`), always registered.
+- The Node extension `node`:
+  - Modular organisation: `src/extensions/node/fs/` + `runtime/ext_node/fs/read_file.c`
+  - Exposes importable modules (`fs`, `fs/promises`, `path`, `os`, `process`, ...) under both bare and `node:`-prefixed specifiers; `import { readFileSync } from "fs"` resolves to `xt_node_read_text_file`, and `path`/`os`/`process` map exports onto the namespace dispatchers.
+- Adding a new module only requires a new directory plus a C implementation; the core compiler never changes.
+- Native C++/Rust extensions (`src/extensions/native.ts`, `--ext-native`):
+  - `nativeObjects()` links pre-built objects/static archives that expose `extern "C"` symbols with the `(argc, argv)` ABI; a JSON manifest maps them onto builtins/modules (`linkerFlags` / `linkerFlagsByPlatform` cover C++/Rust runtimes).
+  - Authoring helpers live in `runtime/xt_ext.h` (C/C++) and `runtime/xt_ext.rs` (Rust); runnable projects are under `examples/extensions/`.
+  - The driver links the artifacts verbatim and the incremental cache fingerprints their contents, so a rebuilt library invalidates the cached binary.
+  - CI builds both language examples on Linux, macOS and Windows; on Windows the system clang links with the MSVC ABI (C++ `-lmsvcprt`, Rust `*-pc-windows-msvc` plus the Windows system libraries).
+- Node module coverage is documented in [Node extension](./node.md).

package/doc/implemented/fetch.md

@@ -0,0 +1,44 @@
+# fetch
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/fetch.md)
+
+Location: `runtime/xt_fetch.c`, `runtime/xt_fetch/async.inc`, `runtime/xt_async_io.c`.
+
+- Global `fetch(input, init)` is an HTTP/1.1 client. The blocking socket exchange
+  (`getaddrinfo`, connect, send, receive) runs on the asynchronous I/O worker
+  pool, so a request in flight does **not** stall the event loop: timers, sockets
+  and other `await`s keep running and the promise settles when the reactor
+  dispatches the completed exchange.
+- Redirects are followed on the main thread: each hop is one offloaded
+  exchange, up to 20 redirects, and a 301/302/303 switches POST to GET.
+- It accepts `http://` URLs only — `https://` rejects with a `TypeError` because
+  no TLS backend is linked.
+- Options: `method`, `headers` (plain object or `Headers`), `body` and `redirect`
+  (`follow` / `manual` / `error`).
+- The resolved `Response`-shaped object exposes `ok` / `status` / `statusText` /
+  `url` / `headers` plus `text()` / `json()` / `arrayBuffer()` / `bytes()` /
+  `clone()`. The body is buffered before the promise settles; streaming bodies
+  are not implemented.
+- `Headers` is case-insensitive with `get` / `has` / `set` / `append` /
+  `delete` / `keys` / `values` / `entries` / `forEach` / `getSetCookie`.
+- Invalid URLs and network failures reject with a `TypeError`.
+
+```ts
+async function main(): Promise<void> {
+  const response = await fetch("http://127.0.0.1:8080/status");
+  console.log(response.status, await response.text());
+}
+main();
+```
+
+A timer scheduled before the request completes fires while the exchange is still
+in flight:
+
+```ts
+const pending = fetch("http://127.0.0.1:8080/slow");
+setTimeout(() => console.log("timer"), 10); // runs before the 150ms response
+await pending;
+```
+
+Known limits (only `http://`, no TLS, buffered body) are listed in
+[Runtime deviations](../unimplemented/deviations.md).

package/doc/implemented/lexer.md

@@ -0,0 +1,23 @@
+# Lexer
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/lexer.md)
+
+Location: `src/lexer/scanner.ts`, `src/lexer/token.ts`
+
+- Full token classification: identifiers, keywords, private identifiers, numbers, strings, templates, regex (scanning), all punctuation and operators.
+- Full keyword table: `abstract any as asserts async await bigint boolean break case catch class const constructor continue debugger declare default delete do else enum export extends false finally for from function get if implements import in infer instanceof interface is keyof let module namespace never new null number object package private protected public readonly return satisfies set static string super switch symbol this throw true try type typeof undefined unique unknown var void while with yield`
+- Numeric literals:
+  - Decimal, `0x` hex, `0o` octal, `0b` binary
+  - Underscore separators `1_000_000`
+  - Fractions, exponents `1.5e3`
+  - BigInt literals (`10n`, `0xFFn`) evaluate to arbitrary-precision integers (arithmetic, bitwise, shifts, comparisons, `toString(radix)`, `BigInt()` / `BigInt.asIntN` / `BigInt.asUintN`)
+  - BigInt literal values are parsed exactly into `bigint` (never routed through `Number`), so the token / AST value of a literal beyond 2^53 keeps full precision
+- String literals:
+  - Single / double quotes
+  - Escapes: `\n \t \r \b \f \0 \\ \' \"`, `\xHH`, `\uHHHH`, `\u{...}`
+- Template literals (lexer level): no-substitution templates, `TemplateHead`, `TemplateMiddle`, `TemplateTail`, with `${}` and escapes.
+- Regex literal scanning (`/pattern/flags`), distinguishing division `/`.
+- Private identifiers `#name`.
+- Comments: line `//` and block `/* */` (with unterminated diagnostics).
+- Newline and whitespace tracking (for ASI), BOM / CRLF normalization (`SourceFile`).
+- Lexical diagnostics: unterminated string / template / comment, illegal character, illegal number, illegal escape.

package/doc/implemented/modules.md

@@ -0,0 +1,28 @@
+# Module system
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/modules.md)
+
+Location: `src/parser/parser.ts` (syntax), `src/driver/modules.ts` (bundling),
+`src/driver/frontend.ts` (`parseEntry`).
+
+## Syntax
+
+- `import default, { named } from "..."`, `import * as ns from "..."` (namespace imports of relative modules are lowered to a synthetic object literal; extension modules such as `path` are also supported), `import "./side-effect"`, `import type`
+- `export default`, `export { a as b }`, `export *`, `export =`
+- Import attributes (`with` / `assert`)
+
+## Runtime semantics
+
+- The **runtime semantics** of `import` / `export` are handled at the driver layer by `src/driver/modules.ts`: it recursively resolves relative dependencies *and* bare `node_modules` packages (following `exports` / `module` / `main` and package subpaths), renames top-level symbols with a per-module prefix, rewrites references, merges into a single file and rebinds.
+- Packages may be ESM or CommonJS: a CommonJS file under `node_modules` gets a synthetic `module`/`exports` pair, its `require` calls are lowered to the bundled dependency's exports, and its statically-detected exports are exposed to ESM importers. `require()` outside `node_modules` is still rejected with a hint to use `import`. Circular dependencies error out.
+- A `.js`-family specifier resolves to its `.ts` source, and TypeScript suffixes are preferred over JavaScript siblings when the specifier omits the extension; plain `.js` / `.jsx` / `.mjs` / `.cjs` sources are bundled directly.
+- Imported bindings and namespace members are snapshots at module-evaluation time (no live bindings) — see [Unimplemented: module system](../unimplemented/modules.md).
+- Type-only imports and re-exports (`import type { T } from "..."`, `import { type T } from "..."`, `export type { T } from "..."`) are erased. They are **not** module edges: the target is not loaded or bundled, and a type-only cycle between modules is not a circular dependency. Use a side-effect import (`import "./mod"`) when a module must be evaluated without binding a name.
+
+## import.meta
+
+- `import.meta.url` / `.dirname` / `.filename`, resolved from the running executable's path.
+
+## Extension modules
+
+- Extension modules (such as `fs`) are importable by bare or `node:`-prefixed specifier and resolve to their runtime entries; see [Extensions](./extensions.md).

package/doc/implemented/node/assert.md

@@ -0,0 +1,17 @@
+# `assert`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/assert.md)
+
+Location: `src/extensions/node/assert/index.ts`, `runtime/ext_node/assert/assert.c`
+
+`assert.ok` / `fail` / `equal` / `notEqual` / `strictEqual` / `notStrictEqual` /
+`deepEqual` / `notDeepEqual` / `deepStrictEqual` / `notDeepStrictEqual` /
+`throws` / `doesNotThrow` / `rejects` / `doesNotReject` / `match` /
+`doesNotMatch` / `ifError`.
+
+Named imports and the namespace form both dispatch through `xt_assert_static`:
+
+```ts
+import assert from "node:assert";
+assert.strictEqual(1 + 1, 2);
+```

package/doc/implemented/node/buffer.md

@@ -0,0 +1,29 @@
+# `buffer`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/buffer.md)
+
+Location: `src/extensions/node/buffer/index.ts`, `runtime/ext_node/buffer/buffer.c`
+
+xbintsc has no native binary value type, so `Buffer` is represented as a
+**plain object**: each byte is a numeric property `"0".."n-1"`, plus a `length`
+property, sharing the `xt_buffer_proto()` prototype that provides instance
+methods. `xt_node_is_buffer` / `xt_node_buffer_bytes` let other modules access
+bytes across modules.
+
+| Static method | Notes |
+| --- | --- |
+| `Buffer.from(value[, encoding])` | construct from a string (hex / base64 / utf8), array or Buffer |
+| `Buffer.alloc(size[, fill])` | allocate and fill |
+| `Buffer.allocUnsafe(size)` | allocate |
+| `Buffer.isBuffer(value)` | test |
+| `Buffer.byteLength(value[, encoding])` | byte length |
+| `Buffer.concat(list[, totalLength])` | concatenate |
+| `Buffer.compare(a, b)` | compare |
+
+Instance methods: `toString([encoding])`, `toJSON()`, `slice(start, end)`, `subarray(...)`, `equals(other)`, `compare(other)`, `copy(target[, targetStart, sourceStart, sourceEnd])`, `write(string[, offset[, length[, encoding]]])`, `fill(value)`, `reverse()`, `indexOf(value)`, `lastIndexOf(value)`, `includes(value)`, `keys()`, `values()`, plus `readUInt8/UInt16LE/UInt16BE/UInt32LE/UInt32BE`, `writeUInt8/UInt16LE/UInt16BE/UInt32LE/UInt32BE`.
+
+```ts
+const buf = Buffer.from("hello");
+console.log(buf.toString(), buf.length);      // hello 5
+console.log(Buffer.alloc(4, 65).toString());  // AAAA
+```

package/doc/implemented/node/child-process.md

@@ -0,0 +1,29 @@
+# `child_process`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/child-process.md)
+
+Location: `src/extensions/node/child_process/index.ts`, `runtime/ext_node/child_process/child_process.c`
+
+`spawnSync(command, args[, options])` runs a program to completion and returns
+`{ status, stdout, stderr }`. `options.cwd` sets the working directory and
+`options.stdio: "inherit"` hands the child the parent's stdout/stderr (used by
+`xbintsc run`, so a compiled program's output streams live); otherwise
+stdout/stderr are captured as UTF-8 strings.
+
+| Option | Notes |
+| --- | --- |
+| `cwd` | working directory for the child |
+| `stdio: "inherit"` | share the parent's stdout/stderr instead of capturing |
+| `encoding` | accepted and ignored (output is always decoded as UTF-8) |
+
+On Windows the child is launched with `CreateProcess` and its stdout/stderr are
+drained through anonymous pipes by reader threads. No temporary files are used,
+so a locked-down `%TEMP%` cannot break `spawnSync`, and output larger than a pipe
+buffer cannot deadlock.
+
+```ts
+import { spawnSync } from "child_process";
+
+const result = spawnSync("clang", ["--version"], { encoding: "utf8" });
+console.log(result.status, result.stdout.split("\n")[0]);
+```

package/doc/implemented/node/crypto.md

@@ -0,0 +1,9 @@
+# `crypto`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/crypto.md)
+
+Location: `src/extensions/node/crypto/index.ts`, `runtime/ext_node/crypto/crypto.c`
+
+- `createHash(algorithm)` returns a hash object with `update(...)` and `digest([encoding])`.
+- The streaming form (`setEncoding` / `write` / `end` / `read`) is supported.
+- SHA-1 and SHA-256 are available.

package/doc/implemented/node/dgram.md

@@ -0,0 +1,15 @@
+# `dgram`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/dgram.md)
+
+Location: `src/extensions/node/dgram/index.ts`, `runtime/ext_node/dgram/dgram.c`
+
+UDP sockets. `dgram.createSocket(type | options[, cb])` returns an EventEmitter.
+
+| Method | Notes |
+| --- | --- |
+| `bind([port][, address][, cb])` | bind (`send` auto-binds if unbound) |
+| `send(msg[, offset, length,] port[, address][, cb])` | send a datagram |
+| `close([cb])` / `address()` | close / query address |
+| `setBroadcast(b)` / `setTTL(n)` / `setMulticastTTL(n)` | socket options |
+| `on('message', (msg, rinfo) => ...)` | receive a datagram; `rinfo` has `address` / `port` / `family` / `size` |

package/doc/implemented/node/events.md

@@ -0,0 +1,37 @@
+# `events`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/events.md)
+
+Location: `src/extensions/node/events/index.ts`, `runtime/ext_node/events/events.c`
+
+Provides a standalone `EventEmitter`, available both as a **global constructor**
+(`new EventEmitter()`) and as a named export
+(`import { EventEmitter } from "events"`). Instances share the runtime emitter
+used by `stream` / `net` / `http` (listeners live in an internal `__xt_events`
+property), with the fuller `events` surface layered on top:
+
+| Method | Notes |
+| --- | --- |
+| `on(name, fn)` / `addListener(name, fn)` | append a listener |
+| `once(name, fn)` | fire at most once, then remove itself |
+| `prependListener(name, fn)` / `prependOnceListener(name, fn)` | insert at the front |
+| `off(name, fn)` / `removeListener(name, fn)` | remove a listener |
+| `removeAllListeners([name])` | clear one event (or all events) |
+| `emit(name[, ...args])` | invoke listeners |
+| `listeners(name)` / `rawListeners(name)` | listener array |
+| `listenerCount(name)` | number of listeners |
+| `eventNames()` | names that currently have listeners |
+| `setMaxListeners(n)` / `getMaxListeners()` | bookkeeping (default 10) |
+
+Statics reachable through the namespace (`import ee from "events"`):
+`listenerCount`, `getEventListeners`, `getMaxListeners`, `setMaxListeners`,
+`once`, `addAbortListener`.
+
+```ts
+import { EventEmitter } from "events";
+
+const em = new EventEmitter();
+em.once("ready", () => console.log("ready"));
+em.emit("ready"); // ready
+em.emit("ready"); // nothing: the listener already ran
+```

package/doc/implemented/node/fs-promises.md

@@ -0,0 +1,49 @@
+# `fs/promises`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/fs-promises.md)
+
+Location: `src/extensions/node/fs-promises/index.ts`, `runtime/ext_node/fs/async_*.c`,
+`runtime/ext_node/fs/promises.c`.
+
+Every function submits a job to the runtime's asynchronous I/O pool
+(`runtime/xt_async_io.c`): the blocking syscall runs on a worker thread and the
+promise settles on the event loop. `await` therefore yields while a large read,
+a slow network filesystem or a descriptor operation is in progress, and `then` /
+`catch` keep the usual Promise semantics. Failures **reject** with the same
+Node-shaped `Error` (with `code` / `errno` / `syscall` / `path`) that the
+synchronous form throws.
+
+`fs.promises` is also reachable from the `fs` module
+(`import { promises as fsp } from "fs"`), and both namespaces expose a
+`constants` object.
+
+Promise exports: `readFile`, `writeFile`, `appendFile`, `mkdir`, `readdir`,
+`rm`, `unlink`, `rmdir`, `rename`, `copyFile`, `cp`, `realpath`, `stat`,
+`lstat`, `statfs`, `access`, `open`, `chmod`, `lchmod`, `chown`, `lchown`,
+`truncate`, `utimes`, `lutimes`, `link`, `symlink`, `readlink`, `mkdtemp`,
+`opendir`, `glob`, `watch`.
+
+`open(...)` resolves to a **`FileHandle`** with:
+`read`, `write`, `readFile`, `writeFile`, `appendFile`, `close`, `stat`,
+`truncate`, `chmod`, `chown`, `utimes`, `sync`, `datasync`. Those methods are
+offloaded too; `read(buffer, …)` fills the caller's `Buffer` when the worker
+completes.
+
+```ts
+import { readFile, writeFile, open } from "fs/promises";
+
+async function main(): Promise<void> {
+  await writeFile("/tmp/a.txt", "hi");
+  console.log(await readFile("/tmp/a.txt"));
+  const handle = await open("/tmp/a.txt", "r");
+  console.log(await handle.readFile("utf8"));
+  await handle.close();
+}
+main();
+```
+
+Work runs on a small fixed pool (four workers) and completions are dispatched in
+submission order per worker; independent operations can overlap. A job never
+blocks another `await`, a timer or a socket callback.
+
+Known deviations are listed in [Unimplemented: `fs/promises`](../../unimplemented/node/fs-promises.md).

package/doc/implemented/node/fs.md

@@ -0,0 +1,112 @@
+# `fs`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/fs.md)
+
+Location: `src/extensions/node/fs/*.ts`, `runtime/ext_node/fs/*.c`
+
+## Available functions (imported from `fs`)
+
+| Imported function | Runtime symbol | Notes |
+| --- | --- | --- |
+| `readFileSync(path[, options])` | `xt_node_read_text_file` | synchronously read a file, returns a string; supports encoding options |
+| `readTextFile(path)` | `xt_node_read_text_file` | alias of `readFileSync` (same symbol) |
+| `writeFileSync(path, data[, options])` | `xt_node_write_file` | overwrite write; accepts a string or a `Buffer` |
+| `appendFileSync(path, data[, options])` | `xt_node_append_file` | append write; accepts a string or a `Buffer` |
+| `existsSync(path)` | `xt_node_exists` | whether it exists, returns a boolean |
+| `readdirSync(path[, options])` | `xt_node_read_dir` | directory entry names; `{ withFileTypes: true }` returns `Dirent`s, `{ recursive: true }` recurses |
+| `mkdirSync(path[, options])` | `xt_node_mkdir` | create a directory; `{ recursive: true }` creates recursively, `{ mode }` is honoured |
+| `rmSync(path[, options])` | `xt_node_rm` | delete a file/directory; `{ recursive: true }` deletes recursively |
+| `rmdirSync(path[, options])` | `xt_node_rmdir` | delete an empty directory |
+| `unlinkSync(path)` | `xt_node_unlink` | delete a file |
+| `renameSync(oldPath, newPath)` | `xt_node_rename` | rename / move |
+| `copyFileSync(src, dest[, flags])` | `xt_node_copy_file` | copy a file; honours `COPYFILE_EXCL` |
+| `cpSync(src, dest[, options])` | `xt_node_cp` | recursive copy; `recursive`, `force`, `errorOnExist`, `dereference`, `preserveTimestamps` |
+| `realpathSync(path)` | `xt_node_realpath` | resolve to an absolute path |
+| `statSync(path)` | `xt_node_stat` | file metadata object (follows symlinks) |
+| `lstatSync(path)` | `xt_node_lstat` | file metadata object (does not follow symlinks) |
+| `statfsSync(path)` | `xt_node_statfs` | filesystem statistics (`bsize`, `blocks`, `bfree`, …) |
+| `accessSync(path[, mode])` | `xt_node_access` | check accessibility |
+| `chmodSync(path, mode)` | `xt_node_chmod` | change permissions |
+| `lchmodSync(path, mode)` | `xt_node_lchmod` | change symlink permissions |
+| `chownSync(path, uid, gid)` | `xt_node_chown` | change ownership |
+| `lchownSync(path, uid, gid)` | `xt_node_lchown` | change symlink ownership |
+| `truncateSync(path[, len])` | `xt_node_truncate` | truncate a file |
+| `utimesSync(path, atime, mtime)` | `xt_node_utimes` | set access/modification time (number of seconds or a `Date`) |
+| `lutimesSync(path, atime, mtime)` | `xt_node_lutimes` | set symlink times |
+| `mkdtempSync(prefix)` | `xt_node_mkdtemp` | create a unique temporary directory |
+| `linkSync(existing, newPath)` | `xt_node_link` | hard link |
+| `symlinkSync(target, path[, type])` | `xt_node_symlink` | symbolic link |
+| `readlinkSync(path)` | `xt_node_readlink` | read a symbolic link target |
+| `opendirSync(path[, options])` | `xt_node_opendir` | returns a `Dir` (`readSync` / `closeSync` / `read` / `close`) |
+| `globSync(pattern[, options])` | `xt_node_glob` | glob matching (`*`, `?`, `[...]`, `**`), `{ cwd, withFileTypes }` |
+| `openSync(path[, flags[, mode]])` | `xt_node_open` | open a file descriptor |
+| `closeSync(fd)` | `xt_node_close` | close a descriptor |
+| `readSync(fd, buffer, offset, length, position)` | `xt_node_read` | read into a `Buffer` |
+| `writeSync(fd, data[, offset[, length[, position]]])` | `xt_node_write` | write a string / `Buffer` |
+| `readvSync(fd, buffers[, position])` | `xt_node_readv` | scatter read |
+| `writevSync(fd, buffers[, position])` | `xt_node_writev` | gather write |
+| `fstatSync(fd)` | `xt_node_fstat` | `stat` for a descriptor |
+| `fsyncSync(fd)` / `fdatasyncSync(fd)` | `xt_node_fsync` / `xt_node_fdatasync` | flush a descriptor |
+| `ftruncateSync(fd[, len])` | `xt_node_ftruncate` | truncate a descriptor |
+| `fchmodSync(fd, mode)` | `xt_node_fchmod` | `chmod` for a descriptor |
+| `fchownSync(fd, uid, gid)` | `xt_node_fchown` | `chown` for a descriptor |
+| `futimesSync(fd, atime, mtime)` | `xt_node_futimes` | `utimes` for a descriptor |
+| `watch(filename[, options][, listener])` | `xt_node_watch` | returns an emitter-shaped watcher (never fires; see [Unimplemented: `fs`](../../unimplemented/node/fs.md)) |
+| `watchFile(filename[, options], listener)` | `xt_node_watch_file` | polling-shaped `StatWatcher` (never fires) |
+| `unwatchFile(filename[, listener])` | `xt_node_unwatch_file` | stop watching |
+| `constants` | `xt_fs_constants` | `F_OK` / `R_OK` / `W_OK` / `X_OK`, `COPYFILE_*`, `O_*`, `S_IF*` (host values) |
+| `promises` | `xt_fs_promises` | the `fs/promises` facade (see [`fs/promises`](./fs-promises.md)) |
+
+## Encoding support
+
+The `options` of `readFileSync` / `writeFileSync` / `appendFileSync` may be an
+encoding string or `{ encoding: "..." }`:
+
+| Encoding | Read | Write |
+| --- | --- | --- |
+| default / `utf8` / `utf-8` / `ascii` / `latin1` / `binary` | raw UTF-8 text | write as text bytes |
+| `hex` | lowercase hex string | parse hex then write |
+| `base64` | Base64 string | parse Base64 then write |
+| `base64url` | Base64url string | parse Base64url then write |
+| `utf16le` / `ucs2` | raw bytes read as text (no UTF-16 decoding) | write as UTF-8 text |
+
+> `readFileSync` still returns a **string** by default rather than a `Buffer`,
+> even though the `Buffer` class exists, so that `console.log(readFileSync(p))`
+> keeps printing text.
+
+## `statSync` return structure
+
+Returns a plain object with numeric properties: `size`, `mode`, `uid`, `gid`, `dev`, `ino`, `nlink`, `rdev`, `blksize`, `blocks`, `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs`.
+Methods (native closures, callable): `isFile()`, `isDirectory()`, `isSymbolicLink()`, `isFIFO()`, `isSocket()`, `isBlockDevice()`, `isCharacterDevice()`.
+
+## How to call
+
+`fs` exports are reached through an `import` (or the `node:fs` alias), not as bare
+globals:
+
+```ts
+import { readFileSync, writeFileSync, existsSync } from "fs";
+
+const text = readFileSync("examples/data.txt");
+writeFileSync("/tmp/out.txt", text);
+console.log(existsSync("/tmp/out.txt"));
+```
+
+## Error handling
+
+On failure the functions **throw** a Node-shaped `Error` object carrying
+`name` (`Error`), `message`, `code` (e.g. `ENOENT`), `errno` (the numeric
+`errno`), `syscall` and `path`. `existsSync` still returns a boolean and never
+throws.
+
+```ts
+import { readFileSync } from "fs";
+try {
+  readFileSync("/does/not/exist");
+} catch (error) {
+  console.log((error as any).code); // ENOENT
+}
+```
+
+
+Known deviations are listed in [Unimplemented: `fs`](../../unimplemented/node/fs.md).

package/doc/implemented/node/http.md

@@ -0,0 +1,21 @@
+# `http`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/http.md)
+
+Location: `src/extensions/node/http/index.ts`, `runtime/ext_node/http/http.c`
+
+The server wraps a `net` server: each connection accumulates bytes until a
+complete request (request line + headers + `Content-Length` body) is available,
+then invokes the `request` listener with `req`/`res`. The client wraps a `net`
+socket, writes an HTTP/1.1 request and parses the response after the connection
+closes.
+
+| API | Notes |
+| --- | --- |
+| `http.createServer([requestListener])` | create an HTTP server |
+| `http.request(options[, cb])` | create a `ClientRequest` (`write` / `end` / `setHeader`) |
+| `http.get(url[, cb])` | issue a GET |
+
+`IncomingMessage` (`req` / response): `method`, `url`, `httpVersion`, `headers`, `statusCode`, `data` / `end` events, `setEncoding`.
+
+`ServerResponse` (`res`): `writeHead(status[, message][, headers])`, `setHeader` / `getHeader` / `removeHeader` / `getHeaders`, `write(chunk)`, `end([chunk])`, events `finish` / `close`. Responses always carry `Connection: close` (no keep-alive).

package/doc/implemented/node/net.md

@@ -0,0 +1,17 @@
+# `net`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/net.md)
+
+Location: `src/extensions/node/net/index.ts`, `runtime/ext_node/net/net.c`
+
+TCP server and client, built on the core event loop.
+
+| API | Notes |
+| --- | --- |
+| `net.createServer([connectionListener])` | create a TCP server (equivalent to the `Server` constructor) |
+| `net.connect(...)` / `net.createConnection(...)` | connect (blocking connect, then registers with the event loop) |
+| `net.isIP(s)` / `net.isIPv4(s)` / `net.isIPv6(s)` | address test |
+
+`Server`: `listen(port[, host][, cb])`, `close([cb])`, `address()`, `getConnections(cb)`, events `listening` / `connection` / `close`.
+
+`Socket`: `write(data[, cb])`, `end([data])`, `destroy()`, `address()`, `setEncoding(enc)`, `pause()` / `resume()`, events `data` / `end` / `close` / `connect` / `error`.

package/doc/implemented/node/os.md

@@ -0,0 +1,22 @@
+# `os`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/os.md)
+
+Location: `src/extensions/node/os/index.ts`, `runtime/ext_node/os/os.c`
+
+Uses `os.<name>(...)` namespace calls, lowered to `xt_os_static(<name>, argc, argv)`.
+Import the module as a namespace (`import os from "os"`) or pull in individual
+functions (`import { platform } from "os"`).
+
+| Method | Notes |
+| --- | --- |
+| `os.platform()` | `darwin` / `linux` / `win32` / ... |
+| `os.arch()` | `x64` / `arm64` / `ia32` / `arm` |
+| `os.type()` | `Darwin` / `Linux` / `Windows_NT` / ... |
+| `os.release()` | kernel version |
+| `os.endianness()` | `LE` / `BE` |
+| `os.homedir()` | user home directory |
+| `os.tmpdir()` | temporary directory |
+| `os.hostname()` | hostname |
+| `os.totalmem()` / `os.freemem()` | total / free memory (bytes) |
+| `os.cpus()` | array of CPU entries (`model` / `speed` placeholders) |

package/doc/implemented/node/path.md

@@ -0,0 +1,33 @@
+# `path`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/path.md)
+
+Location: `src/extensions/node/path/index.ts`, `runtime/ext_node/path/path.c`
+
+Uses `path.<name>(...)` namespace calls, which the compiler lowers to
+`xt_path_static(<name>, argc, argv)`. Results are produced with the POSIX `/`
+separator on every platform (Windows accepts `/`), while inputs may use native
+Windows separators: on Windows both `/` and `\` are recognised and drive
+prefixes (`C:`) are preserved, so the self-hosted compiler resolves
+drive-letter paths correctly.
+Import the module as a namespace (`import path from "path"` / `import * as path
+from "path"`) or pull in individual methods (`import { join } from "path"`).
+
+| Method | Notes |
+| --- | --- |
+| `path.join(...parts)` | join and normalize |
+| `path.resolve(...parts)` | resolve to an absolute path |
+| `path.normalize(path)` | normalize |
+| `path.dirname(path)` | directory name |
+| `path.basename(path[, ext])` | file name, optionally without extension |
+| `path.extname(path)` | extension |
+| `path.isAbsolute(path)` | whether it is an absolute path |
+| `path.relative(from, to)` | relative path |
+
+```ts
+import path from "path";
+import { basename } from "path";
+
+console.log(path.join("a", "b", "..", "c")); // a/c
+console.log(basename("/x/y/z.txt"));          // z.txt
+```

package/doc/implemented/node/process.md

@@ -0,0 +1,23 @@
+# `process`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/process.md)
+
+Location: `src/extensions/node/process/index.ts`, `runtime/ext_node/process/process.c`
+
+Method calls lower to `xt_process_call(<name>, argc, argv)`, property access to `xt_process_get(<name>)`.
+Import the object (`import process from "process"`) to reach these.
+
+| Method / property | Notes |
+| --- | --- |
+| `process.cwd()` | current working directory |
+| `process.exit([code])` | exit the process |
+| `process.uptime()` | process uptime (seconds) |
+| `process.hrtime()` | `[seconds, nanoseconds]` array |
+| `process.getuid()` | user ID (returns 0 on Windows) |
+| `process.platform` / `process.arch` | platform / architecture |
+| `process.pid` / `process.ppid` | process ID / parent process ID |
+| `process.argv` | argument array (`argv[0]` is the executable) |
+| `process.env` | environment variable object |
+| `process.version` / `process.title` | placeholder strings |
+
+> `argv` is captured by the generated `main` via `xt_set_program_args` and provided to the runtime.

package/doc/implemented/node/querystring.md

@@ -0,0 +1,20 @@
+# `querystring`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/querystring.md)
+
+Location: `src/extensions/node/querystring/index.ts`, `runtime/ext_node/querystring/querystring.c`
+
+| Function | Notes |
+| --- | --- |
+| `parse(str[, sep[, eq]])` / `decode` | parse into an object; repeated keys become arrays |
+| `stringify(obj[, sep[, eq]])` / `encode` | serialize; spaces become `+`, arrays repeat the key |
+| `escape(str)` / `unescape(str)` | percent-encode / decode (`+` decodes to a space) |
+
+Defaults: `sep = "&"`, `eq = "="`.
+
+```ts
+import { parse, stringify } from "querystring";
+
+const q = parse("a=1&b=2&b=3");      // { a: "1", b: ["2", "3"] }
+console.log(stringify({ x: "a b" })); // x=a+b
+```

package/doc/implemented/node/stream-promises.md

@@ -0,0 +1,8 @@
+# `stream/promises`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/stream-promises.md)
+
+Location: `src/extensions/node/stream-promises/index.ts`, `runtime/ext_node/stream/pipeline.c`
+
+- `pipeline(...)` drains the given streams synchronously and returns an already-resolved promise, so `await pipeline(...)` works.
+- `zlib.createGzip()` is the supported transform stage; see [`zlib`](./zlib.md).

package/doc/implemented/node/stream.md

@@ -0,0 +1,19 @@
+# `stream`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/stream.md)
+
+Location: `src/extensions/node/stream/index.ts`, `runtime/ext_node/stream/stream.c`
+
+`Readable` / `Writable` / `Duplex` / `Transform` / `PassThrough` are used as
+**global constructors** (`new Readable()` etc.); statics such as
+`stream.Readable.from(...)` are resolved through the `stream` namespace. Streams
+are EventEmitters with a **synchronous event model**: `on('data')` flushes the
+`push` buffer, and `write` delivers immediately.
+
+| Method | Notes |
+| --- | --- |
+| `push(chunk)` / `read([n])` | Readable side |
+| `write(chunk)` / `end([chunk])` | Writable side |
+| `pipe(destination)` | forward data |
+| `on('data' / 'end' / 'finish')` | events |
+| `pause()` / `resume()` / `setEncoding(enc)` / `destroy()` | flow control |

package/doc/implemented/node/test.md

@@ -0,0 +1,10 @@
+# `test`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/test.md)
+
+Location: `src/extensions/node/test/index.ts`, `runtime/ext_node/test/test.c`
+
+- `test(name, fn)` runs `fn` immediately, catches assertion failures and reports TAP output.
+- `it` / `describe` / `skip` / `todo` / `only` and the `before` / `after` / `beforeEach` / `afterEach` hooks.
+- A failure makes the process exit non-zero.
+- The default export is callable, so `import test from "node:test"` works.

package/doc/implemented/node/url.md

@@ -0,0 +1,8 @@
+# `url`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/url.md)
+
+Location: `src/extensions/node/url/index.ts`, `runtime/ext_node/url/url.c`
+
+- `pathToFileURL(path)` and `fileURLToPath(url)`.
+- These are the helpers used to relate `import.meta.url`, `process.argv[1]` and filesystem paths.