name: updating-fast-webstreams
description: Vendors fast-webstreams from npm to additions/, converting ESM to CommonJS with primordials for Node.js bootstrap. Use when the WebStreams version needs update or builds fail with streams errors.
user-invocable: true
allowed-tools: Bash(pnpm:), Bash(npm:), Bash(git:), Bash(node:), Bash(rg:), Bash(grep:), Bash(find:), Bash(ls:), Bash(cat:), Bash(head:), Bash(tail:), Bash(wc:), Bash(diff:*), Read---
updating-fast-webstreams
Synchronize experimental-fast-webstreams from node_modules to the vendor directory, converting ES modules to CommonJS for Node.js internal module system.
Vercel's library replaces Node.js pure-JS WebStreams with native C++ stream-backed implementations (3-15x faster).
Key Constraints
- Use absolute internal paths:
require('internal/deps/fast-webstreams/utils') not require('./utils.js')
- Use individual
exports.X = X; at file end (not module.exports = {})
- The sync script handles ES-to-CJS conversion and primordials transforms automatically
- Do not modify converted files manually; re-run sync instead
Process
Sync
node packages/node-smol-builder/scripts/vendor-fast-webstreams/sync.mts
Build (skip in CI)
pnpm --filter node-smol-builder clean && pnpm --filter node-smol-builder build
Validate
Quick (15 tests): node packages/node-smol-builder/scripts/vendor-fast-webstreams/validate.mts
Full WPT (1,116 tests): pnpm --filter node-smol-builder run wpt:streams (options after --: --force, --filter=, --verbose). Also wired into pnpm test via test/integration/wpt-streams.test.mts (gated on a built binary being present).
Update Version
- Edit
packages/node-smol-builder/package.json devDependencies
pnpm install- Run sync, clean, rebuild, validate
Circular Dependencies
Two cycles require special handling (managed by sync.mts):
- patch.js <-> index.js: Import directly from source modules, not index.js
- writer.js <-> writable.js: Use module reference pattern (access at runtime, not load time)
Key Files
| File | Purpose |
|---|
scripts/vendor-fast-webstreams/sync.mts | ES-to-CJS conversion |
scripts/vendor-fast-webstreams/validate.mts | 15-test integration suite |
test/scripts/wpt-streams-runner.mts | WPT spec compliance (rich CLI runner) |
test/integration/wpt-streams.test.mts | WPT vitest wrapper (gates via pnpm test) |
test/fixtures/wpt/streams/ | WPT sparse submodule (just streams/ subtree) |
test/fixtures/wpt/{harness,run-file}.mjs | In-binary WPT harness + per-file runner |
additions/source-patched/deps/fast-webstreams/ | Converted CommonJS (14 files) |
