Queue

Queue<T> is a standalone FIFO/priority queue for modeling buffers, pipelines, conveyor belts, and WIP limits. Supports bounded capacity with overflow policies (drop or block).

Quick Start


import { SimulationEngine, Queue } from 'simloop';
 
type Events = {
  'item:produce': { itemId: number };
  'item:consume': Record<string, never>;
};
 
const sim = new SimulationEngine<Events>({ seed: 42 });
const buffer = new Queue<number>('buffer', { maxCapacity: 5 });
 
sim.on('item:produce', (event, ctx) => {
  buffer.enqueue(ctx, event.payload.itemId);
  ctx.schedule('item:produce', ctx.clock + ctx.dist.exponential(1)(), {
    itemId: event.payload.itemId + 1,
  });
});
 
sim.on('item:consume', (_e, ctx) => {
  const item = buffer.dequeue(ctx);
  if (item !== undefined) ctx.stats.increment('consumed');
  ctx.schedule('item:consume', ctx.clock + ctx.dist.exponential(0.8)(), {});
});

Queue vs Resource

	Queue	Resource
Models	Buffers, pipelines, WIP limits	Servers, machines, staff
Pattern	enqueue → wait → dequeue	seize → delay → release
Items	Typed values (`Queue<T>`)	Anonymous slots
Capacity	Bounded or unbounded	Always bounded (>= 1)
Overflow	Drop or block	Always queues

Constructor


const queue = new Queue<T>(name, options?);

Option	Type	Default	Description
`maxCapacity`	`number`	`Infinity`	Maximum number of items. Must be > 0.
`overflowPolicy`	`'drop' \| 'block'`	`'drop'`	Behavior when enqueueing to a full queue.
`statsPrefix`	`string`	`name`	Prefix for all auto-collected stat keys.

`queue.enqueue(ctx, item, options?)`

Has space: item is inserted in priority order, returns true.
Full + 'drop': returns false, item is discarded.
Full + 'block': returns false, item is held and auto-admitted when dequeue() frees a slot.

Option	Type	Default	Description
`priority`	`number`	`0`	Lower value = higher precedence. FIFO within same priority.

`queue.dequeue(ctx)`

Removes and returns the front item. Returns undefined if empty. Automatically admits blocked items when a slot frees up.

`queue.peek()`

Returns the front item without removing it. Does not record any stats.

`queue.snapshot()`

Returns a plain object with the current state. Useful for logging and assertions.


const snap = queue.snapshot();
// { name, maxCapacity, length, items: readonly T[] }

`queue.reset()`

Clears all items, blocked entries, and the insertion counter. Must be called after engine.reset() before re-running the simulation.


sim.reset();
queue.reset(); // ← required
sim.init((ctx) => { /* re-init */ });
sim.run();

Overflow Policies

Drop (default)

Item is silently discarded. Use for systems where items can be lost (network packet buffers, production lines without backpressure).

Block

Item is held in a waiting list and auto-admitted when space frees up. Use for systems with backpressure (conveyor belts, bounded producer-consumer).

Accessors

Accessor	Type	Description
`queue.name`	`string`	Name given at construction
`queue.maxCapacity`	`number`	Maximum capacity
`queue.length`	`number`	Current number of items
`queue.isFull`	`boolean`	`length >= maxCapacity`
`queue.isEmpty`	`boolean`	`length === 0`
`queue.overflowPolicy`	`'drop' \| 'block'`	Overflow behaviour

Priority Queuing

By default, all items have priority = 0 and are served in FIFO order.


queue.enqueue(ctx, item, { priority: 1 });  // high priority
queue.enqueue(ctx, item, { priority: 10 }); // low priority

Within the same priority level, items are served in the order enqueue() was called (FIFO). Negative priorities are allowed — priority is a plain number; the minimum value wins.

Auto-Collected Statistics

All stat keys are prefixed with queue.{name}.:

Key	Description
`queue.{n}.enqueued`	Total successful enqueue operations
`queue.{n}.dequeued`	Total successful dequeue operations
`queue.{n}.throughput`	Alias for dequeued
`queue.{n}.dropped`	Items discarded due to overflow
`queue.{n}.blocked`	Items blocked waiting for space
`queue.{n}.blockTime`	Time from block to admission
`queue.{n}.waitTime`	Time from enqueue to dequeue
`queue.{n}.queueLength`	Queue depth snapshot after each operation

Edge Cases

Dequeue from empty queue

Returns undefined. No stats are recorded.

`maxCapacity = Infinity` (default)

The queue is never full — isFull always returns false, overflowPolicy is irrelevant.

Multiple queues with the same name

Stats will be recorded under the same prefix and merged — producing incorrect statistics. Names (or statsPrefix values) must be unique per simulation instance.