mirror of
https://github.com/affaan-m/ECC.git
synced 2026-10-17 21:55:34 +02:00
docs(bun): clarify isolation, audit coverage and package commands
Preserve the original contributor histories and apply the exact independently reviewed repair.
Source-Parent: edcb389e2c
Review-Manifest-SHA256: c607db261fe8760465af1dffd5f9a3dda42478c5f745dbfa5916fd8e014ef306
This commit is contained in:
affaan-m
@@ -17,19 +17,19 @@ Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/te
|
||||
|
||||
## How It Works
|
||||
|
||||
- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags have changed across major versions.
|
||||
- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags can change between releases.
|
||||
- **Runtime**: Drop-in Node-compatible runtime, built on JavaScriptCore. As of Bun 1.4 the runtime itself is implemented in Rust (migrated from Zig). Not 100% Node-compatible — some native addons, less-common `node:` internal APIs, and packages that depend on Node-specific internals can still fail; verify before depending on it in production.
|
||||
- **Package manager**: `bun install` is typically faster than npm/yarn; actual gains depend on project size, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`.
|
||||
- **Package manager**: Bun includes a package manager; installation performance depends on the project, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`.
|
||||
- **Bundler**: Built-in bundler and transpiler for apps and libraries.
|
||||
- **Test runner**: Built-in `bun test` with a Jest-like API.
|
||||
|
||||
**Migration from Node**: Replace `node script.js` with `bun run script.js` or `bun script.js`. Run `bun install` in place of `npm install`; most packages work. Use `bun run` for npm scripts; `bun x` for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance.
|
||||
|
||||
**Package and workspace commands**: `bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` manage dependencies; `bun outdated` lists stale deps; `bun pm ls` shows the dependency tree derived from the lockfile (not a listing of what's actually on disk). Read-only inspection: `bun audit` reads `bun.lock` and sends the package list to the npm advisory endpoint (or each scoped registry's own advisory endpoint) to report known vulnerabilities — it doesn't touch local files, but it isn't offline, so on private projects only use an approved registry/advisory endpoint, since package names and versions (including private ones) leave the machine. Modifying: `bun audit fix` applies fixes, `bun dedupe` collapses duplicate installs, and `bun prune` removes packages no longer referenced. Monorepos use a root `workspaces` array in `package.json` (same convention as npm/yarn); run a script in one workspace with `bun run --filter <pkg-name> <script>`.
|
||||
**Package and workspace commands**: `bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` manage dependencies; `bun outdated` lists stale deps. `bun pm ls` lists project dependencies and resolved versions using the lockfile; `--all` includes transitive dependencies. It is not an integrity check of installed file contents. [`bun audit`](https://bun.com/docs/pm/cli/audit) queries registry advisories using package names and versions from `bun.lock`; it does not modify `package.json`, `bun.lock`, or `node_modules`. Review approved destinations before sending private package metadata. Packages whose scoped registry lacks an advisory endpoint are skipped and do not affect the exit code. `bun audit fix` upgrades and installs dependencies, changing the lockfile and installed packages and sometimes direct version pins; review it as a modifying install operation, including applicable lifecycle scripts. `bun dedupe` collapses duplicate installs, and `bun prune` removes packages no longer referenced. Monorepos use a root `workspaces` array in `package.json` (same convention as npm/yarn); run a script in one workspace with `bun run --filter <pkg-name> <script>`.
|
||||
|
||||
**Built-in APIs**: reach for these before adding a dependency — `Bun.file` / `Bun.write` for file I/O, `bun:sqlite` for an embedded SQLite database, `Bun.serve` for an HTTP/WebSocket server, [`Bun.sql`](https://bun.com/docs/runtime/sql) for SQL databases, [`Bun.redis`](https://bun.com/docs/runtime/redis) for Redis, and [`Bun.S3Client`](https://bun.com/docs/runtime/s3) for S3-compatible object storage. See the [1.4 release notes](https://bun.com/blog/bun-v1.4) for the rest of what's new.
|
||||
|
||||
**Vercel**: Set `bunVersion: "1.4.x"` in `vercel.json` to use Bun 1.4 (Rust runtime) — `"1.x"` currently still resolves to the older 1.3.14. See [Vercel's Bun runtime docs](https://vercel.com/docs/functions/runtimes/bun). Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
|
||||
**Vercel**: Set `bunVersion: "1.4.x"` in `vercel.json` to use Bun 1.4 (Rust runtime). See [Vercel's Bun runtime docs](https://vercel.com/docs/functions/runtimes/bun). Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
|
||||
|
||||
**Reference**: [Bun 1.4 release notes](https://bun.com/blog/bun-v1.4).
|
||||
|
||||
@@ -61,7 +61,7 @@ bun test
|
||||
bun test --watch
|
||||
```
|
||||
|
||||
For CI, Bun 1.4's test runner adds: `bun test --changed[=<ref>]` (run test files affected by changes vs. a git commit/branch — includes tests exercising changed source files, not just edited test files), `bun test --isolate` (fresh global object per test file, so leaked handles in one file can't affect another; implied by `--parallel`), `bun test --parallel[=<n>]` (run test files across N worker processes, defaults to CPU core count), `bun test --shard=<n>/<count>` (split one suite across CI runners), and `bun test --timings=<file>` (reads JSON per-file duration data to front-load the slowest files) with `--update-timings` (writes to the first `--timings` path given — without `--shard` it merges into existing entries; with `--shard` it writes only the current shard's files to that same first `--timings` path — Bun does not pick a different path per shard automatically, so choose a distinct output path for each shard to avoid overwriting other shards' timing records; pass `--timings` multiple times, once per shard file, to read them together as a single combined table). Example: `bun test --parallel --timings=./test-timings.json --update-timings`. Run `bun test --help` locally to confirm exact flag behavior for your installed version.
|
||||
For CI on Bun 1.4, available options include `bun test --changed[=<ref>]` for affected tests, `bun test --isolate` for per-file globals, `bun test --parallel[=<n>]` for worker processes, and `bun test --shard=<n>/<count>` for CI partitioning. `--isolate` creates a fresh JavaScript global for each file in the same process and cleans up documented per-file resources; it is not a process or security sandbox. `--parallel` enables it by default. `--timings=<file>` reads prior durations for scheduling; `--update-timings` records durations. Example: `bun test --parallel --timings=./test-timings.json --update-timings`. Check the installed version's help and documentation before choosing timing-file paths for a multi-shard workflow.
|
||||
|
||||
```typescript
|
||||
// test/example.test.ts
|
||||
|
||||
@@ -17,19 +17,19 @@ Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/te
|
||||
|
||||
## How It Works
|
||||
|
||||
- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags have changed across major versions.
|
||||
- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags can change between releases.
|
||||
- **Runtime**: Drop-in Node-compatible runtime, built on JavaScriptCore. As of Bun 1.4 the runtime itself is implemented in Rust (migrated from Zig). Not 100% Node-compatible — some native addons, less-common `node:` internal APIs, and packages that depend on Node-specific internals can still fail; verify before depending on it in production.
|
||||
- **Package manager**: `bun install` is typically faster than npm/yarn; actual gains depend on project size, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`.
|
||||
- **Package manager**: Bun includes a package manager; installation performance depends on the project, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`.
|
||||
- **Bundler**: Built-in bundler and transpiler for apps and libraries.
|
||||
- **Test runner**: Built-in `bun test` with a Jest-like API.
|
||||
|
||||
**Migration from Node**: Replace `node script.js` with `bun run script.js` or `bun script.js`. Run `bun install` in place of `npm install`; most packages work. Use `bun run` for npm scripts; `bun x` for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance.
|
||||
|
||||
**Package and workspace commands**: `bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` manage dependencies; `bun outdated` lists stale deps; `bun pm ls` shows the dependency tree derived from the lockfile (not a listing of what's actually on disk). Read-only inspection: `bun audit` reads `bun.lock` and sends the package list to the npm advisory endpoint (or each scoped registry's own advisory endpoint) to report known vulnerabilities — it doesn't touch local files, but it isn't offline, so on private projects only use an approved registry/advisory endpoint, since package names and versions (including private ones) leave the machine. Modifying: `bun audit fix` applies fixes, `bun dedupe` collapses duplicate installs, and `bun prune` removes packages no longer referenced. Monorepos use a root `workspaces` array in `package.json` (same convention as npm/yarn); run a script in one workspace with `bun run --filter <pkg-name> <script>`.
|
||||
**Package and workspace commands**: `bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` manage dependencies; `bun outdated` lists stale deps. `bun pm ls` lists project dependencies and resolved versions using the lockfile; `--all` includes transitive dependencies. It is not an integrity check of installed file contents. [`bun audit`](https://bun.com/docs/pm/cli/audit) queries registry advisories using package names and versions from `bun.lock`; it does not modify `package.json`, `bun.lock`, or `node_modules`. Review approved destinations before sending private package metadata. Packages whose scoped registry lacks an advisory endpoint are skipped and do not affect the exit code. `bun audit fix` upgrades and installs dependencies, changing the lockfile and installed packages and sometimes direct version pins; review it as a modifying install operation, including applicable lifecycle scripts. `bun dedupe` collapses duplicate installs, and `bun prune` removes packages no longer referenced. Monorepos use a root `workspaces` array in `package.json` (same convention as npm/yarn); run a script in one workspace with `bun run --filter <pkg-name> <script>`.
|
||||
|
||||
**Built-in APIs**: reach for these before adding a dependency — `Bun.file` / `Bun.write` for file I/O, `bun:sqlite` for an embedded SQLite database, `Bun.serve` for an HTTP/WebSocket server, [`Bun.sql`](https://bun.com/docs/runtime/sql) for SQL databases, [`Bun.redis`](https://bun.com/docs/runtime/redis) for Redis, and [`Bun.S3Client`](https://bun.com/docs/runtime/s3) for S3-compatible object storage. See the [1.4 release notes](https://bun.com/blog/bun-v1.4) for the rest of what's new.
|
||||
|
||||
**Vercel**: Set `bunVersion: "1.4.x"` in `vercel.json` to use Bun 1.4 (Rust runtime) — `"1.x"` currently still resolves to the older 1.3.14. See [Vercel's Bun runtime docs](https://vercel.com/docs/functions/runtimes/bun). Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
|
||||
**Vercel**: Set `bunVersion: "1.4.x"` in `vercel.json` to use Bun 1.4 (Rust runtime). See [Vercel's Bun runtime docs](https://vercel.com/docs/functions/runtimes/bun). Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
|
||||
|
||||
**Reference**: [Bun 1.4 release notes](https://bun.com/blog/bun-v1.4).
|
||||
|
||||
@@ -61,7 +61,7 @@ bun test
|
||||
bun test --watch
|
||||
```
|
||||
|
||||
For CI, Bun 1.4's test runner adds: `bun test --changed[=<ref>]` (run test files affected by changes vs. a git commit/branch — includes tests exercising changed source files, not just edited test files), `bun test --isolate` (fresh global object per test file, so leaked handles in one file can't affect another; implied by `--parallel`), `bun test --parallel[=<n>]` (run test files across N worker processes, defaults to CPU core count), `bun test --shard=<n>/<count>` (split one suite across CI runners), and `bun test --timings=<file>` (reads JSON per-file duration data to front-load the slowest files) with `--update-timings` (writes to the first `--timings` path given — without `--shard` it merges into existing entries; with `--shard` it writes only the current shard's files to that same first `--timings` path — Bun does not pick a different path per shard automatically, so choose a distinct output path for each shard to avoid overwriting other shards' timing records; pass `--timings` multiple times, once per shard file, to read them together as a single combined table). Example: `bun test --parallel --timings=./test-timings.json --update-timings`. Run `bun test --help` locally to confirm exact flag behavior for your installed version.
|
||||
For CI on Bun 1.4, available options include `bun test --changed[=<ref>]` for affected tests, `bun test --isolate` for per-file globals, `bun test --parallel[=<n>]` for worker processes, and `bun test --shard=<n>/<count>` for CI partitioning. `--isolate` creates a fresh JavaScript global for each file in the same process and cleans up documented per-file resources; it is not a process or security sandbox. `--parallel` enables it by default. `--timings=<file>` reads prior durations for scheduling; `--update-timings` records durations. Example: `bun test --parallel --timings=./test-timings.json --update-timings`. Check the installed version's help and documentation before choosing timing-file paths for a multi-shard workflow.
|
||||
|
||||
```typescript
|
||||
// test/example.test.ts
|
||||
|
||||
@@ -17,19 +17,19 @@ Bunは高速なオールインワンJavaScriptランタイムとツールキッ
|
||||
|
||||
## 動作方法
|
||||
|
||||
- **バージョンの基準**：以下のガイダンスはBun 1.4.xを対象としています。CLIフラグはメジャーバージョン間で変更されているため、フラグ名に依存する前に`bun --version`で実際のバージョンを確認してください。
|
||||
- **バージョンの基準**：以下のガイダンスはBun 1.4.xを対象としています。CLIフラグはリリース間で変更されることがあるため、フラグ名に依存する前に`bun --version`で実際のバージョンを確認してください。
|
||||
- **ランタイム**：ドロップイン互換のNodeランタイム（JavaScriptCore上に構築）。Bun 1.4以降、ランタイム自体はRustで実装されています（Zigから移行）。100%Node互換ではありません — 一部のネイティブアドオン、あまり一般的でない`node:`内部APIや、Node固有の内部動作に依存するパッケージは動作しないことがあります。本番環境で依存する前に検証してください。
|
||||
- **パッケージマネージャー**：`bun install`は一般にnpm/yarnより高速です。実際の速度差はプロジェクトサイズ、ネットワーク状況、キャッシュの状態によって変わります。ロックファイルは現行のBunでは`bun.lock`（テキスト）がデフォルトです。古いバージョンは`bun.lockb`（バイナリ）を使用しており、Bunは移行のため現在もこれを読み込めますが、新規プロジェクトは`bun.lock`を使うべきです。
|
||||
- **パッケージマネージャー**：Bunにはパッケージマネージャーが含まれています。インストール性能はプロジェクト、ネットワーク状況、キャッシュの状態によって変わります。ロックファイルは現行のBunでは`bun.lock`（テキスト）がデフォルトです。古いバージョンは`bun.lockb`（バイナリ）を使用しており、Bunは移行のため現在もこれを読み込めますが、新規プロジェクトは`bun.lock`を使うべきです。
|
||||
- **バンドラー**：アプリとライブラリ用の組み込みバンドラーとトランスパイラー。
|
||||
- **テストランナー**：Jest様のAPIを備えた組み込み`bun test`。
|
||||
|
||||
**Nodeからの移行**：`node script.js`を`bun run script.js`または`bun script.js`に置き換えます。`npm install`の代わりに`bun install`を実行します。ほとんどのパッケージは機能します。npm スクリプトには`bun run`を使用します。`bun x`をnpxスタイルの1回限りの実行に使用します。Nodeの組み込みはサポートされています。パフォーマンスの向上のため、Bun APIが存在する場合は優先してください。
|
||||
|
||||
**パッケージ・ワークスペースコマンド**：`bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]`で依存関係を管理し、`bun outdated`で古い依存関係を一覧表示します。`bun pm ls`はロックファイルから導出した依存関係ツリーを表示するもので、実際にディスクにインストールされている内容の証明ではありません。読み取り専用の`bun audit`は`bun.lock`を読み込み、パッケージ一覧をnpmのアドバイザリエンドポイント（またはスコープ付きレジストリ各自のエンドポイント）に送信して既知の脆弱性を報告します — ローカルファイルは変更しませんが、オフラインではないため、プライベートプロジェクトでは承認済みのレジストリ/アドバイザリエンドポイントのみを使用してください（プライベートなパッケージ名やバージョンも送信対象になります）。変更を伴う`bun audit fix`はその修正を適用し、`bun dedupe`は重複インストールを解消し、`bun prune`は参照されなくなったパッケージを削除します。モノレポはルートの`package.json`の`workspaces`配列を使用します（npm/yarnと同じ規約）。特定のワークスペースでスクリプトを実行するには`bun run --filter <pkg-name> <script>`を使用します。
|
||||
**パッケージ・ワークスペースコマンド**：`bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]`で依存関係を管理し、`bun outdated`で古い依存関係を一覧表示します。`bun pm ls`はロックファイルを使ってプロジェクトの依存関係と解決済みバージョンを表示し、`--all`を付けると推移的な依存関係も含めます。インストール済みファイルの内容の整合性を検証するものではありません。[`bun audit`](https://bun.com/docs/pm/cli/audit)は`bun.lock`内のパッケージ名とバージョンを使ってレジストリの脆弱性情報を照会し、`package.json`、`bun.lock`、`node_modules`は変更しません。プライベートなパッケージ情報を送信する前に、承認済みの送信先を確認してください。スコープ付きレジストリにアドバイザリエンドポイントがないパッケージはスキップされ、終了コードに影響しません。`bun audit fix`は依存関係を更新・インストールし、ロックファイルとインストール済みパッケージ、場合によっては直接依存の固定バージョンも変更します。適用されるライフサイクルスクリプトも含む、変更を伴うインストール操作としてレビューしてください。`bun dedupe`は重複インストールを解消し、`bun prune`は参照されなくなったパッケージを削除します。モノレポはルートの`package.json`の`workspaces`配列を使用します（npm/yarnと同じ規約）。特定のワークスペースでスクリプトを実行するには`bun run --filter <pkg-name> <script>`を使用します。
|
||||
|
||||
**組み込みAPI**：依存関係を追加する前にこれらを検討してください — ファイルI/Oには`Bun.file` / `Bun.write`、組み込みSQLiteデータベースには`bun:sqlite`、HTTP/WebSocketサーバーには`Bun.serve`、SQLデータベースには[`Bun.sql`](https://bun.com/docs/runtime/sql)、Redisには[`Bun.redis`](https://bun.com/docs/runtime/redis)、S3互換オブジェクトストレージには[`Bun.S3Client`](https://bun.com/docs/runtime/s3)。その他の新機能は[1.4リリースノート](https://bun.com/blog/bun-v1.4)を参照してください。
|
||||
|
||||
**Vercel**：`vercel.json`で`bunVersion: "1.4.x"`を設定し、Bun 1.4（Rustランタイム）を使用してください — `"1.x"`は現在も旧バージョンの1.3.14を選択します。詳細は[VercelのBunランタイムドキュメント](https://vercel.com/docs/functions/runtimes/bun)を参照。ビルド：`bun run build`または`bun build ./src/index.ts --outdir=dist`。インストール：再現可能なデプロイの場合は`bun install --frozen-lockfile`。
|
||||
**Vercel**：`vercel.json`で`bunVersion: "1.4.x"`を設定し、Bun 1.4（Rustランタイム）を使用してください。詳細は[VercelのBunランタイムドキュメント](https://vercel.com/docs/functions/runtimes/bun)を参照。ビルド：`bun run build`または`bun build ./src/index.ts --outdir=dist`。インストール：再現可能なデプロイの場合は`bun install --frozen-lockfile`。
|
||||
|
||||
**参考**：[Bun 1.4 リリースノート](https://bun.com/blog/bun-v1.4)。
|
||||
|
||||
@@ -61,7 +61,7 @@ bun test
|
||||
bun test --watch
|
||||
```
|
||||
|
||||
CI向けに、Bun 1.4のテストランナーは以下を追加します：`bun test --changed[=<ref>]`（gitのコミット/ブランチと比較して変更の影響を受けるテストファイルを実行 — 編集されたテストファイルだけでなく、変更されたソースを利用するテストも含む）、`bun test --isolate`（テストファイルごとに新しいグローバルオブジェクトで実行し、あるファイルのリークが他に影響しないようにする。`--parallel`使用時は暗黙的に有効）、`bun test --parallel[=<n>]`（N個のワーカープロセスでテストファイルを実行、デフォルトはCPUコア数）、`bun test --shard=<n>/<count>`（1つのスイートをCIランナー間で分割）、`bun test --timings=<file>`（JSON形式の所要時間データを読み込み、最も遅いファイルを優先的に実行できるようにする）と`--update-timings`（指定した最初の`--timings`パスに書き込む — `--shard`なしの場合は既存のエントリにマージし、`--shard`ありの場合は同じ最初の`--timings`パスに現在のシャードのファイルのみを書き込む — Bunはシャードごとに異なる出力パスを自動的に選ばないため、他のシャードのタイミング記録を上書きしないよう、シャードごとに異なる出力パスを指定すること。`--timings`をシャードごとに複数回指定すると、それらをまとめて1つの表として読み込める）。例：`bun test --parallel --timings=./test-timings.json --update-timings`。インストールされているバージョンの正確なフラグの挙動は`bun test --help`で確認してください。
|
||||
Bun 1.4でCIに利用できるオプションには、影響を受けるテストを選ぶ`bun test --changed[=<ref>]`、ファイルごとのグローバル環境を使う`bun test --isolate`、ワーカープロセスで実行する`bun test --parallel[=<n>]`、CIを分割する`bun test --shard=<n>/<count>`があります。`--isolate`は同じプロセス内でファイルごとに新しいJavaScriptグローバル環境を作り、文書化されたファイル単位のリソースをクリーンアップします。プロセスやセキュリティのサンドボックスではありません。`--parallel`ではデフォルトで有効です。`--timings=<file>`はスケジューリング用に過去の所要時間を読み込み、`--update-timings`は所要時間を記録します。例：`bun test --parallel --timings=./test-timings.json --update-timings`。複数シャードのタイミングファイルのパスを決める前に、インストール済みバージョンのヘルプとドキュメントを確認してください。
|
||||
|
||||
```typescript
|
||||
// test/example.test.ts
|
||||
|
||||
@@ -17,19 +17,19 @@ Bun 是一个快速的全能 JavaScript 运行时和工具集：运行时、包
|
||||
|
||||
## 工作原理
|
||||
|
||||
* **版本基线**：以下内容以 Bun 1.4.x 为准。CLI 参数在不同大版本之间有变化，依赖具体参数名之前请先用 `bun --version` 核实实际版本。
|
||||
* **版本基线**：以下内容以 Bun 1.4.x 为准。CLI 参数可能在不同发行版本之间变化，依赖具体参数名之前请先用 `bun --version` 核实实际版本。
|
||||
* **运行时**：开箱即用的 Node 兼容运行时（基于 JavaScriptCore）。自 Bun 1.4 起，运行时本身改用 Rust 实现（此前为 Zig）。并非 100% 兼容 Node——部分原生插件、较少使用的 `node:` 内部 API，以及依赖 Node 特定内部行为的包仍可能失败；生产环境依赖前请自行验证。
|
||||
* **包管理器**：`bun install` 通常比 npm/yarn 更快；实际差距取决于项目规模、网络状况和缓存状态。在当前 Bun 中，锁文件默认为 `bun.lock`（文本）；旧版本使用 `bun.lockb`（二进制），Bun 目前仍可读取该格式以便迁移，但新项目应使用 `bun.lock`。
|
||||
* **包管理器**：Bun 包含包管理器；安装性能取决于项目、网络状况和缓存状态。在当前 Bun 中，锁文件默认为 `bun.lock`（文本）；旧版本使用 `bun.lockb`（二进制），Bun 目前仍可读取该格式以便迁移，但新项目应使用 `bun.lock`。
|
||||
* **打包器**：用于应用程序和库的内置打包器和转译器。
|
||||
* **测试运行器**：内置的 `bun test`，具有类似 Jest 的 API。
|
||||
|
||||
**从 Node 迁移**：将 `node script.js` 替换为 `bun run script.js` 或 `bun script.js`。运行 `bun install` 代替 `npm install`；大多数包都能工作。使用 `bun run` 来执行 npm 脚本；使用 `bun x` 进行 npx 风格的临时运行。支持 Node 内置模块；在存在 Bun API 的地方优先使用它们以获得更好的性能。
|
||||
|
||||
**包与工作区命令**：`bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` 管理依赖；`bun outdated` 列出过时的依赖；`bun pm ls` 显示的是根据锁文件推导出的依赖树，并非磁盘上实际安装内容的证明。只读检查用 `bun audit` 读取 `bun.lock` 并将包列表发送至 npm 的漏洞公告端点（或各自的限定作用域注册表端点）以报告已知漏洞——该命令不会修改本地文件，但并非离线操作，因此在私有项目中应仅使用已获批准的注册表/公告端点，因为包名和版本（包括私有包）会被发送出去；会修改内容的命令有 `bun audit fix`（应用修复）、`bun dedupe`（消除重复安装）和 `bun prune`（移除不再被引用的包）。多包仓库（monorepo）通过根 `package.json` 中的 `workspaces` 数组配置（与 npm/yarn 相同的约定）；使用 `bun run --filter <pkg-name> <script>` 在指定工作区运行脚本。
|
||||
**包与工作区命令**：`bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` 管理依赖；`bun outdated` 列出过时的依赖。`bun pm ls` 使用锁文件列出项目依赖及解析后的版本，`--all` 包含传递依赖；它不检查已安装文件内容的完整性。[`bun audit`](https://bun.com/docs/pm/cli/audit) 使用 `bun.lock` 中的包名和版本查询注册表漏洞公告，不修改 `package.json`、`bun.lock` 或 `node_modules`。发送私有包元数据前，请确认获批的发送目标。若作用域注册表没有漏洞公告端点，对应包会被跳过，且不影响退出码。`bun audit fix` 会升级并安装依赖，修改锁文件和已安装的包，有时也修改直接依赖的固定版本；请将其作为会产生修改的安装操作进行审查，包括适用的生命周期脚本。`bun dedupe` 消除重复安装，`bun prune` 移除不再被引用的包。多包仓库（monorepo）通过根 `package.json` 中的 `workspaces` 数组配置（与 npm/yarn 相同的约定）；使用 `bun run --filter <pkg-name> <script>` 在指定工作区运行脚本。
|
||||
|
||||
**内置 API**：在添加依赖之前，优先考虑这些内置能力——文件 I/O 使用 `Bun.file` / `Bun.write`；内置 SQLite 数据库使用 `bun:sqlite`；HTTP/WebSocket 服务器使用 `Bun.serve`；SQL 数据库使用 [`Bun.sql`](https://bun.com/docs/runtime/sql)；Redis 使用 [`Bun.redis`](https://bun.com/docs/runtime/redis)；S3 兼容对象存储使用 [`Bun.S3Client`](https://bun.com/docs/runtime/s3)。其余新特性参见 [1.4 发布说明](https://bun.com/blog/bun-v1.4)。
|
||||
|
||||
**Vercel**：在 `vercel.json` 中设置 `bunVersion: "1.4.x"` 以使用 Bun 1.4（Rust 运行时）——目前 `"1.x"` 仍会解析到较旧的 1.3.14。详见 [Vercel 的 Bun 运行时文档](https://vercel.com/docs/functions/runtimes/bun)。构建命令：`bun run build` 或 `bun build ./src/index.ts --outdir=dist`。安装命令：`bun install --frozen-lockfile` 用于可重复的部署。
|
||||
**Vercel**：在 `vercel.json` 中设置 `bunVersion: "1.4.x"` 以使用 Bun 1.4（Rust 运行时）。详见 [Vercel 的 Bun 运行时文档](https://vercel.com/docs/functions/runtimes/bun)。构建命令：`bun run build` 或 `bun build ./src/index.ts --outdir=dist`。安装命令：`bun install --frozen-lockfile` 用于可重复的部署。
|
||||
|
||||
**参考**：[Bun 1.4 发布说明](https://bun.com/blog/bun-v1.4)。
|
||||
|
||||
@@ -61,7 +61,7 @@ bun test
|
||||
bun test --watch
|
||||
```
|
||||
|
||||
面向 CI，Bun 1.4 的测试运行器新增了：`bun test --changed[=<ref>]`（运行相对某个 git 提交/分支受影响的测试文件——不仅是被修改的测试文件本身，还包括依赖了被修改源文件的测试）、`bun test --isolate`（每个测试文件使用全新的全局对象运行，避免一个文件的句柄泄漏影响另一个文件；使用 `--parallel` 时默认启用）、`bun test --parallel[=<n>]`（用 N 个工作进程并行运行测试文件，默认等于 CPU 核心数）、`bun test --shard=<n>/<count>`（将一个测试套件拆分到多个 CI 运行器上）、以及 `bun test --timings=<file>`（读取 JSON 格式的单文件耗时数据，用于优先调度最慢的文件）配合 `--update-timings`（写入第一个指定的 `--timings` 路径——不带 `--shard` 时会合并进已有条目，带 `--shard` 时只会把当前分片的文件写入同一个首个 `--timings` 路径——Bun 不会自动为每个分片选择不同的输出路径，因此需要为每个分片指定不同的输出路径，避免覆盖其他分片的耗时记录；多次指定 `--timings=<file>`，例如每个分片一个，可将它们合并为一张表一起读取）。示例：`bun test --parallel --timings=./test-timings.json --update-timings`。具体参数行为请以本地 `bun test --help` 输出为准。
|
||||
Bun 1.4 中可用于 CI 的选项包括：选择受影响测试的 `bun test --changed[=<ref>]`、提供逐文件全局环境的 `bun test --isolate`、使用工作进程的 `bun test --parallel[=<n>]`，以及划分 CI 任务的 `bun test --shard=<n>/<count>`。`--isolate` 在同一进程内为每个文件创建新的 JavaScript 全局环境，并清理文档列出的逐文件资源；它不是进程或安全沙箱。`--parallel` 默认启用该选项。`--timings=<file>` 读取以往耗时以供调度，`--update-timings` 记录耗时。示例：`bun test --parallel --timings=./test-timings.json --update-timings`。为多个分片选择耗时文件路径前，请查阅已安装版本的帮助和文档。
|
||||
|
||||
```typescript
|
||||
// test/example.test.ts
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -18,19 +18,19 @@ Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/te
|
||||
|
||||
## How It Works
|
||||
|
||||
- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags have changed across major versions.
|
||||
- **Version baseline**: guidance below targets Bun 1.4.x. Check the actual version with `bun --version` before relying on flag names, since CLI flags can change between releases.
|
||||
- **Runtime**: Drop-in Node-compatible runtime, built on JavaScriptCore. As of Bun 1.4 the runtime itself is implemented in Rust (migrated from Zig). Not 100% Node-compatible — some native addons, less-common `node:` internal APIs, and packages that depend on Node-specific internals can still fail; verify before depending on it in production.
|
||||
- **Package manager**: `bun install` is typically faster than npm/yarn; actual gains depend on project size, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`.
|
||||
- **Package manager**: Bun includes a package manager; installation performance depends on the project, network conditions, and cache state. Lockfile is `bun.lock` (text) by default in current Bun; older versions used `bun.lockb` (binary) — Bun still reads that format for migration, but new projects should use `bun.lock`.
|
||||
- **Bundler**: Built-in bundler and transpiler for apps and libraries.
|
||||
- **Test runner**: Built-in `bun test` with a Jest-like API.
|
||||
|
||||
**Migration from Node**: Replace `node script.js` with `bun run script.js` or `bun script.js`. Run `bun install` in place of `npm install`; most packages work. Use `bun run` for npm scripts; `bun x` for npx-style one-off runs. Node built-ins are supported; prefer Bun APIs where they exist for better performance.
|
||||
|
||||
**Package and workspace commands**: `bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` manage dependencies; `bun outdated` lists stale deps; `bun pm ls` shows the dependency tree derived from the lockfile (not a listing of what's actually on disk). Read-only inspection: `bun audit` reads `bun.lock` and sends the package list to the npm advisory endpoint (or each scoped registry's own advisory endpoint) to report known vulnerabilities — it doesn't touch local files, but it isn't offline, so on private projects only use an approved registry/advisory endpoint, since package names and versions (including private ones) leave the machine. Modifying: `bun audit fix` applies fixes, `bun dedupe` collapses duplicate installs, and `bun prune` removes packages no longer referenced. Monorepos use a root `workspaces` array in `package.json` (same convention as npm/yarn); run a script in one workspace with `bun run --filter <pkg-name> <script>`.
|
||||
**Package and workspace commands**: `bun add <pkg>` / `bun remove <pkg>` / `bun update [pkg]` manage dependencies; `bun outdated` lists stale deps. `bun pm ls` lists project dependencies and resolved versions using the lockfile; `--all` includes transitive dependencies. It is not an integrity check of installed file contents. [`bun audit`](https://bun.com/docs/pm/cli/audit) queries registry advisories using package names and versions from `bun.lock`; it does not modify `package.json`, `bun.lock`, or `node_modules`. Review approved destinations before sending private package metadata. Packages whose scoped registry lacks an advisory endpoint are skipped and do not affect the exit code. `bun audit fix` upgrades and installs dependencies, changing the lockfile and installed packages and sometimes direct version pins; review it as a modifying install operation, including applicable lifecycle scripts. `bun dedupe` collapses duplicate installs, and `bun prune` removes packages no longer referenced. Monorepos use a root `workspaces` array in `package.json` (same convention as npm/yarn); run a script in one workspace with `bun run --filter <pkg-name> <script>`.
|
||||
|
||||
**Built-in APIs**: reach for these before adding a dependency — `Bun.file` / `Bun.write` for file I/O, `bun:sqlite` for an embedded SQLite database, `Bun.serve` for an HTTP/WebSocket server, [`Bun.sql`](https://bun.com/docs/runtime/sql) for SQL databases, [`Bun.redis`](https://bun.com/docs/runtime/redis) for Redis, and [`Bun.S3Client`](https://bun.com/docs/runtime/s3) for S3-compatible object storage. See the [1.4 release notes](https://bun.com/blog/bun-v1.4) for the rest of what's new.
|
||||
|
||||
**Vercel**: Set `bunVersion: "1.4.x"` in `vercel.json` to use Bun 1.4 (Rust runtime) — `"1.x"` currently still resolves to the older 1.3.14. See [Vercel's Bun runtime docs](https://vercel.com/docs/functions/runtimes/bun). Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
|
||||
**Vercel**: Set `bunVersion: "1.4.x"` in `vercel.json` to use Bun 1.4 (Rust runtime). See [Vercel's Bun runtime docs](https://vercel.com/docs/functions/runtimes/bun). Build: `bun run build` or `bun build ./src/index.ts --outdir=dist`. Install: `bun install --frozen-lockfile` for reproducible deploys.
|
||||
|
||||
**Reference**: [Bun 1.4 release notes](https://bun.com/blog/bun-v1.4).
|
||||
|
||||
@@ -62,7 +62,7 @@ bun test
|
||||
bun test --watch
|
||||
```
|
||||
|
||||
For CI, Bun 1.4's test runner adds: `bun test --changed[=<ref>]` (run test files affected by changes vs. a git commit/branch — includes tests exercising changed source files, not just edited test files), `bun test --isolate` (fresh global object per test file, so leaked handles in one file can't affect another; implied by `--parallel`), `bun test --parallel[=<n>]` (run test files across N worker processes, defaults to CPU core count), `bun test --shard=<n>/<count>` (split one suite across CI runners), and `bun test --timings=<file>` (reads JSON per-file duration data to front-load the slowest files) with `--update-timings` (writes to the first `--timings` path given — without `--shard` it merges into existing entries; with `--shard` it writes only the current shard's files to that same first `--timings` path — Bun does not pick a different path per shard automatically, so choose a distinct output path for each shard to avoid overwriting other shards' timing records; pass `--timings` multiple times, once per shard file, to read them together as a single combined table). Example: `bun test --parallel --timings=./test-timings.json --update-timings`. Run `bun test --help` locally to confirm exact flag behavior for your installed version.
|
||||
For CI on Bun 1.4, available options include `bun test --changed[=<ref>]` for affected tests, `bun test --isolate` for per-file globals, `bun test --parallel[=<n>]` for worker processes, and `bun test --shard=<n>/<count>` for CI partitioning. `--isolate` creates a fresh JavaScript global for each file in the same process and cleans up documented per-file resources; it is not a process or security sandbox. `--parallel` enables it by default. `--timings=<file>` reads prior durations for scheduling; `--update-timings` records durations. Example: `bun test --parallel --timings=./test-timings.json --update-timings`. Check the installed version's help and documentation before choosing timing-file paths for a multi-shard workflow.
|
||||
|
||||
```typescript
|
||||
// test/example.test.ts
|
||||
|
||||
Reference in New Issue
Block a user