# magic-api-ts

**Repository Path**: yutel/magic-api-ts

## Basic Information

- **Project Name**: magic-api-ts
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-16
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于 magic-api 的 TS 类型增强

> 在 **magic-api 2.2.2** 的脚本编辑器（magic-editor）里，为 `magic-script` 语言叠加了一套 **TypeScript 风格的类型系统 + WebStorm 风格编辑体验**：
> 类型补全、实时类型检查、一键快速修复、语义着色、inlay 参数名、CodeLens 引用统计、实时模板、符号导航等。
>

---

## 目录

1. [功能总览](#一功能总览)
2. [TS 类型系统](#二ts-类型系统)
3. [智能补全](#三智能补全)
4. [实时类型检查（波浪线报错）](#四实时类型检查波浪线报错)
5. [快速修复（Ctrl + Enter）](#五快速修复ctrl--enter)
6. [hover 类型提示与 Ctrl+点击 跳转](#六hover-类型提示与-ctrl点击-跳转)
7. [WebStorm 风格编辑体验](#七webstorm-风格编辑体验)
8. [意图操作（Code Action）](#八意图操作code-action)
9. [错误波浪线增强](#九错误波浪线增强)
10. [性能优化](#十性能优化)
11. [快捷键速查](#十一快捷键速查)

---

## 一、功能总览

编辑器在 `magic-script` 语言上叠加了一套**前端类型系统** + **WebStorm 风格编辑体验**，整体链路：

**① 输入即提示（补全）**
- `type` 字段值 / lambda 参数 / 返回类型 → 类型补全
- 对象字面量 `return {` / `const x = {` → 字段名补全（含嵌套递归）
- `import '@type/xxx' as asd` → 模块类型补全（`asd.Demo`）

**② 实时校验（doValidate）**
- 类型检查：结构比较、any 通配、数组、返回类型
- 语法检查：缺逗号等 → 波浪线 + 错误列表

**③ 一键修复（Ctrl + Enter）**
- 插入逗号 / 创建缺失字段 / 移除注解

**④ hover 与跳转**
- hover 查看结构 / Ctrl+点击跳转模块类型

**核心能力一句话**：写 `magic-script` 就像写 TS —— 有类型、有提示、有检查、有修复，还有 WebStorm 式的编辑手感。

---

## 二、TS 类型系统

### 2.1 `type` 类型定义

用 `type` 关键字定义**结构化类型**（字段 + 类型），是整套类型系统的基础：

```javascript
type Address = {
    city: string,
    zip: string
}

type Demo = {
    name: string,
    age: number,
    address: Address,       // 引用同文件类型
    test?: string,          // 可选字段（?:）
    data: Data | null       // 联合类型（|）
}
```

**示例效果**：
- 给 `address` 字段补全时，提示 `Address`、`string`、`number` 等
- 定义 `type Demo<T = Address>` 支持**泛型**与默认值

### 2.2 引入类型模块（`import '@type/...'`）

magic-api 把类型资源放在 `@type` 下，用 import 引入后即可当类型用：

```javascript
import '@type/demo/Demo' as Demo

// 写法一：直接作为类型注解
const config: Demo = {
    name: "张三",
    age: 18,
    address: { city: "北京", zip: "100000" }
}

// 写法二：as 断言（Cast）
const data = { ... } as Demo
```

> 类型模块别名必须以大写字母开头（`import ... as demo` → 会爆红提示改为 `Demo`）。

### 2.3 可选字段 / 泛型 / 默认值

```javascript
// 泛型：T 默认是 Address
type Box<T = Address> = {
    value: T,
    label?: string          // 可选字段，赋值时可省略
}

// 实例化
const b1: Box = { value: { city: "上海", zip: "200000" } }
const b2: Box<string> = { value: "hello" }
```

---

## 三、智能补全

### 3.1 type 字段值类型补全

光标停在类型字段值位置，**只提示类型名**（不混入变量/方法噪音）：

```javascript
type Demo = {
    name: █        // ← Alt + / 提示：string / number / boolean / Address / Demo...
}
```

### 3.2 对象字面量字段补全（含嵌套）

在 `return {` 或 `const x = {` 里，自动补全已知类型的字段，**嵌套递归**：

```javascript
const config: Demo = {
    █               // ← 提示：name / age / address / test / data
    address: {
        █           // ← 进入嵌套，提示：city / zip
    }
}
```

### 3.3 模块类型补全

```javascript
import '@type/testType/TestTs' as asd

const config: asd.█ = {}    // ← 提示：Demo、Address、Other...
```

### 3.4 lambda 参数 / 返回类型补全

```javascript
const fn = (val: █                // ← 提示：string / number / 自定义类型
const fn = (val: string): █ =>    // ← 提示：TestTs.Demo 等返回类型
```

### 3.5 变量 / 函数补全带文档

补全项附带**类型说明**（documentation），悬停补全项右侧显示类型结构。

### 3.6 实时模板（Live Templates）

输入缩写自动补全代码片段（WebStorm 风格）：

| 缩写 | 生成 |
|---|---|
| `log` / `logd` / `loge` / `logt` | `log.info` / `log.debug` / `log.error` / `log.trace` |
| `try` / `tryf` | `try { } catch (e) { }` / `try { } finally { }` |
| `for` / `forin` / `fori` | for 循环 / for-in / 带索引的 for |
| `if` / `ife` | `if` / `if-else` |
| `db` / `json` / `list` / `map` / `sw` | 常用结构 |

**示例**：输入 `try` 后回车：

```javascript
try {
    █
} catch (e) {
    █
}
```

---

## 四、实时类型检查（波浪线报错）

输入过程中**实时校验**，错误标红色波浪线，未使用标黄色：

```javascript
// 缺少必填字段 → 爆红
const obj: Demo = {
    name: "张三"        // ← 缺少属性：age、address
}

// 字段类型不匹配 → 爆红
const obj2: Demo = {
    name: 123,          // ← 变量「name」类型不匹配：期望 string，实际 number
    age: 18
}
```

支持的结构比较：**精确结构、any 通配、数组与混合数组、函数返回类型**。

```javascript
// any 通配：任意类型都兼容
type Loose = { id: any }
const ok: Loose = { id: { anything: true } }   // ✓ 不报错

// 数组类型检查
type List = { items: string[] }
const bad: List = { items: [1, 2] }            // ← 期望 string[]，实际 number[]

// 缺逗号 → 爆红「缺少逗号」
const x = { a: 1 b: 2 }                        // ← Expected ',', but got 'b'
```

---

## 五、快速修复（Ctrl + Enter）

把光标放在错误上按 `Ctrl + Enter`，一键修复：

| 错误 | 修复动作 |
|---|---|
| 缺逗号 | 自动插入逗号 |
| 缺少必填字段 | 一键补全所有缺失字段（含嵌套） |
| 返回类型不匹配 | 创建缺失字段 / 移除返回类型注解 |
| 变量类型不匹配 | 移除类型注解 |
| 未使用变量/导入 | 一键移除 |

**示例**：光标在 `obj` 的 `name` 行按 Ctrl+Enter：

```javascript
const obj: Demo = { name: "张三" }
// ↓ 一键补全后
const obj: Demo = {
    name: "张三",
    age: null,
    address: { city: null, zip: null }
}
```

---

## 六、hover 类型提示与 Ctrl+点击 跳转

### 6.1 hover 显示类型结构

悬停变量/字段，弹出**类型结构**（多行格式化 + 命名类型展开）：

```javascript
const config: Demo = { ... }
// hover config → { name: string, age: number, address: Address, data?: Data }
```

### 6.2 命名类型引用点击就地展开

hover 里出现**可点击的类型名**（如 `Address`），点击**就地展开**结构，不用跳走：

```javascript
// hover 到 config.address 时：
//   address: Address  ← 可点击，点击展开 { city: string, zip: string }
```

### 6.3 Ctrl + 点击 跳转

- `import '@type/demo/Demo' as Demo` → Ctrl+点击路径打开类型资源
- 本地定义 `type` / `const` → Ctrl+点击跳转定义
- 字段引用 → Ctrl+点击查看引用 / 跳转

---

## 七、WebStorm 风格编辑体验

### 7.1 语义着色（semantic tokens）

基于 AST 精确区分类型/函数/字段/参数（Monarch 词法无法可靠区分函数调用与成员字段）：

```javascript
import '@type/demo/Demo' as Demo      // Demo → 类型色(加粗)
import '@/func/func1' as func1        // func1 → 函数色

const config: Demo = {                // config → 变量色
    name: null,                       // name → 字段色
    ...
}

const fn = (a, b) => a + b            // a/b → 参数色(斜体)
const list = db.select(...)           // db/log/map → 内置函数(斜体)
```

| 语义 | 示例 | 效果 |
|---|---|---|
| 类型 | `Demo`、`type` 注解、`as Demo` | 类型色 + 加粗 |
| 函数 | `func1(...)`、`@/` import 别名 | 函数色 |
| 字段 | 对象属性 `name:`、成员 `.address` | 字段色 |
| 参数 | lambda `(a, b)` | 参数色 + 斜体 |
| 内置函数 | `db`/`log`/`map`/`list` | 斜体 |

### 7.2 inlay 参数名提示

函数调用实参前**淡色显示形参名**：

```javascript
func1(a: 123, b: 1, c: "123")
//      ^      ^      ^   ← 参数名提示
```

### 7.3 参数提示自动触发

输入 `(` 自动弹出函数签名 + 参数类型 + 返回类型，无需手动按快捷键。

### 7.4 CodeLens（引用数 / 调用次数）

类型/函数/变量定义处显示统计，**点击「N 个引用」跳转到下一个引用位置**：

```javascript
2 个引用            被调用 2 次          2 个引用
import '@type/demo/Demo' as Demo   import '@/func/func1' as func1   const config: Demo = ...
```

- 未使用的变量 → 「未使用」；未调用的函数 → 「未调用」

### 7.5 符号导航（Ctrl + Shift + O）

弹出文档符号列表（类型定义 + 顶层变量），输入过滤、点击跳转：

```
config (variable)
Base   (class)
Demo   (class)
```

> 面包屑（breadcrumbs）monaco standalone 不支持，用符号导航替代。

### 7.6 括号彩虹色 / 引导线 / sticky 标题

- 括号彩虹配色 + 括号/缩进引导线
- 滚动时顶部固定显示结构标题（sticky scroll）

---

## 八、意图操作（Code Action）

### 8.1 Surround with

选中一段代码，包裹进控制结构：

```javascript
// 选中 `list.forEach(...)`，选 Surround with try-catch：
try {
    list.forEach(...)
} catch (e) {
    █
}
```

支持：`if` / `try-catch` / `for` / `while`。

### 8.2 提取变量

```javascript
// 选中表达式 `config.name.toUpperCase()`，选「提取变量」：
const extracted = config.name.toUpperCase()
```

### 8.3 生成 log.info

光标在变量上，一键插入调试日志：

```javascript
// 光标在 config 上：
log.info("config: {}", config)
```

---

## 九、错误波浪线增强

- **所有语法错误**红色波浪线（缺逗号、缺少括号等，显示原始错误消息）
- 类型错误红色、未使用警告黄色
- 悬停错误显示详情

**示例**：

```javascript
const x = { a: 1 b: 2 }    // ← 红色波浪线「缺少逗号」
const unused = 1            // ← 黄色警告「未使用的变量」
```

---

## 十、性能优化

| 优化 | 说明 |
|---|---|
| AST 单槽缓存 | 同一脚本内容复用解析结果（`script-cache.js`） |
| 类型模块 fetch 节流 | 2 秒内不重复拉取类型模块 |
| 校验防抖 | 输入后 250ms 才触发全量校验 |
| 编辑中容错 | 未闭合字符串等解析失败不抛错（语义着色临时降级），语法错误仍由校验标记波浪线 |

---

## 十一、快捷键速查

| 快捷键 | 功能 |
|---|---|
| `Alt + /` | 触发代码补全 |
| `Ctrl + Enter` | 快速修复光标处错误 |
| `Ctrl + Shift + O` | 符号导航（类型/变量列表） |
| `Ctrl + 点击` | 跳转模块类型 / 本地定义 / 资源 |
| `Alt + 1` | 光标变量下方插入 log 调试 |
| `Ctrl + Alt + L` | 格式化文档（含 SQL 三引号） |
| `Ctrl + F8` | 跳转到下一个错误 |
| `F2` | 重命名变量 |
| hover | 查看类型结构 / 命名类型点击展开 |