# TypeScript

类型注解会先擦掉、再交给 JavaScript 后端 —— 写法是 «bold»JavaScript 子集 + 类型外壳«/»。

## 在手机上怎么跑

```
vml run examples/typescript/school/binary_search.ts
```

编译要等一会儿（C 那种要一两分钟，脚本类语言几秒）。程序跑起来后**屏幕底部就是手柄**，
方向键 + 四个动作键都在；点右上角返回可以回到命令行。

## 写法要点

- 类型注解 / `interface` / `type` / `enum` / `as` 都能写，擦掉后不影响运行
- 对象字段（`p.name`）暂时按整数打印，«bold»别指望它当字符串«/»
- `for...of`、类实例方法调用«bold»编不过«/» —— 它们是 JS 子集的限制，不是 TS 的
- 定义 `function main()` 之后记得手动调用一次

## 示例

| 文件 | 演示什么 |
|---|---|


同目录还有：`school/NOTICE.md`、`school/README.md`、`school/binary_search.ts`、`school/bubble_sort.ts`、`school/class_demo.ts`、`school/fibonacci.ts`、`school/fizzbuzz.ts`、`school/hanoi.ts`、`school/palindrome.ts`、`school/types_demo.ts`

---

下面的内容是**从 VML 源码里直接带的**（`third_party/vml/VMLPrepares/TypeScriptCompiler/`）：
`README` 讲这个前端支持什么、怎么编；`语言规范` 讲语法本身。
上游一改，这里重新生成就是最新的。

## 语言规范

### TypeScript 语言支持规范（VML 前端）

> 版本：v1.66.470 起
> 前端：`VMLPrepares/TypeScriptCompiler/`
> 后端：`VMLPrepares/JavaScriptCompiler/`（类型擦除后复用）

#### 1. 架构

```
.ts 源码
   │  TypeScriptCleaner（逐 token 擦除类型层，等长替换、保留换行）
   ▼
JS 子集源码 + TypeHints（形参类型 / 返回类型 / interface 布局）
   │  JavaScriptCompiler（带类型提示）
   ▼
VML 汇编
```

##### 1.1 类型提示

| 提示 | 用途 |
|---|---|
| `TypeHintParams` | 形参声明类型；`string` ⇒ 字符串拼接与打印；`number` ⇒ 整数模型 |
| `TypeHintReturns` | 返回值类型；`string` ⇒ 调用点按字符串打印 |
| `TypeHintShapes` | interface 属性顺序与类型；对象字面量布局与 `obj.prop` 偏移 |
| `TypeHintFields` | 类实例字段类型（注解/参数属性）；`p.name` / `this.name` 的打印与拼接 |

`number` «bold»不映射为 F32«/»：JS 后端的整数字面量生成 `MOVE @R0 #25`，
按浮点打印会得到 0。小数仍由字面量自身的 F32 推断负责。

##### 1.2 行号保持

擦除是"等长空白替换"，只替换 token 文本、不删换行。因此链接/解析错误
报出的 `<input>:行号` 与 `.ts` 源文件一致。

#### 2. 语法覆盖

##### 2.1 类型层（全部擦除）

- 类型注解：变量、形参、返回值、catch 形参、类字段
- `interface` / `type` 别名 / `declare`
- 泛型：函数、方法、类、调用处类型实参
- `as T`、`satisfies T`、`x!`
- 可选/确定标记 `?` / `!`
- 类成员修饰符：`public private protected readonly override abstract declare`
- `implements` 子句、`abstract class` 的 `abstract` 关键字
- `import` / `export` 全部形式

##### 2.2 有运行时语义的翻译

- «bold»enum«/»：`enum E { A, B = 5, C }` → `var E = { A: 0, B: 5, C: 6 };`
  - 支持字符串枚举与引用前一成员（`C = B` → `E.B`）
  - `const enum` 的 `const` 一并擦除
- «bold»class 实例字段初始化«/»：`x: number = 5;` 注入到构造函数开头；
  若类没有显式构造函数则生成一个。有 `super(...)` 时注入在其后。
- «bold»构造函数参数属性«/»（v1.66.471）：`constructor(public x: number, readonly id: T)`
  擦除修饰符、保留形参，并注入 `this.x = x;` / `this.id = id;`。
- «bold»`#private` 字段/方法«/»（v1.66.471）：编译期按类作用域改名为
  `__priv_<类>_<名>`（静态成员 `__privs_`），声明与 `this.#x` 一致；
  `#x in obj` 响亮报错。
- «bold»类字段类型提示«/»（v1.66.471）：`TypeHintFields` 让 `p.name` / `this.name`
  按 `string` 处理（打印/拼接），修前当整数打指针。
- «bold»`for (const k in obj)`«/»：静态布局对象在编译期逐属性展开；形状未知响亮报错。
- «bold»`for (const ch of "abc")`«/»：按 `strlen` 逐字节遍历，元素是 1 字符字符串。
- «bold»`label:` / `break label` / `continue label`«/»、«bold»`debugger`«/»（空语句）。
- «bold»尾随逗号«/»（v1.66.472）：数组/对象/实参/形参列表允许 `, ]` / `, }` / `, )`。

##### 2.3 复用 JavaScript 运行语义

函数、控制流、数组、对象字面量、类（构造函数 + 方法 + 继承）、模板字符串、
`for...of`、字符串方法、`console.log` / `print`、共享标准库 —— 全部由
JavaScript 后端提供。TypeScript 特有的 `interface` 只影响编译期布局，
不产生运行时对象。

- «bold»模板字符串«/»：`` `hi ${name}!` `` 的插值按类型转换成字符串后拼接
  （数值走 `int_to_str`/`float_to_str`，布尔走 `bool_to_str`）。
- «bold»`for (const x of arr)`«/»：按数组长度头遍历；支持 `break`/`continue`
  与循环头作用域。
- «bold»可选形参 `b?: T`«/»：`?` 只是类型层标记，«bold»调用时省略实参«/»无法表达
  `undefined`。请写默认值（`b: T = …`）或显式哨兵值，不要依赖缺省实参。

#### 3. 明确不支持（编译期报错）

| 构造 | 报错文本要点 |
|---|---|
| `a?.b` | `` `?.` 暂不支持 `` |
| `a ?? b` / `a ??= b` | `??` 暂不支持（null 与 0 不可区分） |
| `namespace` / `module` | 命名空间暂不支持 |
| `@Decorator` | 装饰器暂不支持 |
| `const C = class { … }` | 类表达式暂不支持 |
| `static x = …`（非字面量） | 静态字段初始化暂不支持 |
| `get`/`set` 访问器 | 访问器暂不支持 |
| `async`/`await` | MCU 模式跳过 async/await |
| `yield` / `function*` | 生成器不在 MCU 子集内 |
| `with (o) { … }` | `with` 暂不支持 |
| 基类方法内调用抽象/被覆写方法 | 需要运行时虚分派，暂不支持 |
| `#x in obj` | 仅支持成员声明与 `this.#x` 访问 |

依据项目原则：«bold»宁可在编译期响亮失败，也不产出静默错值«/»。

#### 4. 与 JavaScript 前端的差异

- `.ts` 扩展名经 `VMLTool` 自动分派到 `typescript` 语言目录（`Lib/typescript/`）。
- TS 额外提供 `__TYPESCRIPT__` / `__TS__` 预定义宏。

#### 4.5 标准库

`Lib/typescript/` 与 JavaScript 标准库同源（71 个模块包装器）。此外
`JavaScriptCompiler/JsStdlibApi.cs` 提供 «bold»27 个语言惯用名«/»到已有包装器/共享库标签的
映射，按 `native`（`__stdcall`）约定调用，且不覆盖用户同名函数：

| 类别 | 惯用名 |
|---|---|
| 时间/随机 | `sleepMs` `delayMs` `millis` `timestamp` `randomInt` `setSeed` `nowDate` `nowTime` |
| 运行环境 | `configValue` `keyPressed` `setRTC` `speakerBeep` |
| EEPROM | `eepromRead` `eepromWrite` |
| 文件 | `fileOpen` `fileClose` `fileRead` `fileWrite` `fileSeek` `fileTell` `fileSize` `fileTruncate` |
| 文件系统 | `fs_mkdir` `fs_remove` `fs_rename` `fs_readdir` `fs_stat` |

C 标准库族（`abort`/`fprintf`/`fgetc`/`clock`/`gmtime`/`cstd_file_*` …）经
`SharedExactSymbolMap` 自动链接 `Lib/shared/cstdlib.vml`。
- 注解驱动的类型提示使 TS 在字符串拼接、字符串返回、interface 对象布局上
  比 JavaScript 的纯静态推断更准确。

#### 5. 测试

- `VMLTests/Lang_TypeScript.cs` — 28 项功能/报错用例
- `VMLTests/Probe_2026_11_08_TypeScript.cs` — 42 项全特性探针：
  所有运算符 / 控制语句 / 关键字、类（基本/继承/多态）、标准库行为，
  以及 «bold»81 个面向用户函数 + 1383 个 native 绑定«/»的穷举链接探针。
- JavaScript 后端改动同时跑 `Lang_JavaScript` 与全部 `~JavaScript` 回归。

## 编译器 README

### TypeScript 编译器

«bold»路径«/»: `VMLPrepares/TypeScriptCompiler/`
«bold»后端«/»: 类型擦除后复用 JavaScript 后端（`JavaScriptCompiler`）
«bold»标准库«/»: `Lib/typescript/`（与 `Lib/javascript/` 一一对应，由 GenLib 生成）

#### 实现方式

TypeScript 的«bold»类型层«/»（interface / type 别名 / 泛型 / 类型注解 / `as` / `!`）
由 `TypeScriptCleaner` 按«bold»字符位置«/»擦除 —— 替换成等长空白、«bold»换行原样保留«/»，
因此编译错误里的行号与用户源码一致。擦除后的代码交给 JavaScript 前端编译。

注解不是完全丢弃：`string` / `number` 等形参与返回类型会作为«bold»类型提示«/»传给
JS 后端（`TypeHintParams` / `TypeHintReturns` / `TypeHintShapes`）。
没有这层提示，`function greet(name: string): string { return name + punct; }`
里的 `+` 会被当成整数相加（输出指针和）、返回值按整数打印（输出 65570）。

interface 的«bold»属性顺序与类型«/»也会传给 JS 后端（`TypeHintShapes`），
对象字面量因此按静态布局 `[count, v0, v1, …]` 分配，`p.x` 按偏移读取。

#### 支持的特性

| 特性 | 处理 |
|---|---|
| `let/const x: T` 注解 | 擦除类型，保留初始化表达式 |
| interface / type 别名 | 整体擦除；interface 属性布局作为运行时提示 |
| enum（数字/字符串/自动递增/引用前一成员） | 改写为 `var E = { A: 0, … };` |
| 泛型函数/类声明与调用（`pick<T>` / `pick<number>(…)`） | 声明处擦除 `<T>`，调用处擦除 `<…>` |
| `as T` / `satisfies T` | 擦除 |
| `x!` 非空断言 | 擦除 |
| 可选形参 `b?` / 可选属性 `x?` | 擦除 `?` |
| class 成员修饰符 `public/private/protected/readonly/override/abstract/declare` | 擦除 |
| class 实例字段初始化 `x: number = 5;` | 注入到构造函数开头（无构造函数则创建） |
| `import` / `export` 各种形式 | 整条擦除 |
| `declare` 声明 | 整条擦除 |
| `catch (e: T)` | 擦除注解 |
| constructor 参数读取 | 参数顺序/类型提示（v1.66.470） |
| 构造函数参数属性 `constructor(public x: T)` | 擦修饰符 + 注入 `this.x = x;`（v1.66.471） |
| `#private` 字段/方法 | 按类作用域改名为 `__priv_<类>_<名>`（v1.66.471） |
| 类字段类型注解 | `TypeHintFields`：`p.name` 按字符串打印/拼接（v1.66.471） |
| 模板字符串 `` `hi ${x}` `` | 插值转换成字符串后拼接 |
| `for (const x of arr)` | 数组遍历；字符串按 strlen 逐字符；支持 `break`/`continue` |
| `for (const k in obj)` | 静态布局对象编译期展开；`o[k]` 读已知槽位 |
| 解构（数组/对象、`{ k: v }`） | 复用 JS 后端（v1.66.470 修复） |
| 类继承 `extends` / `super()` / `super.m()` | 复用 JS 后端；隐式构造函数按父类形参转发 |
| `label:` / `break label` / `continue label` | v1.66.471 |
| `debugger` | 按空语句（MCU 无调试器） |
| 尾随逗号 `[a, b,]` / `f(x,)` / `{a:1,}` | v1.66.472 支持的清单语法 |
| 全部运算符 | 含 `«bold»`、`>>>`、`«/»= <<= >>= >>>= &= |= ^=`、`void`、`delete`、`in`、`instanceof` |

#### 标准库

`Lib/typescript/` 与 JS 标准库同源，另加 «bold»27 个语言惯用名别名«/»（`sleepMs` /
`millis` / `randomInt` / `nowDate` / `keyPressed` / `fileOpen…` / `fs_*` …），
由 `JavaScriptCompiler/JsStdlibApi.cs` 映射到已有包装器标签。
«bold»81 个面向用户函数«/»与 «bold»1383 个 native 绑定«/»均有穷举链接探针。

#### 明确不支持（«bold»响亮报错«/»，不静默降级）

- `?.` 可选链、`??` / `??=` 空值合并（null 与 0 在本仓不可区分）
- `namespace` / `module`
- 装饰器 `@Decorator`
- 类表达式（`const C = class { … }`）
- 静态字段初始化表达式（`static x = …`）
- `get`/`set` 访问器（属性访问不会调用方法，改写为普通方法）
- `async` / `await`、`yield` / `function*`、`with`
- 抽象/覆写方法在«bold»基类方法内部«/»的调用（需要运行时虚分派）
- 对象数组元素上的«bold»方法«/»调用（`arr[i].m()`）—— 元素类别需运行时类型；
  字段读取 `arr[i].x` 与带类型变量的方法调用正常
- 省略可选实参（`b?: T` 的 `?` 只在类型层；请写默认值）

#### 使用

```bash
dotnet run --project VMLTool -- input.ts -o output.vml
dotnet run --project VMLEmulators/ConsoleEmulator -- -r output.vml
```

`VMLTool` 会自动把 `.ts` 映射到 `typescript` 语言目录；也可显式
`-x typescript`。保存中间 JS 便于排查：`VML_TS_DUMP=/tmp/x.js`。

#### 测试

- `VMLTests/Lang_TypeScript.cs`（28 项）：类型擦除、interface 对象布局、
  字符串注解、enum、泛型、类、import/export、行号保持、不支持特性的报错。
- `VMLTests/Probe_2026_11_08_TypeScript.cs`（42 项）：«bold»所有运算符/控制语句/关键字«/»、
  类（基本/继承/多态）、标准库行为，以及 81 个用户函数 + 1383 个 native 绑定的
  穷举链接探针。
- `VMLTests/Regress_2026_11_08_TypeScript.cs`（12 项）：共享 JS 后端回归。
