A tiny and simple FIFO queue with decent performance.
- Simple interface
- 342 bytes minified (204 bytes gzipped)
- Documentation and TypeScript declarations
- Tests and benchmarks
- No dependencies
- Public domain
Use your package manager of choice:
npm install @joakimstai/q
pnpm add @joakimstai/q
The library targets ES2020.
Import Q
using the appropriate method for your environment:
import { Q } from '@joakimstai/q'
const { Q } = require('@joakimstai/q')
const queue = new Q()
Optionally, specify an array of items up front:
const queue = new Q([1, 2, 3])
queue.push(4)
queue.shift() // 1
queue.at(0) // 2 (front)
queue.at(1) // 3
queue.at(-1) // 4 (back)
queue.size() // 3
while (queue.hasItems()) { … // true
queue.toArray() // [2, 3, 4]
queue.reset()
Optionally, specify an array of items to reset to:
queue.reset([1, 2, 3])
That's it.
Below are the results of benchmarks adapted from denque
and fast-fifo
. They were executed on JavaScriptCore with bun run
, using tinybench
, on a 2018 Mac Mini (3 GHz 6-Core Intel Core i5).
According to these benchmarks, Q
is about 2 × faster than using Array
as a makeshift queue. It's not able to match the highly optimized denque
and fast-fifo
libraries, but is an alternative when size is important, and it should be more than performant enough for most use cases. Pretty decent for 342 bytes.
The high margin of error on the results of Q
is notable, though the results are relatively stable across runs. Benchmarking is not my strong suit, so I can't really offer an explanation or analysis. Take it for what it is. YMMV, grain of salt and all that.
┌───┬───────────────────┬─────────┬────────────────────┬─────────┬─────────┐
│ │ Task Name │ ops/sec │ Average Time (ns) │ Margin │ Samples │
├───┼───────────────────┼─────────┼────────────────────┼─────────┼─────────┤
│ 0 │ bulk:denque │ 56,922 │ 17567.660880000152 │ ±0.07% │ 100000 │
│ 1 │ bulk:fifo │ 53,502 │ 18690.82211000017 │ ±0.07% │ 100000 │
│ 2 │ bulk:q │ 34,965 │ 28599.61588000114 │ ±57.44% │ 100000 │
│ 3 │ bulk:array │ 16,025 │ 62401.65270999802 │ ±0.24% │ 100000 │
│ 4 │ individual:denque │ 57,640 │ 17348.849719997284 │ ±0.10% │ 100000 │
│ 5 │ individual:fifo │ 53,131 │ 18821.2484400024 │ ±0.08% │ 100000 │
│ 6 │ individual:q │ 30,898 │ 32364.489050003427 │ ±94.29% │ 100000 │
│ 7 │ individual:array │ 20,632 │ 48467.935640011136 │ ±0.30% │ 100000 │
└───┴───────────────────┴─────────┴────────────────────┴─────────┴─────────┘
┌───┬───────────┬────────────┬────────────────────┬─────────┬─────────┐
│ │ Task Name │ ops/sec │ Average Time (ns) │ Margin │ Samples │
├───┼───────────┼────────────┼────────────────────┼─────────┼─────────┤
│ 0 │ denque │ 11,782,944 │ 84.86842916873053 │ ±0.09% │ 5891473 │
│ 1 │ fifo │ 10,811,026 │ 92.49815410713445 │ ±0.12% │ 5405514 │
│ 2 │ q │ 9,667,354 │ 103.44091228259218 │ ±35.83% │ 4833678 │
│ 3 │ array │ 4,366,517 │ 229.01543930422363 │ ±5.63% │ 2183259 │
└───┴───────────┴────────────┴────────────────────┴─────────┴─────────┘