⚙️ ArrayQueue Class

⚙️ ArrayQueue Class — Sorting by order of insertion

The ArrayQueue class provides a minimal, array-backed implementation of the abstract Queue. It supports basic FIFO or LIFO ordering, making it suitable for general-purpose queue and stack operations.

📚 Overview

Internally, ArrayQueue stores items in a plain JavaScript array. Its behavior is controlled by a fifo flag:

  • fifo: true → FIFO (queue)
  • fifo: false → LIFO (stack)

All items are treated as distinct — no identity or value-based equality checks are performed. This means:

  • has(item) always returns false
  • remove(item) always returns false

🧩 Constructor

new ArrayQueue(fifo = true, items = [])
  • fifo: Boolean flag to toggle between FIFO and LIFO behavior.
  • items: Optional array to seed the queue.

🧪 Public API

get fifo(): boolean

Returns whether the queue uses FIFO ordering.

get items(): Array<any>

Exposes the internal storage array (use with caution).

n(): number

Returns the current number of elements in the queue.

has(item): boolean

Always returns false.
In ArrayQueue, no item is considered equivalent to any other — not even itself.

add(item): boolean

Adds an item to the end of the queue. Always returns true.

remove(item): boolean

Always returns false. Value-based removal is unsupported.

peek(first = true): any

Returns the item at the head or tail:

  • first = true: returns the first item (according to fifo).
  • first = false: returns the last item.

poll(first = true): any

Removes and returns the item at the head or tail:

  • first = true: removes from front.
  • first = false: removes from end.

clear(): void

Removes all items from the queue.

[Symbol.iterator](): Iterator<any>

Returns a forward iterator over the queue’s items.

reverse(): Each<any>

Returns an iterable (Each) yielding items in reverse order.
This is a view — not a reversed copy or a new queue.

🧠 Design Notes

  • ArrayQueue is optimized for simplicity, speed, and minimal assumptions.
  • Items are added fast, removed fast, and iterated efficiently.
  • Use it when you need a lightweight FIFO or LIFO queue with no equivalence checking.
  • All items are treated as distinct — even identical ones. No value is considered equal to any other.

✍️ Example

const q = new ArrayQueue(true);
q.add("🍎");
q.add("🍌");
q.add("🍓");

q.peek();   // → "🍎"
q.poll();   // → "🍎"
q.reverse(); // → Iterable over ["🍓", "🍌"]

“In ArrayQueue, nothing is equal — not even to itself.”
— @fizzwiz ✨


Comments

Post a Comment

Popular posts from this blog

🧠 Contemplating a True Set

🧠 Equivalence in JavaScript: Contemplating a True Set In JavaScript,   equivalence   behaves differently depending on whether you're working with primitive or non-primitive types. For   primitives —such as numbers, booleans, strings, and symbols—equivalence is determined by comparing actual values. If two variables hold the same value, they are considered equivalent. However, for   objects and arrays , equivalence is   by reference . Two arrays   [0]   and   [0]   are not considered equal because they are separate instances, even though they contain identical content. 🔬 Snippet 1: Equivalence by Value and by Reference new Set ([ 0 , 0 ]); // => Set { 0 } new Set ([[ 0 ], [ 0 ]]); // => Set { [0], [0] } JavaScript’s   Set   treats the two   0   values as equivalent but considers   [0]   and   [0]   as distinct because they are different object instances. This reveals JavaScript’s mini...
Read more

🧱 v0.0.0-dev.1 — First Brick

🧱 v0.0.0-dev.1 — First Brick We’re excited to announce the   first prerelease   of   @fizzwiz/sorted :   v0.0.0-dev.1   — the   First Brick   in what aims to become a foundational library for   priority-aware collections   and   custom equivalence models . This release introduces the core building blocks: 🔧 Core Abstractions Collection   – a base interface for iterable containers Queue   – an extension for prioritizing and structuring exploration 📦 Concrete Implementations ArrayQueue   – a simple queue based on insertion order SortedArray   – a comparator-based queue maintaining sorted state These implementations offer different   notions of equivalence   — by insertion order or by comparator — laying the groundwork for more powerful models based on   representation functions , coming soon. 🧪 This is a   prerelease , but it’s ready to explore. Your early feedback will help guide the evolution o...
Read more

☯️ v0.0.0-dev.3 — Classifier & TrueSet

☯️ v0.0.0-dev.3 — Classifier & TrueSet We’re thrilled to announce   v0.0.0-dev.3   of   @fizzwiz/sorted , introducing two powerful new abstractions:   Classifier   and   TrueSet . This release takes the library far beyond simple sorted collections, enabling   hierarchical keys ,   prefix queries , and   representation-based equivalence . 🔧 Core Enhancements Classifier   — a rich, multidimensional map A   Classifier   stores entries whose keys are   arrays (any iterable) . It supports: Storing multiple items per key Efficient   prefix queries   with wildcards Sorted traversal of both keys and items Flexible equivalence via custom sorting rules TrueSet   — a representation-based set A   TrueSet   defines equivalence using a   representation function   ( repr ). It enables: Equivalence among   objects , not just primitives Aggregation of equivalent items in sorted, enumerable class...
Read more