JavaScript Standard Data Structures Library

Common errors

• ReferenceError: OrderedMap is not defined

  cause Attempting to use `OrderedMap` (or other classes) without a proper ESM named import, or an incorrect CommonJS `require` call that does not destructure the named export.
  fix Ensure you are using `import { OrderedMap } from 'js-sdsl';` in ESM or `const { OrderedMap } = require('js-sdsl');` in CJS. For v4+, ESM is highly recommended.

• TypeError: container.set is not a function

  cause This error typically occurs when attempting to call a method like `set` on a variable that is either not an instance of the expected data structure (e.g., `OrderedMap`), or has not been properly initialized.
  fix Verify that `container` is correctly initialized, for example: `const container = new OrderedMap<KeyType, ValueType>();`. Also, ensure you are calling the correct method for the specific data structure (e.g., `OrderedSet` uses `add` instead of `set`).

• Error: Iterator access denied

  cause This error message indicates an invalid operation on an iterator, possibly due to accessing an iterator that has become invalid (e.g., after an element it pointed to was removed) or attempting to dereference an 'end' iterator.
  fix Always check iterator validity before dereferencing or using it. Ensure that modifications to the container do not invalidate active iterators that are subsequently used. The library implements C++ STL-like iterators, so similar rules regarding iterator invalidation apply.

Warnings

• breaking In version 4.x, the classes `Set` and `Map` were renamed to `OrderedSet` and `OrderedMap` respectively. If you are migrating from v3 or earlier, you must update your imports and class instantiations to use the new names to avoid conflicts with native JavaScript `Set` and `Map` objects. Additionally, `eraseElementByValue` on `HashSet` and `OrderedSet` was renamed to `eraseElementByKey` in v4.0.0.
  Fix: Rename `Set` to `OrderedSet` and `Map` to `OrderedMap` in your code. Update method calls from `eraseElementByValue` to `eraseElementByKey` for affected containers.
• gotcha While `js-sdsl` offers high-performance data structures, for very small datasets or simple array/object operations, native JavaScript `Array` or `Map`/`Set` might sometimes exhibit comparable or even better performance due to V8 engine optimizations. `js-sdsl` shines in scenarios requiring specific algorithmic complexities, ordered iteration, or large-scale data manipulation where its optimized implementations provide consistent benefits.
  Fix: Benchmark critical sections of your application to determine if `js-sdsl` provides a meaningful performance improvement for your specific use case, especially for smaller datasets.
• breaking With version 4.1.0, the CommonJS target was changed to ES6. While `js-sdsl` generally aims for broad compatibility, modern Node.js environments and bundlers primarily favor ES Modules (ESM). Using `require()` for named exports in CJS contexts with `js-sdsl` v4+ may lead to unexpected behavior or `undefined` imports.
  Fix: Refactor your module imports to use ESM `import { Name } from 'js-sdsl';` syntax. If you are in a pure CommonJS environment, consider using dynamic `import('js-sdsl').then(...)` or ensure your build setup correctly transpiles ESM to CJS with named exports.
• gotcha Iterator behavior and internal implementations were subject to changes in the 4.x series. Specifically, `OrderedMap`'s iterator pointer retrieval changed from `Object.defineProperty` to `Proxy` in v4.1.4, and iterator type descriptions evolved. While generally backward-compatible for common use, advanced iterator manipulation might require re-testing.
  Fix: If experiencing unexpected iterator behavior, review the `CHANGELOG.md` for your specific `js-sdsl` version regarding iterator updates and adjust custom iterator logic or assumptions accordingly.

Install

• npm install js-sdsl npm
• yarn add js-sdsl yarn
• pnpm add js-sdsl pnpm

Imports

• OrderedMap
  wrong:

  const OrderedMap = require('js-sdsl').OrderedMap;

  correct:

  import { OrderedMap } from 'js-sdsl';

  ESM imports are the recommended standard. For v4+, direct CommonJS `require('js-sdsl').OrderedMap` may not work as expected due to changes in CJS target to ES6 in v4.1.0. Use `import()` for dynamic CJS loading if strictly necessary, but prefer ESM.
• Vector
  wrong:

  const Vector = require('js-sdsl').Vector;

  correct:

  import { Vector } from 'js-sdsl';

  As with all exports from js-sdsl v4+, prefer named ESM imports. This ensures correct tree-shaking and module resolution in modern build environments.
• OrderedSet
  wrong:

  import { Set } from 'js-sdsl'; // Incorrect symbol name for v4+

  correct:

  import { OrderedSet } from 'js-sdsl';

  In version 4.x and later, the `Set` and `Map` classes were renamed to `OrderedSet` and `OrderedMap` respectively to avoid conflicts with native JavaScript `Set` and `Map` global objects.
• Deque
  wrong:

  const Deque = require('js-sdsl'); // CommonJS import often requires destructuring for named exports

  correct:

  import { Deque } from 'js-sdsl';

  Always explicitly import the specific data structure classes you need. Direct `require('js-sdsl')` will not expose the individual classes in a usable way for CJS without further destructuring. ESM named imports are cleaner.

Quickstart

This quickstart demonstrates the instantiation and basic operations of OrderedMap, Deque, and Vector, including adding, retrieving, iterating, and modifying elements.

import { OrderedMap, Deque, Vector } from 'js-sdsl';

// Using an OrderedMap (a sorted map implemented with a red-black tree)
const myOrderedMap = new OrderedMap<string, number>();
myOrderedMap.set('apple', 10);
myOrderedMap.set('banana', 20);
myOrderedMap.set('cherry', 5);
console.log('OrderedMap size:', myOrderedMap.size()); // Output: 3
console.log('Value of apple:', myOrderedMap.get('apple')); // Output: 10
myOrderedMap.forEach((key, value) => {
  console.log(`Map: ${key} -> ${value}`);
});
// Output:
// Map: apple -> 10
// Map: banana -> 20
// Map: cherry -> 5

// Using a Deque (Double-ended queue)
const myDeque = new Deque<string>();
myDeque.pushFront('first');
myDeque.pushBack('second');
myDeque.pushFront('zero');
console.log('Deque elements:', myDeque.toArray()); // Output: [ 'zero', 'first', 'second' ]
console.log('Pop back:', myDeque.popBack()); // Output: second
console.log('Pop front:', myDeque.popFront()); // Output: zero

// Using a Vector (a protected array)
const myVector = new Vector<number>([1, 2, 3]);
myVector.pushBack(4);
myVector.insert(0, 0);
console.log('Vector elements:', myVector.toArray()); // Output: [ 0, 1, 2, 3, 4 ]
console.log('Element at index 2:', myVector.getElementByPos(2)); // Output: 2