@rwitankar/javascript-data-structures 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 1.0.0 - 2026-11-14
+
+- Added Stack, Queue, Deque, linked lists, heaps, PriorityQueue, Graph, Trie, and UnionFind.
+- Added CommonJS and ES Module package entry points.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# JavaScript Data Structures
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Small, dependency-free JavaScript implementations of common data structures. The package exposes CommonJS and ES Module entry points.
+
+## Install
+
+```bash
+npm install @rwitankar/javascript-data-structures
+```
+
+## Usage
+
+CommonJS:
+
+```js
+const { Stack, PriorityQueue } = require('@rwitankar/javascript-data-structures');
+const stack = new Stack();
+stack.push('value');
+console.log(stack.pop());
+```
+
+ES Modules:
+
+```js
+import { Graph, Trie } from '@rwitankar/javascript-data-structures';
+const graph = new Graph();
+graph.addVertex('A').addVertex('B').addEdge('A', 'B');
+console.log(graph.BFS('A'));
+```
+
+## Data structures and APIs
+
+- `Stack`: `push`, `pop`, `peek`, `isEmpty`, `size`, `clear`, `toArray` (LIFO).
+- `Queue`: `enqueue`, `dequeue`, `front`, `rear`, `isEmpty`, `size`, `clear`, `toArray` (FIFO).
+- `Deque`: `addFront`, `addRear`, `removeFront`, `removeRear`, `peekFront`, `peekRear`, `isEmpty`, `size`.
+- `SinglyLinkedList`: `append`, `prepend`, `insertAt`, `removeAt`, `remove`, `find`, `get`, `reverse`, `size`, `isEmpty`, `toArray`.
+- `DoublyLinkedList`: `append`, `prepend`, `insertAt`, `removeAt`, `remove`, `find`, `reverse`, `size`, `toArray`.
+- `MinHeap` / `MaxHeap`: `insert`, `extractMin` / `extractMax`, `peek`, `size`, `isEmpty`, `clear`, `toArray`.
+- `PriorityQueue`: `enqueue(value, priority)`, `dequeue`, `peek`, `size`, `isEmpty`, `clear`. Lower numeric priorities leave first; equal priorities are FIFO.
+- `Graph`: `addVertex`, `addEdge`, `removeVertex`, `removeEdge`, `hasVertex`, `hasEdge`, `getNeighbors`, `BFS`, `DFS`, `isDirected`, `display`. Construct with `new Graph(true)` for directed edges; edges are unweighted.
+- `Trie`: `insert`, `search`, `startsWith`, `delete`, `getWordsWithPrefix`. Words are strings; prefix results are lexicographically ordered.
+- `UnionFind`: `find`, `union`, `connected`, `count`. Construct with a non-negative element count; elements are zero-based.
+
+Empty removal/peek operations throw `Error`. Invalid indexes throw `RangeError`; invalid constructor values, words, or priorities throw `TypeError`/`RangeError` as appropriate. Methods that mutate a structure return the structure for chaining unless documented otherwise. `remove` and `delete` return booleans.
+
+## Complexity
+
+| Structure | Main operations | Space |
+| --- | --- | --- |
+| Stack | push/pop/peek O(1) | O(n) |
+| Queue | enqueue/dequeue/front/rear O(1) amortized | O(n) |
+| Deque | rear operations O(1); front array operations O(n) | O(n) |
+| Singly linked list | append/prepend O(1); indexed operations O(n) | O(n) |
+| Doubly linked list | append/prepend O(1); indexed lookup O(n) | O(n) |
+| Heaps | insert/extract O(log n); peek O(1) | O(n) |
+| Priority queue | enqueue/dequeue O(log n); peek O(1) | O(n) |
+| Graph | edge/vertex lookup O(1) average; BFS/DFS O(V+E) | O(V+E) |
+| Trie | insert/search/prefix O(k), excluding output size | O(total characters) |
+| UnionFind | near O(1) amortized (`α(n)`) | O(n) |
+
+## Compatibility
+
+The package is tested with Node.js `v26.5.0` in this project. Node.js `18+` is declared in `package.json`, but other versions are not verified here.
+
+## Development and publishing
+
+```bash
+npm test
+npm pack --dry-run
+npm publish
+```
+
+Authenticate with an npm account that owns the `rwitankar` scope, then review the package contents before publishing. Publishing is intentionally not automated.
+
+## Contributing
+
+Keep each structure independent, add Node built-in tests for behavior and edge cases, and update this README when a public API changes.

package/index.js

@@ -0,0 +1,6 @@
+module.exports = {
+  Stack: require('./src/linear/Stack'), Queue: require('./src/linear/Queue'), Deque: require('./src/linear/Deque'),
+  SinglyLinkedList: require('./src/linked-list/SinglyLinkedList'), DoublyLinkedList: require('./src/linked-list/DoublyLinkedList'),
+  MinHeap: require('./src/heaps/MinHeap'), MaxHeap: require('./src/heaps/MaxHeap'), PriorityQueue: require('./src/priority-queue/PriorityQueue'),
+  Graph: require('./src/graphs/Graph'), Trie: require('./src/trees/Trie'), UnionFind: require('./src/disjoint-set/UnionFind')
+};

package/index.mjs

@@ -0,0 +1,3 @@
+import api from './index.js';
+export const { Stack, Queue, Deque, SinglyLinkedList, DoublyLinkedList, MinHeap, MaxHeap, PriorityQueue, Graph, Trie, UnionFind } = api;
+export default api;

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@rwitankar/javascript-data-structures",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Common JavaScript data structures and algorithms.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rwitankar-byte/JS_dataStructure_npm.git"
+  },
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "exports": {
+    ".": {
+      "require": "./index.js",
+      "import": "./index.mjs"
+    }
+  },
+  "files": ["index.js", "index.mjs", "src", "README.md", "LICENSE", "CHANGELOG.md"],
+  "scripts": {"test": "node --test"},
+  "engines": {"node": ">=18"},
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/disjoint-set/UnionFind.js

@@ -0,0 +1,10 @@
+/** Disjoint-set structure with path compression and union by rank. */
+class UnionFind {
+  constructor(size) { if (!Number.isInteger(size) || size < 0) throw new RangeError('Size must be a non-negative integer'); this.parent = Array.from({ length: size }, (_, i) => i); this.rank = Array(size).fill(0); this.components = size; }
+  _check(value) { if (!Number.isInteger(value) || value < 0 || value >= this.parent.length) throw new RangeError('Element out of bounds'); }
+  find(value) { this._check(value); if (this.parent[value] !== value) this.parent[value] = this.find(this.parent[value]); return this.parent[value]; }
+  union(a, b) { const rootA = this.find(a), rootB = this.find(b); if (rootA === rootB) return false; if (this.rank[rootA] < this.rank[rootB]) this.parent[rootA] = rootB; else { this.parent[rootB] = rootA; if (this.rank[rootA] === this.rank[rootB]) this.rank[rootA]++; } this.components--; return true; }
+  connected(a, b) { return this.find(a) === this.find(b); }
+  count() { return this.components; }
+}
+module.exports = UnionFind;

package/src/graphs/Graph.js

@@ -0,0 +1,16 @@
+/** Directed or undirected unweighted graph. */
+class Graph {
+  constructor(directed = false) { if (typeof directed !== 'boolean') throw new TypeError('Directed must be a boolean'); this.directed = directed; this.adjacency = new Map(); }
+  addVertex(vertex) { if (!this.adjacency.has(vertex)) this.adjacency.set(vertex, new Set()); return this; }
+  addEdge(from, to) { if (!this.adjacency.has(from) || !this.adjacency.has(to)) throw new Error('Both vertices must exist'); this.adjacency.get(from).add(to); if (!this.directed) this.adjacency.get(to).add(from); return this; }
+  removeVertex(vertex) { if (!this.adjacency.delete(vertex)) return false; for (const neighbors of this.adjacency.values()) neighbors.delete(vertex); return true; }
+  removeEdge(from, to) { const removed = this.adjacency.get(from)?.delete(to) ?? false; if (!this.directed) this.adjacency.get(to)?.delete(from); return removed; }
+  hasVertex(vertex) { return this.adjacency.has(vertex); }
+  hasEdge(from, to) { return this.adjacency.get(from)?.has(to) ?? false; }
+  getNeighbors(vertex) { if (!this.adjacency.has(vertex)) throw new Error('Vertex does not exist'); return [...this.adjacency.get(vertex)]; }
+  BFS(start) { if (!this.adjacency.has(start)) throw new Error('Vertex does not exist'); const seen = new Set([start]), result = [], queue = [start]; for (let i = 0; i < queue.length; i++) { const v = queue[i]; result.push(v); for (const n of this.adjacency.get(v)) if (!seen.has(n)) { seen.add(n); queue.push(n); } } return result; }
+  DFS(start) { if (!this.adjacency.has(start)) throw new Error('Vertex does not exist'); const result = [], seen = new Set(); const visit = v => { seen.add(v); result.push(v); for (const n of this.adjacency.get(v)) if (!seen.has(n)) visit(n); }; visit(start); return result; }
+  isDirected() { return this.directed; }
+  display() { return Object.fromEntries([...this.adjacency].map(([v, n]) => [v, [...n]])); }
+}
+module.exports = Graph;

package/src/heaps/MaxHeap.js

@@ -0,0 +1,8 @@
+/** Binary max-heap for values comparable with `>` and `>=`. */
+class MaxHeap extends require('./MinHeap') {
+  _up(i) { while (i) { const p = (i - 1) >> 1; if (this.items[p] >= this.items[i]) break; [this.items[p], this.items[i]] = [this.items[i], this.items[p]]; i = p; } }
+  _down(i) { while (true) { let c = i * 2 + 1; if (c >= this.items.length) return; if (c + 1 < this.items.length && this.items[c + 1] > this.items[c]) c++; if (this.items[i] >= this.items[c]) return; [this.items[i], this.items[c]] = [this.items[c], this.items[i]]; i = c; } }
+  extractMax() { return super.extractMin(); }
+  peek() { return super.peek(); }
+}
+module.exports = MaxHeap;

package/src/heaps/MinHeap.js

@@ -0,0 +1,14 @@
+/** Binary min-heap for values comparable with `<` and `<=`. */
+class MinHeap {
+  constructor() { this.items = []; }
+  insert(value) { this.items.push(value); this._up(this.items.length - 1); return this; }
+  _up(i) { while (i) { const p = (i - 1) >> 1; if (this.items[p] <= this.items[i]) break; [this.items[p], this.items[i]] = [this.items[i], this.items[p]]; i = p; } }
+  _down(i) { while (true) { let c = i * 2 + 1; if (c >= this.items.length) return; if (c + 1 < this.items.length && this.items[c + 1] < this.items[c]) c++; if (this.items[i] <= this.items[c]) return; [this.items[i], this.items[c]] = [this.items[c], this.items[i]]; i = c; } }
+  extractMin() { if (this.isEmpty()) throw new Error('Heap is empty'); const value = this.items[0], last = this.items.pop(); if (this.items.length) { this.items[0] = last; this._down(0); } return value; }
+  peek() { if (this.isEmpty()) throw new Error('Heap is empty'); return this.items[0]; }
+  size() { return this.items.length; }
+  isEmpty() { return !this.items.length; }
+  clear() { this.items.length = 0; }
+  toArray() { return [...this.items]; }
+}
+module.exports = MinHeap;

package/src/linear/Deque.js

@@ -0,0 +1,13 @@
+/** Double-ended collection. */
+class Deque {
+  constructor() { this.items = []; }
+  addFront(value) { this.items.unshift(value); return this; }
+  addRear(value) { this.items.push(value); return this; }
+  removeFront() { if (this.isEmpty()) throw new Error('Deque is empty'); return this.items.shift(); }
+  removeRear() { if (this.isEmpty()) throw new Error('Deque is empty'); return this.items.pop(); }
+  peekFront() { if (this.isEmpty()) throw new Error('Deque is empty'); return this.items[0]; }
+  peekRear() { if (this.isEmpty()) throw new Error('Deque is empty'); return this.items.at(-1); }
+  isEmpty() { return this.items.length === 0; }
+  size() { return this.items.length; }
+}
+module.exports = Deque;

package/src/linear/Queue.js

@@ -0,0 +1,13 @@
+/** FIFO collection with amortized constant-time dequeue. */
+class Queue {
+  constructor() { this.items = []; this.head = 0; }
+  enqueue(value) { this.items.push(value); return this; }
+  dequeue() { if (this.isEmpty()) throw new Error('Queue is empty'); const value = this.items[this.head++]; if (this.head > 64 && this.head * 2 >= this.items.length) { this.items = this.items.slice(this.head); this.head = 0; } return value; }
+  front() { if (this.isEmpty()) throw new Error('Queue is empty'); return this.items[this.head]; }
+  rear() { if (this.isEmpty()) throw new Error('Queue is empty'); return this.items.at(-1); }
+  isEmpty() { return this.head >= this.items.length; }
+  size() { return this.items.length - this.head; }
+  clear() { this.items = []; this.head = 0; }
+  toArray() { return this.items.slice(this.head); }
+}
+module.exports = Queue;

package/src/linear/Stack.js

@@ -0,0 +1,12 @@
+/** LIFO collection with constant-time top operations. */
+class Stack {
+  constructor() { this.items = []; }
+  push(value) { this.items.push(value); return this; }
+  pop() { if (!this.items.length) throw new Error('Stack is empty'); return this.items.pop(); }
+  peek() { if (!this.items.length) throw new Error('Stack is empty'); return this.items.at(-1); }
+  isEmpty() { return this.items.length === 0; }
+  size() { return this.items.length; }
+  clear() { this.items.length = 0; }
+  toArray() { return [...this.items]; }
+}
+module.exports = Stack;

package/src/linked-list/DoublyLinkedList.js

@@ -0,0 +1,16 @@
+/** Mutable doubly linked list with zero-based indexing. */
+class DoublyLinkedList {
+  constructor() { this.head = null; this.tail = null; this.length = 0; }
+  append(value) { const node = { value, prev: this.tail, next: null }; if (this.tail) this.tail.next = node; else this.head = node; this.tail = node; this.length++; return this; }
+  prepend(value) { const node = { value, prev: null, next: this.head }; if (this.head) this.head.prev = node; else this.tail = node; this.head = node; this.length++; return this; }
+  _index(index, allowEnd = false) { if (!Number.isInteger(index) || index < 0 || index >= this.length + (allowEnd ? 1 : 0)) throw new RangeError('Index out of bounds'); }
+  insertAt(index, value) { this._index(index, true); if (index === 0) return this.prepend(value); if (index === this.length) return this.append(value); const next = this._node(index), node = { value, prev: next.prev, next }; next.prev.next = node; next.prev = node; this.length++; return this; }
+  _node(index) { let n; if (index < this.length / 2) { n = this.head; while (index--) n = n.next; } else { n = this.tail; for (let i = this.length - 1; i > index; i--) n = n.prev; } return n; }
+  removeAt(index) { this._index(index); const n = this._node(index); if (n.prev) n.prev.next = n.next; else this.head = n.next; if (n.next) n.next.prev = n.prev; else this.tail = n.prev; this.length--; return n.value; }
+  remove(value) { const i = this.find(value); if (i === -1) return false; this.removeAt(i); return true; }
+  find(value) { let n = this.head, i = 0; while (n) { if (Object.is(n.value, value)) return i; n = n.next; i++; } return -1; }
+  reverse() { let n = this.head; while (n) { [n.next, n.prev] = [n.prev, n.next]; n = n.prev; } [this.head, this.tail] = [this.tail, this.head]; return this; }
+  size() { return this.length; }
+  toArray() { const result = []; for (let n = this.head; n; n = n.next) result.push(n.value); return result; }
+}
+module.exports = DoublyLinkedList;

package/src/linked-list/SinglyLinkedList.js

@@ -0,0 +1,17 @@
+/** Mutable singly linked list with zero-based indexing. */
+class SinglyLinkedList {
+  constructor() { this.head = null; this.tail = null; this.length = 0; }
+  append(value) { const node = { value, next: null }; if (!this.head) this.head = node; else this.tail.next = node; this.tail = node; this.length++; return this; }
+  prepend(value) { const node = { value, next: this.head }; this.head = node; if (!this.tail) this.tail = node; this.length++; return this; }
+  _index(index) { if (!Number.isInteger(index) || index < 0 || index >= this.length) throw new RangeError('Index out of bounds'); }
+  insertAt(index, value) { if (!Number.isInteger(index) || index < 0 || index > this.length) throw new RangeError('Index out of bounds'); if (index === 0) return this.prepend(value); if (index === this.length) return this.append(value); let prev = this.head; for (let i = 1; i < index; i++) prev = prev.next; prev.next = { value, next: prev.next }; this.length++; return this; }
+  removeAt(index) { this._index(index); let removed; if (index === 0) { removed = this.head; this.head = this.head.next; } else { let prev = this.head; for (let i = 1; i < index; i++) prev = prev.next; removed = prev.next; prev.next = removed.next; if (removed === this.tail) this.tail = prev; } this.length--; if (!this.length) this.tail = null; return removed.value; }
+  remove(value) { const i = this.find(value); if (i === -1) return false; this.removeAt(i); return true; }
+  find(value) { let node = this.head, i = 0; while (node) { if (Object.is(node.value, value)) return i; node = node.next; i++; } return -1; }
+  get(index) { this._index(index); let node = this.head; for (let i = 0; i < index; i++) node = node.next; return node.value; }
+  reverse() { let previous = null, node = this.head; this.tail = this.head; while (node) { const next = node.next; node.next = previous; previous = node; node = next; } this.head = previous; return this; }
+  size() { return this.length; }
+  isEmpty() { return this.length === 0; }
+  toArray() { const result = []; for (let n = this.head; n; n = n.next) result.push(n.value); return result; }
+}
+module.exports = SinglyLinkedList;

package/src/priority-queue/PriorityQueue.js

@@ -0,0 +1,14 @@
+/** Stable min-priority queue; lower numeric priorities dequeue first. */
+class PriorityQueue {
+  constructor() { this.items = []; this.sequence = 0; }
+  enqueue(value, priority) { if (typeof priority !== 'number' || Number.isNaN(priority)) throw new TypeError('Priority must be a number'); this.items.push({ value, priority, sequence: this.sequence++ }); this._up(this.items.length - 1); return this; }
+  _before(a, b) { return a.priority < b.priority || (a.priority === b.priority && a.sequence < b.sequence); }
+  _up(i) { while (i) { const p = (i - 1) >> 1; if (this._before(this.items[p], this.items[i])) break; [this.items[p], this.items[i]] = [this.items[i], this.items[p]]; i = p; } }
+  _down(i) { while (true) { let c = i * 2 + 1; if (c >= this.items.length) return; if (c + 1 < this.items.length && this._before(this.items[c + 1], this.items[c])) c++; if (this._before(this.items[i], this.items[c])) return; [this.items[i], this.items[c]] = [this.items[c], this.items[i]]; i = c; } }
+  dequeue() { if (this.isEmpty()) throw new Error('Priority queue is empty'); const value = this.items[0].value, last = this.items.pop(); if (this.items.length) { this.items[0] = last; this._down(0); } return value; }
+  peek() { if (this.isEmpty()) throw new Error('Priority queue is empty'); return this.items[0].value; }
+  size() { return this.items.length; }
+  isEmpty() { return !this.items.length; }
+  clear() { this.items.length = 0; }
+}
+module.exports = PriorityQueue;

package/src/trees/Trie.js

@@ -0,0 +1,13 @@
+/** Prefix tree for string values. */
+class Trie {
+  constructor() { this.root = { children: new Map(), word: false }; }
+  _validate(word) { if (typeof word !== 'string') throw new TypeError('Word must be a string'); }
+  insert(word) { this._validate(word); let node = this.root; for (const char of word) { if (!node.children.has(char)) node.children.set(char, { children: new Map(), word: false }); node = node.children.get(char); } node.word = true; return this; }
+  _node(prefix) { let node = this.root; for (const char of prefix) { node = node.children.get(char); if (!node) return null; } return node; }
+  search(word) { this._validate(word); return !!this._node(word)?.word; }
+  startsWith(prefix) { this._validate(prefix); return !!this._node(prefix); }
+  delete(word) { this._validate(word); const path = [], node = this._nodeWithPath(word, path); if (!node?.word) return false; node.word = false; for (let i = path.length - 1; i >= 0; i--) { const [parent, char, child] = path[i]; if (child.word || child.children.size) break; parent.children.delete(char); } return true; }
+  _nodeWithPath(word, path) { let node = this.root; for (const char of word) { const child = node.children.get(char); if (!child) return null; path.push([node, char, child]); node = child; } return node; }
+  getWordsWithPrefix(prefix) { this._validate(prefix); const node = this._node(prefix); if (!node) return []; const words = []; const visit = (n, suffix) => { if (n.word) words.push(prefix + suffix); for (const char of [...n.children.keys()].sort()) visit(n.children.get(char), suffix + char); }; visit(node, ''); return words; }
+}
+module.exports = Trie;