| name | benchmark |
| description | Run sparkid benchmarks. Use when the user asks to benchmark, profile, or measure performance of any sparkid package. Triggers on 'benchmark', 'bench', 'perf', 'performance', 'how fast'. |
Benchmark Skill
Run benchmarks for sparkid packages. Never run benchmarks concurrently — always run one at a time, sequentially. Concurrent benchmarks compete for CPU and produce unreliable results.
When the user asks to benchmark, determine which specific benchmark they need and run only that one. Do not run all benchmarks unless explicitly asked.
Available Benchmarks
JavaScript (js/)
All commands run from the js/ directory.
| Command | What it measures |
|---|
npm run bench | sparkid generateId() throughput (1M iterations, 5 trials) + binary toBytes/fromBytes |
npm run bench:compare | sparkid vs uuid v4, uuid v7, nanoid, ulid (100K iterations) |
npm run bench:binary | Binary encoding/decoding only (toBytes/fromBytes) |
Python (python/)
All commands run from the python/ directory. Requires Python 3.14+ for --compare (uses uuid.uuid7).
| Command | What it measures |
|---|
uv run python bench/benchmark.py | sparkid generate_id() throughput (1M iterations, 5 trials) |
uv run python bench/benchmark.py --compare | sparkid vs uuid4, uuid7, nanoid, ulid, ksuid |
uv run python bench/benchmark.py --binary | Binary encoding/decoding only (to_bytes/from_bytes) |
Ensure deps are installed first: uv sync --all-groups
Rust (rust/)
All commands run from the rust/ directory. Uses Criterion for statistical benchmarking.
| Command | What it measures |
|---|
cargo bench | All Rust benchmarks (generator, thread-local, parse, from_u128, from_bytes, comparison) |
cargo bench -- "IdGenerator::next_id" | IdGenerator::next_id only (direct generator) |
cargo bench -- "SparkId::new" | SparkId::new only (thread-local path) |
cargo bench -- "from_str" | SparkId::from_str parsing only |
cargo bench -- "from_u128" | SparkId::from_u128 binary validation only |
cargo bench -- "from_bytes" | SparkId::from_bytes binary validation only |
cargo bench -- "id_generators" | Comparison group only (sparkid vs uuid v4/v7, nanoid, ulid) |
Cross-language comparison (repo root)
| Command | What it measures |
|---|
python bench_compare.py | Runs all three language benchmarks and produces a comparison chart |
Decision Guide
- "How fast is sparkid?" → Run the core benchmark for the relevant language (
npm run bench, uv run python bench/benchmark.py, or cargo bench -- "IdGenerator::next_id")
- "How does it compare to X?" → Run the comparison benchmark for the relevant language
- "Is binary encoding fast?" → JS:
npm run bench:binary, Python: --binary flag, Rust: cargo bench -- "from_u128\|from_bytes"
- "Benchmark everything" → Run each language's full benchmark sequentially, one after another
- "I changed the generator" → Run only the core benchmark for the language that was changed
