FlatQueue

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` to import `flatqueue` after it became an ESM-only package.
  fix Update your import statement to `import FlatQueue from 'flatqueue';` and ensure your project's `package.json` specifies `"type": "module"` if running in Node.js, or use a bundler configured for ESM.

• Perceived 'memory leak' or unexpectedly high memory usage over time.

  cause The internal `ids` and `values` arrays do not automatically resize down after `pop()` or `clear()` operations to improve performance by avoiding frequent reallocations.
  fix Call `queue.shrink()` manually to trim the internal arrays to the current `length` of the queue, freeing unused memory. This should be done when memory usage is a concern or after significant reduction in queue size.

• TypeError: Cannot read properties of undefined (reading 'id') (or similar for other properties)

  cause Attempting to access properties of the return value from `peek()` or `pop()` when the queue is empty. Both methods return `undefined` when the queue contains no items.
  fix Always check if the return value of `peek()` or `pop()` is `undefined` before attempting to access its properties. For example: `const item = q.pop(); if (item !== undefined) { console.log(item.id); }`

Warnings

• breaking FlatQueue transitioned to ESM-only in v2.0.0, dropping the CommonJS entry point. In v3.0.0, the legacy UMD bundle was also removed. Direct CommonJS `require()` statements will fail.
  Fix: Migrate your project to use ES module imports (`import FlatQueue from 'flatqueue';`) and ensure your environment (Node.js, bundler) is configured for ESM (e.g., `"type": "module"` in package.json).
• gotcha The `pop()` and `clear()` methods do not automatically shrink the internal arrays (`ids` and `values`) to free memory. This behavior is intentional to improve performance by avoiding unnecessary reallocations during intensive reuse, but can lead to higher memory consumption if the queue size frequently fluctuates downwards and isn't explicitly managed.
  Fix: To explicitly release unused memory after extensive `pop()` or `clear()` operations, call `queue.shrink()`.
• gotcha FlatQueue is not 'stable' for items with identical priority values. If multiple items share the same lowest priority, there is no guarantee which of them will be returned first by `pop()` or `peek()`.
  Fix: If deterministic ordering for same-priority items is required, you must incorporate a secondary sorting criterion into your priority value (e.g., by combining priority with a stable index) or use a different priority queue implementation.
• gotcha For maximum performance and memory efficiency, especially when the maximum queue size is known, you can override the internal `ids` and `values` arrays with typed arrays (e.g., `Uint16Array`, `Uint32Array`).
  Fix: Before pushing items, initialize `q.ids = new Uint16Array(maxSize);` and `q.values = new Uint32Array(maxSize);`.

Install

• npm install flatqueue npm
• yarn add flatqueue yarn
• pnpm add flatqueue pnpm

Imports

• FlatQueue
  wrong:

  const FlatQueue = require('flatqueue');

  correct:

  import FlatQueue from 'flatqueue';

  FlatQueue is ESM-only since v2.0.0. UMD bundles were dropped in v3.0.0.
• FlatQueue (CDN)

  import FlatQueue from 'https://cdn.jsdelivr.net/npm/flatqueue/+esm';

  For direct browser usage as an ES module via CDN.
• TypeScript Types

  import FlatQueue from 'flatqueue'; // Types are inferred via JSDoc

  The package ships with first-class TypeScript types, automatically picked up by TypeScript compilers without explicit type imports.

Quickstart

This example demonstrates how to create a FlatQueue, push items with associated priorities, peek at the top item, pop the lowest-priority item, and clear the queue. It highlights basic API usage and the queue's length property.

import FlatQueue from 'flatqueue';

interface Item {
  id: number;
  priority: number;
  data: string;
}

const q = new FlatQueue();

const items: Item[] = [
  { id: 0, priority: 5, data: 'task A' },
  { id: 1, priority: 1, data: 'task B' },
  { id: 2, priority: 8, data: 'task C' },
  { id: 3, priority: 2, data: 'task D' }
];

console.log('Pushing items...');
for (let i = 0; i < items.length; i++) {
  // Push the item's original ID (or the item itself) and its priority value.
  // Storing only integers (like IDs/indices) is generally faster for JavaScript engine optimizations.
  q.push(items[i].id, items[i].priority);
}

console.log(`\nQueue length: ${q.length}`);
console.log(`Top item (ID): ${q.peek()}`); // Expected: 1 (ID of task B)
console.log(`Top item priority: ${q.peekValue()}`); // Expected: 1

const poppedId = q.pop(); // Removes ID 1
console.log(`Popped item ID: ${poppedId}`); // Expected: 1

console.log(`\nNew top item (ID): ${q.peek()}`); // Expected: 3 (ID of task D)
console.log(`New top item priority: ${q.peekValue()}`); // Expected: 2

q.clear();
console.log(`\nQueue length after clear: ${q.length}`); // Expected: 0