 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 |
|