@console-one/collections

A home for collection data structures with different referencing and observation techniques. Package grows over time as new queue variants and collection types are needed.

Current contents

Class	File	Purpose
`LinkedQueue<T>`	`src/linked-queue.ts`	Plain doubly-linked FIFO queue. No events, no insert-at-node. Use when you just want a fast queue.
`ObservableQueue<T>`	`src/observable-queue.ts`	Doubly-linked FIFO queue with `on(event, handler)` push listeners and `insert(data).before(node)` / `.after(node)` for positional insertion. Use when you need to react to pushes or splice items by node reference.
`IndexMap<T>`	`src/index-map.ts`	Map keyed by a monotonic counter — keys are unique and never reused. `lock()` reserves a key before the value is ready; `set(key, value)` fills it later. `indexLock()` returns an `IndexLock<T>` handle carrying a back-reference so a listener can un-register itself from inside its own closure. Useful for subscription IDs, allocation slots, and self-removing callbacks.
`LinkedHeap<T>`	`src/linked-heap.ts`	Key-addressable binary heap whose items are exposed as `HeapNode` handles. Callers can `update(data)` in-place (preserving identity across rebalance), `remove(key)` by key, detach a node without reshaping, and async-iterate neighbors via `nextNode()` / `prevNode()`. Suitable for schedulers, priority queues whose priorities change, and reactive UIs.

Future variants planned: different backing structures (array ring, chunked), different reference techniques (weak refs, handle-based), different observation models (per-item subscriptions, batched flush events).

Install

npm install @console-one/collections

Usage

LinkedQueue — the minimal case

import { LinkedQueue } from '@console-one/collections'

const q = LinkedQueue.of(1, 2, 3)
q.shift()   // 1
q.shift()   // 2
q.peak()    // 3 (peek without removing)
q.length    // 1

ObservableQueue — when you need push hooks or node-positional inserts

import { ObservableQueue } from '@console-one/collections'

const q = new ObservableQueue<string>()

// React to pushes
q.on('push', (unsub) => (newNodes, queue) => {
  console.log('pushed', newNodes.length, 'items; queue size:', queue.length)
})

q.push('alpha')
q.push('beta', 'gamma')

// Splice by node reference
q.push(1, 2, 4)  // [1, 2, 4]
const lastNode = q.last!
q.insert(3).before(lastNode)  // [1, 2, 3, 4]

IndexMap — stable handles before values exist

import { IndexMap } from '@console-one/collections'

const subs = new IndexMap<(msg: string) => void>()
const id = subs.store((msg) => console.log(msg))
// ... later
subs.delete(id)   // keys are never reused — safe to hand to external code

// Reserve a slot, fill it later:
const slot = subs.lock()
// ... wiring happens, the handler is built
subs.set(slot, (msg) => console.log('late', msg))

// IndexLock — self-unsubscribing listener
const lock = subs.indexLock()
lock.set((msg) => {
  if (msg === 'done') lock.remove()   // callback un-registers itself
  else handle(msg)
})

LinkedHeap — priority queue with stable handles

import { LinkedHeap, HeapNode } from '@console-one/collections'

const heap = new LinkedHeap<{ id: string; priority: number }>(
  (a, b) => a.data.priority - b.data.priority,
  (data) => data.id,   // mapper: derive the key from the value
)

const job = heap.push({ id: 'job-1', priority: 5 })
heap.push({ id: 'job-2', priority: 1 })

heap.peak()             // { id: 'job-2', priority: 1 }
job.update({ id: 'job-1', priority: 0 })  // in-place reprioritize
heap.peak()             // { id: 'job-1', priority: 0 }

// Async neighbor iteration — yields existing then future pushes
for await (const neighbor of heap.startNode!.nextNode()) {
  console.log('neighbor', neighbor.data)
}

Subpath imports

You can import each class directly if you want to avoid loading the others:

import { LinkedQueue } from '@console-one/collections/linked-queue'
import { ObservableQueue } from '@console-one/collections/observable-queue'
import { IndexMap, IndexLock } from '@console-one/collections/index-map'
import { LinkedHeap, HeapNode } from '@console-one/collections/linked-heap'

Shared API

Both queues implement the same base FIFO interface. They only differ in the extras that ObservableQueue adds.

Common methods

Method	Description
`push(...items)`	Append one or more items to the tail. Returns a queue of any items that were flushed due to `maxSize` overflow.
`prepend(item)`	Insert an item at the head.
`shift()` / `pull()`	Remove and return the head item. Applies `pipe` option if configured. Throws if empty.
`remove()`	Like `shift()` but without applying `pipe`. Throws if empty.
`peak()`	Return the head item without removing it. Throws if empty.
`isEmpty()`	True iff there are no items.
`length` / `size`	Current number of items.
`concat(other)`	Append all items from another queue.
`clear()`	Remove everything. Chainable.
`toArray()`	Materialize as a JS array, head first.
`toString()`	Pretty-printed JSON of `toArray()`.
`headIs(pred)`	Safe predicate check on the head; returns `false` if empty.
`flush(n)`	Generator that pops up to `n` items.
`readHead(n?)`	Generator over head-first items without consuming.
`readTail(n?)`	Generator over tail-first items without consuming.
`[Symbol.iterator]()`	Iterable, head first.
`static describes(x)`	Type guard for instances of this queue class.
`static fromArray(arr)`	Construct from an array.
`static of(...items)`	Construct from varargs.

Constructor options

Both queues accept the same options:

new LinkedQueue<T>(maxSize?: number, { pipe?, chain? })

maxSize — bound the queue. Items past the bound are flushed from the head. Default Number.POSITIVE_INFINITY.
pipe — transform applied on shift() / pull(). Leaves remove() untouched.
chain — factory for the "overflow" queue returned by push() when a bounded queue discards items.

ObservableQueue extras

Method	Description
`on(event, create)`	Subscribe to a queue event (`'push'`). `create(unsub)` must return the actual handler; you get an unsubscribe function to close over.
`insert(data).before(node)` / `.after(node)`	Splice a new item at a specific node position. Takes a `QueueItem` reference (from `q.first`, `q.last`, or walking `.next` / `.prev`).

Known quirks

nodes() and some iterator loops use a !== vs || mix that can look infinite at a glance. They terminate because next becomes undefined. Don't use nodes() as a general-purpose iterator — use readHead() / [Symbol.iterator] instead.
maxSize overflow pushes into a secondary "chain" queue rather than silently dropping. The chain is created fresh on each push() call, so you don't accumulate one global overflow buffer.
pipe only runs on shift() / pull(), not on remove() or iterators.

Tests

npm test

46 tests covering FIFO semantics, insertion, options, overflow, event hooks, index-map lock/set/delete + IndexLock self-unsubscribe, and linked-heap push/pop/update/remove/async iteration.