node-queue

CPU-based process queue daemon that throttles test runners (vitest, jest, playwright) to prevent system overload during development.

Features

• CPU Monitoring: Continuously monitors system CPU usage (overall and system/kernel)
• Daemon Architecture: Background daemon manages queued processes via Unix socket
• Test Runner Interception: Transparently intercepts vitest, jest, and playwright commands
• CLI Management: Full CLI for daemon control, installation, and status monitoring
• Session Metrics: Tracks queue statistics, wait times, and peak usage
• Graceful Fallback: Falls back to direct execution if daemon is unavailable

Installation

npm install -g @doryski/node-queue
# or
pnpm add -g @doryski/node-queue

Quick Start

1. Install and start the daemon

# Install shims and PATH configuration
npx node-queue install

# Start the daemon (runs in background)
npx node-queue start

# Or run in foreground for debugging
npx node-queue start -f

2. Check status

npx node-queue status

3. Use normally

Once installed, your test commands (vitest, jest, playwright) will automatically be queued when CPU usage is high.

CLI Commands

Command	Description
start [-f]	Start daemon (use -f for foreground)
stop	Stop the daemon
status	Show daemon status, CPU stats, and queue
install	Install PATH modification and build shims
uninstall	Remove PATH modification and LaunchAgent
build	Build shims only (without PATH installation)
logs [-f] [-n N]	Show daemon logs (use -f to follow)
install-project [-r]	Patch node_modules/.bin in the current project (auto-run by the pnpm/npm wrappers)
uninstall-project	Remove patches from node_modules/.bin
patch-all --base <dir>	Recursively patch every project under <dir>. Registers the base for future re-runs
patch-all	Re-run patch-all against every previously registered base
patch-all --forget <dir>	Remove a base from the registry

Configuration

Environment Variables

Variable	Description
NODE_QUEUE_BYPASS=1	Skip queueing, run directly
NODE_QUEUE_TIMEOUT=N	Custom timeout in milliseconds (default: 60000)
NODE_QUEUE_DEBUG=1	Enable debug logging in shims

Thresholds

Default thresholds (in src/config.ts):

• maxOverallCpu: 50% - Queue when overall CPU exceeds this
• maxSystemCpu: 20% - Queue when system/kernel CPU exceeds this

Auto-Patch Wrappers

The library only intercepts commands that go through the shims on your PATH. Locally-resolved binaries (anything in ./node_modules/.bin, which is what pnpm exec vitest, npm test, and editor test runners use) are not intercepted until you patch them with install-project. To avoid running that manually after every pnpm install, node-queue install offers to add pnpm/npm shell wrappers to your shell rc file.

When accepted, the installer appends a guarded block to ~/.zshrc / ~/.bashrc / fish config (wrapped in # node-queue auto-patch wrappers ... # node-queue auto-patch wrappers end markers):

• pnpm install|i|add → runs the real pnpm, then runs node-queue install-project -p . if ./node_modules/.bin exists
• npm install|i|add → same, for npm

Opting out: answer "no" to the prompt during install. Removing later: node-queue uninstall strips the block cleanly.

Bulk Patching Existing Projects

For one-shot patching of every project under a directory (useful on a fresh machine, or after upgrading node-queue):

# Patch everything under ~/projects and register the base
node-queue patch-all --base ~/projects

# Later, re-run against all registered bases (e.g. after re-installing deps across many repos)
node-queue patch-all

# Stop tracking a base
node-queue patch-all --forget ~/projects

Registered bases are stored at ~/.node-queue/config.json. The walker skips node_modules (except the top-level .bin it finds), .pnpm, .git, .next, dist, build, and other common build/VCS directories.

How It Works

1. Shim Installation: Creates lightweight shims in ~/.node-queue/bin/ for each intercepted binary
2. PATH Modification: Adds shim directory to the front of PATH
3. Interception: When you run vitest (or other intercepted command), the shim runs instead
4. Queue Check: Shim connects to daemon, which checks current CPU usage
5. Decision: If CPU is low, command runs immediately. If high, it's queued until CPU drops.

Intercepted Commands

• vitest
• jest
• playwright

Programmatic Usage

import { createCpuMonitor, createProcessQueue, createMetricsTracker } from '@doryski/node-queue';

// Create a CPU monitor
const monitor = createCpuMonitor(500);
await monitor.start();

// Get current stats
const stats = monitor.getStats();
console.log(`CPU: ${stats.overall}%`);

// Create a queue
const queue = createProcessQueue(100);

Platform Support

• macOS: Full support including LaunchAgent for auto-start on login
• Linux: Core daemon and queueing work; no systemd service file included yet (PRs welcome)
• Windows: Not supported — the daemon uses Unix sockets and POSIX signals

Note: The install command's LaunchAgent setup is macOS-only. On Linux, you'll need to manage the daemon process yourself (e.g., via systemd or a process manager).

Releasing

Releases are driven by a git tag and published automatically by GitHub Actions.

pnpm release

The interactive script:

1. Verifies the working tree is clean and you're on main.
2. Proposes the next patch version (based on the latest v* tag) — you can override.
3. Bumps package.json, commits, tags vX.Y.Z, and pushes both.

On tag push, .github/workflows/release.yml runs build + lint + tests, verifies package.json matches the tag, then publishes to npm with provenance and creates a GitHub Release with auto-generated notes.

One-time setup: add an NPM_TOKEN repository secret (create an automation token at https://www.npmjs.com/settings/~/tokens, scope Automation or Publish).

License

MIT