 what
|
0c947dde70
|
docs: 加一篇函数流走向
call-flow.md 讲的是三个阶段各自在做什么，缺的是**函数之间怎么串起来的**——
想改代码、想知道加一层该加在哪，没有一处能查。
docs/flow.md 七张图：
全景 公开 API → 注册表 / 取 VM / 调用 三条链
runner 三态 Script / Instance / staticTarget 的 acquire+finish 差别，
「同一实例串行」就是 acquire 到 finish 之间一直持着 i.mu
newVM 内部 为什么 scope 是显式参数而不是从 ctx 嗅
作用域进 VM WithScope → vmGlobals → bind → lazyGlobal → freeze 五跳，
这是全库最容易看不清的一条链
invoke 内部 含 defer 的注册顺序（finish → stop → recover，后进先出）
lookup 三级 exports → ctor 静态 → 全局兜底，解释了 Script.Has 为什么
对静态方法也返回 true
编译链 Prepared 为什么不是优化开关而是正确性要求
写的时候实地核对了每条断言，抓出三处我自己写错的：
1. 图上把 Bundle → FinalizeBundle 画成两步，实际 Bundle 末尾自己就调了
2. 把「省 44% 常驻内存」归因给惰性注入——那是关掉 console 的收益
3. 「只读全局赋值静默失败」只对全局本身成立，freeze 拷出来的嵌套只读属性
（store.Set = null）实测是抛错的
顺带修一处上一轮改名的残留：engine.go 的注释还指着 lazyglobal_test.go。
|
2026-09-10 16:24:18 +08:00 |
|
|
what
|
6477b27ef4
|
docs: 校对 README 和 docs，改掉三处跟代码对不上的
不是全面重写——文档里不指向具体源文件，所以上一轮的改名没波及它们。逐条核对
「文档提到的 API」和「实际导出」之后，只有三处不符：
README 的哨兵错误列表 多了 ErrUnsupportedSignature（这轮删了），
少了 ErrInterrupted（一直都有）
call-flow.md 的 freeze 说白名单「逐层拷贝成只读对象，否则同一个 Go map 会被
所有 VM 共享」——那只对 map[string]any 成立。结构体
指针和 slice 走 rt.ToValue，是**共享同一个对象**的。
扩展走的正是这条路，不该被当成隔离保证。
（doc.go 里同一处上一个 commit 已经改过）
lifecycle.md 的状态图 写着 [*] --> 池中: newVM()，但 newVM 产出的 VM 是
直接借出去用的，回池要等 release
错误分类那张表（KindTimeout/KindCanceled/KindPanic/KindRuntime）核对过，没有
KindSignature，不受这轮删除影响。
|
2026-09-10 15:51:48 +08:00 |
|
|
what
|
98eb734caa
|
docs: 把能力面摆出来，更新性能数字
起因是「不知道有什么功能」——公开 API 有 14 个类型、17 个 With* 选项，全部平铺
在同一层文档里，看不出哪些是必须懂的。
doc.go 和 README 顶部都加了分层的能力清单：核心五个概念（Engine / Script /
Instance / Scope / Extension，覆盖九成用法），加上「用不到就不用看的」四类。
同时写清楚明确**不做**的三件事：不代管实例生命周期、没有事件循环、不提供沙箱隔离
（脚本能拿到你放行的 Go 对象，它们的方法是真能调的）。
性能数字重测了一遍。InstanceCall 454 → 300 ns——删掉 lastUsed 省下的两次
time.Now() 兑现了。
顺带加了一句测量方法的提醒：这些数字取的是多轮**最小值**。我这轮一度以为
Script.Call 退化了 27%，逐个 commit 二分下去发现跳变落在一个只删死代码和改注释
的 commit 上——那不可能影响调用路径。加大样本后两边最小值持平，是机器噪声。
中位数会被离群值带偏，微基准在有别的负载时能飘 30%。
|
2026-09-10 15:44:19 +08:00 |
|
|
what
|
7c9a70712e
|
test: 测试文件跟源文件同名，删掉复制粘贴出来的重复
改完之后「某个行为在哪测」就是查同名文件：
lazyglobal_test.go → engine_globals_test.go
static_test.go → script_static_test.go
scope_pool_test.go → script_vm_test.go 它测的是 VM 池，不是作用域
esmwrap_test.go → bundle_finalize_test.go
missing_global_test.go → errors_hints_test.go
entry_test.go → bundle_entry_test.go 并收下 bundle_test.go 里
那三个 TestEntry_*
删掉 5 组复制粘贴。其中 TestNew_同实例调用串行 和 TestInstance_调用串行 **函数体
完全一致**，只差 mustCompile 的文件名参数 counter.js / counter.ts。Instance 的
测试全部归 instance_test.go 并统一前缀成 TestInstance_，scope_test.go 只留作用域。
vmstate_test.go + govalue_test.go → goja_facts_test.go。这两个测的都是 **goja
本身**，不是这个库：Program 能不能给多个 Runtime 共用、顶层变量跟不跟 Runtime 走、
Go 的切片进到脚本里是不是真数组。它们是「为什么这个库要这么设计」的实验记录，
goja 行为变了会先红。原来那个名字看不出这层定位。
helper 集中到 helper_test.go：newEngine / mustCompile 被十几个文件依赖，原来住在
script_test.go 里，那个名字暗示「测 Script」，找不到。
caller_example_test.go 并进 caller_test.go——同一个类型没必要两个文件。
overlay_test.go 和 script_vm_test.go 保持内部测试，各写了一句为什么：前者要读
Engine.loader 和 isPrepared，后者要直接断言 vmHandle.scoped。我试过把 overlay
挪成外部测试，挪不动。
|
2026-09-10 15:39:25 +08:00 |
|
|
what
|
7e1893b246
|
refactor: 文件按主类型划分，一个 struct 一个功能
约定：文件名 = 主类型名；同一个类型要拆多个文件时用 类型_子项.go。
engine.go 355 → 231 行。原来混了三件不相干的事
engine_globals.go ← bind / lazyGlobal / freeze / defineReadOnly（96 行）
它是「Go 值 → 只读 JS 全局」的转换层，跟脚本缓存毫无关系
engine_console.go ← console.go，跟上面是同一主题
script.go 325 → 100 行，只留公开方法
script_vm.go ← VM 的取、还、装载。上个 commit 合一的三条路径现在住一起
script_static.go ← static.go
errors.go 364 → 150 行
errors_goja.go ← goja 错误的翻译层
errors_hints.go ← missingGlobalHint，一份 JS 运行时知识库，跟错误分类是
两回事；拆出来之后 missing_global_test.go 才有对应源文件
bundle_finalize.go ← esmwrap.go
bundle.go 收下 validIdent / hashVersion（原来住在 engine.go）
Engine.New 原来排在所有私有函数之后，挪到导出方法那一段。
classify 83 → 54 行：四个 errors.As 分支各手搓一个 8 字段的 &Error{}，脚本上下文
那三行重复了 4 遍，抽出 gojaError 构造器。
顺带修四处注释漂移：
Session/会话 代码里叫 Instance，注释里大面积残留。engine_globals.go 那条
「注入会话全局对象失败」还是用户可见文案，而公开 API 里根本
没有「会话」这个概念
Extension 文档示例写 Module() string，接口是 Module() (path, source string)。
这是唯一一段教人写扩展的文档，照抄编译不过
doc.go 的 freeze 说白名单「逐层拷贝成只读对象，不会跨 VM 共享可变的 Go map」，
但那只对 map[string]any 成立。结构体指针和 slice 是**共享同一个
对象**的——扩展走的正是这条路，不该被当成隔离保证
|
2026-09-10 15:28:59 +08:00 |
|
|
what
|
1f25425762
|
refactor: 取 VM 的三条路径合一，newVM 成为唯一入口
borrow（池化）、ensure（实例）、borrowStatic（静态）各自写了一遍「取作用域 →
拼 extra → 建 Runtime → load」。borrowStatic 甚至把 newVM 逐行抄了一遍，只为把
noInstance 传成 true。
结果就是规则会漏：上一个 commit 修的「borrowStatic 没标 scoped」正是这么来的。
现在三条都走 newVM，作用域注入和 scoped 标记只有一份。
顺带删掉两处无意义的间接：
loadInto s.load(ctx, rt, ctorArgs, false) 的单行包装，只被 newVM 调一次
newRuntime 它的 scope 参数两个调用点都传 s.name，而注释描述的「会话 VM 用
会话 key」这条路径根本没实现（作用域 key 走的是 vmGlobals）。
参数名还跟同包的 type scope struct 撞名
**scope 是显式参数，不是从 ctx 嗅的**——这一点差点被我改坏：Instance 重建 VM
时要回到它**创建时**那个作用域，而不是当次调用 ctx 里的。对一个作用域实例调
Call(context.Background()) 不该把它的扩展弄丢。加了
TestScope_实例重建VM后仍在原作用域 守这条，用超时逼出 VM 重建（第一版用抛异常，
那不会丢 VM，两种写法都通过，等于没测）。
|
2026-09-10 15:25:12 +08:00 |
|
|
what
|
111665d2e7
|
fix: HasStatic 让 Stats 越用越偏；borrowStatic 漏标 scoped
两个都是静态调用那条路上的。
HasStatic 建了 VM 却不记丢弃。Created 在 load 里加（所有建 VM 的路径都走它），
Dropped 在 staticTarget.finish 里加，而 HasStatic 拿到 VM 后直接返回，不走
finish。每调一次 Created-Dropped 就永久 +1——Stats 是导出的观测结构，这个
偏差会直接体现在监控上。改成走同一套记账。
borrowStatic 同样会注入作用域扩展，却不设 vm.scoped。release 靠这个标志拒绝
把带扩展的 VM 放回池子，漏标就是跨调用泄漏。今天不出事只是因为
staticTarget.finish 永远丢弃——同一个约束靠两套机制守，以后有人把静态 VM
接进 release 就会漏。
测试：
- Stats 那条断言「在飞的 VM 数」调用前后不变
- scoped 那条是**内部测试**，直接断言标志位。行为测试盖不住它——borrowStatic
那条路今天靠 finish 兜底，从外面看不出漏标
两条都做了破坏性验证，摘掉修复会红。
顺带把 WithTimeout 的文档补上一句：要新建 VM 的路径上是顶层和函数调用两段
各自计时，墙钟上限是 2×d。行为不改——两段各自计时是合理的，缺的只是说明。
|
2026-09-10 15:21:17 +08:00 |
|
|
what
|
9b3509ae29
|
refactor: 清掉指向不存在的 Dispatch 的文档，删掉为它留的死导出
Dispatch 在仓库里出现 7 次，全是注释和错误文案，没有任何实现。三处错误文案
写着「需要回调语义请用 Dispatch」——使用者按这句去查会找不到东西，真正该指的
是 WithCall。caller.go 那句还指向不存在的子包 jscriptx/dispatch。
连带删掉四个为它留的导出（全仓库零调用）：
Target 统一 Script/Instance 的接口。有未导出方法 owner()，
外部实现不了；也没有任何函数以它为参数或返回值
ErrUnsupportedSignature 哨兵错误，库自己从不产生它
KindSignature 错误分类，全仓库唯一一次出现就是它自己的声明。
留着会让写 switch 的人为一个永不出现的分支写代码
OverlayLoader.Loaders 零调用的 getter，连测试都没有
另外删掉 Instance.IdleFor 和 lastUsed 字段：它是给「空闲回收」用的，而
doc.go 明确写着本库不代管实例生命周期、没有空闲回收——字段注释和包文档直接
对立。代价是每次 Call 白付两次 time.Now() + atomic store。业务侧真要自己回收，
记一个时间戳是一行的事。
caller 的示例原来拿 ErrUnsupportedSignature 当哨兵，改成自己声明一个——
回调签名的约定本来就是调用方定的，哨兵该归调用方。
验证：framework-v2 和 lx-bid 都仍能编译。
|
2026-09-10 15:15:10 +08:00 |
|
|
what
|
ad722b12f9
|
fix(esm): Vendor 支持子路径，不然 es-toolkit/compat 这种装不了
有些包把东西放在子路径下（es-toolkit 的 toString 只在 compat 里，主入口没有），
而摊平之后原包的 exports 映射就没了，import "es-toolkit/compat" 解析不到。
现在直接写子路径就行：
esm.Install(ctx, "es-toolkit/compat", "app/node_modules")
拉的是根包，摊平的是子路径，落到 node_modules/es-toolkit/compat/。根包和子路径
可以共存——子路径目录嵌在根包目录里，而最小 package.json 不写 exports，
所以解析器认得出来。
npm.SplitPath 负责拆名字，scoped 包名自带一个斜杠所以前两段才是包名。
|
2026-09-07 10:58:34 +08:00 |
|
|
what
|
00d95c496f
|
feat(esm/npm): 用 Go 拉依赖树，加库不再需要 node
零依赖的包下个 tarball 就能用，有依赖的得先解析依赖树——读 semver 范围、
查注册表定版本、递归。这个包把那件事用 Go 做了，于是整条链没有 node：
esm.Install(ctx, "qs", "app/node_modules")
// qs v6.16.0 打进 50 个文件 -> 73.3 KB（依赖树 19 个包 1.7 MB）
= npm.Fetch（拉依赖树到临时目录）+ Vendor（摊平成一个文件）。
刻意不做的（它不是 npm）：
- 不跑安装脚本。那是供应链攻击的主要入口，而纯 JS 库没有编译步骤
- 不管 devDependencies / peerDependencies / 平台二进制
- semver 只实现 ^ / ~ / 精确 / x / >= 这个子集
- 只平铺不嵌套
碰上支持不了的（复合范围、主版本冲突）明确报错并指向 npm + Vendor，
不猜版本——猜错了装出来能跑但行为不对，比装不上难查。
子集划得这么小是有依据的：抽 8 个常见包的 44 个传递依赖统计，^ 占 95%，
~ 和精确各一两处，主版本冲突 0 个。
安全上做了两件事：校验注册表给的 sha512（中间的缓存代理、私有源镜像
是真实存在的），以及挡住 tarball 里带 ../ 的路径。
测试全部走内存假注册表，不碰网络：依赖树平铺、共同依赖只装一次、
版本冲突报错、校验和不符、目录穿越。semver 那组表驱动——写这组时抓到
一个真 bug：1.2.x 被映射成了 ^1.2.0，只锁主版本，实际该锁到 1.2。
|
2026-09-07 10:11:51 +08:00 |
|
|
what
|
efb3141734
|
feat(esm): Vendor 把装好的 npm 包连同依赖摊平成单文件
解决的是「脚本要用第三方库，但目标机器上没有 node」。
npm 真正干的活是解析依赖树——读 semver 范围、查注册表定版本、递归、处理冲突。
这步绕不开，得在有 node 的机器上做一次。但做完之后依赖树就是死数据了，用
esbuild 摊平成一个文件，发布物里只带那一个就够：
qs v6.16.0 打进 47 个文件 -> 73.6 KB （原 19 个包 1.7 MB）
es-toolkit v1.52.0 打进 219 个文件 -> 51.9 KB
产物是最小的 node_modules 布局，脚本照常 import，写法完全不变。
两个实现细节：
- 入口不能直接写包名，esbuild 的 EntryPoints 是文件路径。所以造一段转发
源码当 stdin 入口，包名放进 import，才走正常的 node_modules 解析。
- 转发源码里写 export { default } 时，只有具名导出的包会报错（ESM 原生的
很多是这样），退回去用只带具名导出的版本重打一次。
打包目标从 Loader 里提成了共用常量：摊平出来的库必须跟脚本同一档，
否则库能打出脚本引擎跑不了的语法。
零依赖的包不用这个——直接下 tarball 解开就行，README 里记了命令。
|
2026-09-07 09:54:18 +08:00 |
|
|
what
|
c2ce37ad2d
|
docs: README 与执行流程、生命周期两篇
README 分四段：脚本怎么写、Go 侧怎么调、安全边界与可靠性、性能。
docs/call-flow.md 讲源码怎么变成可执行的、一次调用经过哪些环节；
docs/lifecycle.md 讲 Engine / Script / VM / Instance / 作用域各活多久。
性能一节的每一行都标了对应的基准名，数字过时了可以自己重跑。原来有一张
「循环里访问 Go 对象」的表没有对应的基准测试，数字无法复现，换成了
Benchmark绑定_* 的实测结果。内存那张表仍是手工测的，已在旁边注明。
挑第三方库那节记了两条实测结论：esbuild 的 target 只降级语法、不补全局
对象，所以库只要用了 structuredClone 或定时器就是运行期才炸；CommonJS
包摇不动，同一组功能 lodash 打出 419 KB 而 es-toolkit 只要 7 KB。
|
2026-09-05 22:13:57 +08:00 |
|
|
what
|
7f484d7a71
|
test: 引擎核心的测试与基准
除了常规用例，有几组是专门钉住「引擎的既定事实」的，改动时会先红：
- vmstate_test goja 的硬限制：非原始值不是 goroutine 安全的、对象跨不了
Runtime。其中一条是哨兵——goja 哪天允许对象跨 Runtime 了，
它会失败，提醒我们可以简化设计。
- govalue_test Go 的切片/map 进到脚本里长什么样。这不是本库的行为而是
goja 的，但脚本作者照着它写代码，变了会静默走错分支。
- safety_test 并发下坏 VM 不会被别的 goroutine 捡到。
- bench_gobind 脚本碰 Go 对象的单次开销，README 性能一节的数据来源。
missing_global_test 里有一条断言 typeof setTimeout === "undefined"：
定时器必须保持未定义，库里的特性探测才能正常降级，防止以后有人把桩加回来。
|
2026-09-05 22:13:57 +08:00 |
|
|
what
|
6ce9b483fd
|
feat(esm): 按目录加载脚本、打包与热更新
把一个目录当脚本仓库：按路径寻址、esbuild 打包、内容变了自动重编。
- Loader 扫目录建索引，Load(name) 给出打好包的源码和版本号
- bundler esbuild 的封装。ESM 格式而不是 IIFE——IIFE 会附带一整套
CommonJS interop helper，每建一个 VM 都要重跑一遍
- plugin 把扩展的 TS 模块变成可以 import 的虚拟模块，磁盘上没有文件
- typings 把这些虚拟模块的类型按 node_modules 布局落盘，编辑器才认识
esbuild 原生实现了 Node 的模块解析，所以脚本能直接 import node_modules
里的第三方库。写出来的类型文件是 index.ts 而不是 index.d.ts：扩展给的是
真正的模块源码，里面可能带实现，声明文件里不允许有实现。
node_modules 不参与热更新的版本计算——依赖包是装出来的，改动总伴随显式的
安装动作，而真实的 npm 包动辄上千个文件，每次取脚本 stat 一遍太贵。
|
2026-09-05 22:13:57 +08:00 |
|
|
what
|
7fb8d0f966
|
test: 测试用的最小扩展
本库不带内置扩展——扩展该由用引擎的人按自己的场景定义，引擎只给接口。
但测「作用域共享状态」「扩展改名」「VM 复用后状态还在不在」这些行为，
手上得有一个真的扩展，所以放一个最小的在 internal 下。
Incr 用 float64 而不是整数：JS 的数字就是 float64，脚本写进来的值也是
这个类型，用整数会让「Go 侧读回来」的断言在类型上对不上。
|
2026-09-05 22:12:14 +08:00 |
|
|
what
|
0627d49425
|
feat: 嵌入式 JS 脚本引擎核心
用 goja 承载业务回调，让业务逻辑变更不必重新编译发布 Go 程序。脚本用
ESM + TypeScript 写，Go 侧按名字把它们当普通对象实例化并调用方法。
主要组成：
- Engine 编译脚本、管配置，公开 API 不暴露任何 goja 类型
- Script 一份编译好的脚本 + 它的 VM 池，热更新时整体顶替
- Instance 独占一个 VM 的实例，状态留在 JS 侧
- Caller 自定义调用约定，把脚本函数适配成 Go 侧要的签名
- Scope 让同一个 ctx 下的多个脚本共享 Go 侧对象
- Extension 扩展接口：给脚本添全局对象，配套 TS 类型
- Overlay 多层 Loader 叠加，后面的盖前面的
几个关键取舍：
- 源码一律先过 esbuild 打包成 ESM，再改写成立即执行函数。goja 不认
import/export，而业务脚本要能拆文件、用 TypeScript。
- VM 池化复用，但每个 VM 单线程。goja 的 Runtime 不是 goroutine 安全的。
- Go 侧函数返回的 error 在脚本里表现为抛异常，不占返回值位置。
- 脚本能看见的全局只有白名单放行的那些，且注入是惰性的——没读到的
全局根本不会被转换。
|
2026-09-05 22:11:55 +08:00 |
|