paulmillr/jsbt
GitHub: paulmillr/jsbt
一套零依赖的 JavaScript/TypeScript 构建工具集，集成测试框架、纳秒级基准测试、代码质量审计和 GitHub CI 配置，帮助开发者高效构建和维护高质量 JS 库。
Stars: 16 | Forks: 5
# @paulmillr/jsbt
用于安全 JS 应用的零依赖辅助工具，被 [noble cryptography](https://paulmillr.com/noble/) 使用。
1. [test](#test) 500 行的简洁实现，具有类似 mocha 的语法和并行处理能力
2. [benchmark](#benchmark) 具备纳秒级分辨率
3. [CLI](#cli) 用于创建单文件 bundle；并检查项目中的常见错误
4. [tsconfig](#tsconfig) 严格、文档友好，支持 type stripping
5. [workflows](#workflows) 用于 GitHub CI 的 test / npm+jsr 发布操作
## 用法
## 1. test
500 行的测试框架，语法类似于 Mocha / Jest / Vitest。优势：
- 彩色树状报告器
- +quiet 模式：点状报告器
- +fast 模式：使用所有核心或指定 x 个核心
- 无“全局”魔法：最后的 `it.run()` 简化了逻辑和浏览器运行
- RunWhen 助手：从 cli 运行；在被导入时不运行（作为子测试）
API：
- `it(title, case)` 或 `should(title, case)` 语法用于注册测试函数
- `it.only`、`it.skip` 允许将测试限制为单个用例 / 跳过测试
- `beforeEach`、`afterEach` 在 `describe` 块中的函数之前 / 之后执行代码
- 最后，必须执行 `it.run()` 或 `it.runWhen(import.meta.url)`：
- runWhen 助手确保测试在被其他文件导入时不运行。它将 import.meta.url 与 cli 参数进行比较
环境变量：
- `JSBT_FAST=1` 在 node.js 和 Bun 中启用并行执行
- `JSBT_FAST=3` 大于 1 的值将设置 worker 数量
- `JSBT_FAST=1` 启用“quiet”点状报告器
```
import { should } from 'micro-should';
import { equal } from 'node:assert';
should('add', () => {
equal(2 + 2, 4);
});
should('work in async env', async () => {
equal(await Promise.resolve(123), 123);
});
describe('nested', () => {
describe('nested 2', () => {
should('multiply', () => {
equal(2 * 2, 4);
});
should.skip('disable test by using skip', () => {
equal(true, false); // skip
});
// should.only('execute only one test', () => {
// equal(true, true);
// });
});
});
should.runWhen(import.meta.url); // or should.run();
```
## 2. benchmark
200 行的基准测试框架。优势：
- 精准：使用 `process.hrtime` 实现 1ns 分辨率
- 彩色显示且具有合适的单位
- 方便地从 ops/sec 切换到 mb/sec
```
import bench from '@paulmillr/jsbt/bench.js';
(async () => {
await bench('printing', async () => 0);
await bench('base', () => Promise.resolve(1));
await bench('sqrt', 10000, () => Math.sqrt(2));
})();
```
输出示例：
```
getPublicKey x 6,072 ops/sec @ 164μs/op ± 8.22% [143μs..17ms]
sign x 4,980 ops/sec @ 200μs/op
verify x 969 ops/sec @ 1ms/op
recoverPublicKey x 890 ops/sec @ 1ms/op
getSharedSecret x 585 ops/sec @ 1ms/op
```
## 3. CLI
jsbt CLI 用于单文件 bundle 并执行审计辅助工具。
### bundle
基于 [esbuild](https://esbuild.github.io) 的一些辅助功能。
1. 收集所有包导出
2. 收集所有依赖
3. 创建一个文件，将所有内容 bundle 在里面，声明一个以包名命名的全局变量
4. 打印文件统计信息
```
$ jsbt bundle
11d1900e99f3aa945603bb5e7d82bdd9ec6ddf5d30e2fcab69b836840cff76d2 test/build/out/noble-hashes.js
0be3876ff0816c44d21a401e6572fdb76d06012c760a23a5cb771c6f612106f5 test/build/out/noble-hashes.min.js
3790 LOC noble-hashes.js
58.21 KB noble-hashes.min.js
21.10 KB +gzip
```
bundle 命令在 1) 项目的 `test/build` 目录 或 2) 系统级 tmp 目录中运行。
有以下可用选项：
```
$ jsbt bundle --dir=test/build
# （与 jsbt bundle 相同，但使用特定目录代替默认值）
$ jsbt bundle --stats-only
3790 LOC noble-hashes.js
58.21 KB noble-hashes.min.js
21.10 KB +gzip
```
### check
运行主观性强的代码质量检查。底层使用 typescript 解析。
```
jsbt check
jsbt check bigint
jsbt check bytes
jsbt check comments
jsbt check errors
jsbt check importtime
jsbt check jsr
jsbt check jsrpublish
jsbt check mutate
jsbt check patterns
jsbt check readme
jsbt check tests
jsbt check treeshake [out-dir]
jsbt check tsdoc
jsbt check typeimport
jsbt check-install
```
关于 `check ` 的子命令摘要：
* `bigint`：在公共运行时文件中查找 BigInt 兼容性风险。
* `bytes`：检查字节/typed-array API 表面以及 TypeScript 版本兼容性。
* `comments`：强制要求注释和面向发布的源代码标注。
* `errors`：根据运行时探测验证已记录的抛出错误。
* `importtime`：测量公共入口导入时间并标记缓慢的导入。
* `jsr`：验证 JSR 包元数据、导出、导入和发布图谱。
* `jsrpublish`：运行更严格的 JSR 发布就绪检查。
* `mutate`：检测公共运行时行为中的变异风险。
* `patterns`：报告对已发布包有风险的源代码模式。
* `readme`：对 README 中的示例进行类型检查并运行可执行的示例。
* `tests`：运行包测试并对入口点进行基准测试。
* `treeshake`：bundle 公共导出并报告保留的未使用代码。
* `tsdoc`：审计公共声明文档和示例。
* `typeimport`：验证应为仅类型（type-only）的导入。
* `check-install`：将包检查脚本重写为当前的统一形式。
## 4. Workflows
用于测试和发布 JS 包的安全 GitHub CI 配置。
这些文件位于 `.github/workflows`：
* `test.yml`：用于 Node 22、24、26、Bun 和 Deno 的可复用/手动测试工作流。它运行
`npm run build --if-present`、`npm test`、可选的 `test:tsc`（在 Node 26 上）、
可选的 `test:bun` 以及可选的 `test:deno`。输入项：`submodules` 和 `runs-on`。
* `test-matrix.yml`：跨 Node 22、24、26 的可复用/手动 Node 矩阵，在 `ubuntu-24.04-arm`、
`macos-latest` 和 `windows-latest` 上运行。
* `test-custom.yml`：用于单个自定义 npm 任务的可复用 Node 26 工作流，默认为 `test:slow`。
* `release.yml`：用于 NPM 的发布/可复用/手动发布器，并在存在 `jsr.json` 时发布到 JSR。它
使用 OIDC Trusted Publishing，禁用包管理器缓存，运行 `npm ci`，在存在时进行构建，
验证包/标签版本，试运行 NPM 发布，验证 JSR 版本，并通过
`npm stage publish --access public` 进行发布。
你可以复制它们，或直接依赖它们：
```
name: jsbt 0.5.2
on:
push:
pull_request:
jobs:
test:
uses: paulmillr/jsbt/.github/workflows/test.yml@0.5.2
```
对于发布，请先为包配置 NPM Trusted Publishing：
```
name: Publish release
on:
release:
types: [created]
jobs:
publish:
uses: paulmillr/jsbt/.github/workflows/release.yml@0.5.2
permissions:
contents: read
id-token: write
```
## 5. tsconfig
严格的 typescript v6+ 配置，对 type stripping 友好。使用 `isolatedDeclarations` 和 `verbatimModuleSyntax`
来确保 node.js 能够原生运行 typescript 文件而无需编译。
包含两个文件：`tsconfig.json` 和 `tsconfig.test.json`（更宽松，用于测试）。
可以通过以下方式继承：
```
{
"extends": "@paulmillr/jsbt/tsconfig.json",
"compilerOptions": {
"rootDir": "src",
"outDir": "."
},
"include": [
"src"
],
"exclude": [
"node_modules"
]
}
```
## License
MIT License
标签：CMS安全, JavaScript, MITM代理, 前端构建工具, 性能基准测试, 数据可视化, 测试框架, 自动化攻击, 零依赖