Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nickzuber/needle

:pushpin::books: An extensive standalone data structure library for JavaScript.
https://github.com/nickzuber/needle

binary-trees bitarray data-structures hashmap heap javascript k-ary-tree library linked-list needle node queue rabin-karp rolling-hash-functions stack

Last synced: about 2 months ago
JSON representation

:pushpin::books: An extensive standalone data structure library for JavaScript.

Awesome Lists containing this project

README 

        
# [Needle](https://github.com/nickzuber/needle) 



  




 



Needle is a standalone extensive data structure library in JavaScript.



_Install as an [npm package](https://www.npmjs.com/package/node-needle) or download the [minified file of the latest version](https://github.com/nickzuber/needle/blob/master/bin/needle.min.js)._



## Installation 



You can install Needle as a [node package with npm](https://www.npmjs.com/package/node-needle), and it's as easy as:

```

$ npm install --save node-needle

```



If you prefer to use Needle on the client side, just download the [minified file of the latest version](https://github.com/nickzuber/needle/blob/master/bin/needle.min.js) and include it in your webpage:

```html



```



## Usage



When you have Needle installed, you can use it on the server in Node like so:

```javascript

const Needle = require('node-needle');



// Example: Create a new instance of a hashmap

var map = Needle.Hashmap();

```



or you can just use it on the client side like so:

```javascript

// Needle gets pushed onto the global scope under the alias "Needle"

var bst = new Needle.BinarySearchTree();

```



## API Reference



Needle has a variety of different data structures at its disposal. Here is a reference to all of the currently available data structures that Needle supports. Some data structures have not been added yet and they will appear unavailable.



*If you feel that there should be additional data structures added to this library, [send me a message and let me know what you had in mind.](mailto:[email protected])*



**Note:** In the API, `*` refers to any type. This is commonly used when specifying the type of data; since all types of data are supported when inserting custom data into a data structure.



---



#### Arrays

 - [Bit Array](#bitarray)

 - Bitmap

 - Hashed Array Tree

 - [Sorted Array](#sortedarray)



#### Lists

 - [Doubly Linked List](#doublylinkedlist)

 - [Singly Linked List](#singlylinkedlist)

 - [Queue](#queue)

 - [Stack](#stack)



#### Heaps

 - [Binary Heap](#binaryheap)

 - Binomial Heap

 - Soft Heap



#### General Trees

 - Trie

 - Radix Tree

 - B Trie



#### Binary Trees

 - [Binary Search Tree](#bst)

 - AVL Tree

 - B Tree

 - B+ Tree

 - Red-Black Tree



#### Multiway Trees

 - Ternary Tree

 - [K-ary Tree](#karytree)

 - And-Or Tree



#### Metric Trees

 - VP Tree

 - BK Tree

 - M Tree

 - Cover Tree



#### Hashes

 - [Hashmap](#hashmap)

 - Concurrent Hash Trie

 - [Rolling Hash](#rollinghash)



#### Graphs

 - Adjacency Matrix

 - Directed Graph

 - Multigraph



---



### Needle.BinarySearchTree()

**root** - *Node* - The root node of the binary tree.


**compare** - *function* - Compares two elements to each other to determine the ordering of the heap.



**Note:** The default `compare` function is defined as

```javascript

function defaultCompare(a, b){

  return (a < b);

}

```

 

 - **(constructor)**([< *function* >compare]) - *object* - Creates a Binary Search Tree and if a function is passed in, it overrides the default compare function with the function defined by `compare`.

 - **hasRight**(< *Node* >node) - *boolean* - Returns true if the given `Node` has a right component.

 - **hasLeft**(< *Node* >node) - *boolean* - Returns true if the given `Node` has a left component.

 - **isLeaf**(< *Node* >node) - *boolean* - Returns true if the given `Node` is a leaf.

 - **emptySubtree**(< *Node* >node) - *void* - Empties the subtree of the given `Node`.

 - **emptyTree**() - *void* - Empties the entire tree.

 - **heightSubtree**(< *Node* >node) - *number* - Returns the height of the subtree derived from `Node`.

 - **numNodesSubtree**(< *Node* >node) - *number* - Returns the number of nodes of the subtree derived from `Node`.

 - **numLeavesSubtree**(< *Node* >node) - *number* - Returns the number of leaves of the subtree derived from `Node`.

 - **insert**(< * >data [, < *Node* >node]) - *void* - Inserts a node into the binary search tree given by `data`. The `Node` argument will determine which subtree to attempt to insert the node at. Inserting at the root subtree is selected by default if this parameter is left blank (recommended).

 - **search**(< * >data [, < *Node* >node]) - *Node || false* - Searched for the node given by `data` in the binary search tree. The `Node` argument will determine which subtree to attempt to search for the node. Searching at the root subtree is selected by default if this parameter is left blank (recommended).



### Needle.BinaryHeap()

**heap** - *Array* - The array based heap acting as a binary heap.


**compare** - *function* - Compares two elements to each other to determine the ordering of the heap.



**Note:** The default `compare` function is defined as

```javascript

function defaultCompare(a, b){

  return (a < b);

}

```

 

 - **(constructor)**([< *function* >compare]) - *object* - Creates a Binary Heap and if a function is passed in, it overrides the default compare function with the function defined by `compare`.

 - **peek**() - *element* - Returns the root or top element of the heap.

 - **size**() - *number* - Returns the amount of elements stored in the heap.

 - **insert**(< * >data) - *void* - Inserts the element given by `data` into the heap and adjusts the heap accordingly.

 - **delete**() - *void* - Removes the root or top element from the heap and adjusts the heap accordingly.

 - **heapify**(< *array* >arr) - *void* - Converts the input array into a legal binary heap.



### Needle.BitArray()

**data** - *Array* - The array of bit sequences.


 

 - **(constructor)**([< *number* >size = 0]) - *object* - Creates a Bit Array and allocates memory for the `size` if argument is given.

 - **get**(< *number* >index) - *number* - Returns the bit in the BitArray at location `index`.

 - **set**(< *number* >index, < *boolean* >value) - *void* - 

 - **size**(< *number* >size) - *void* - 

 - **resize**() - *void* - Adjusts the BitArray size to the given argument `size`.

 - **complement**() - *BitArray* - Resolves the complement of the calling BitArray.

 - **union**(< *BitArray* >bitarray) - *BitArray* - Resolves the union between the calling BitArray and the argument `bitarray`.

 - **intersection**(< *BitArray* >bitarray) - *BitArray* - Resolves the intersection between the calling BitArray and the argument `bitarray`.

 - **difference**(< *BitArray* >bitarray) - *BitArray* - Resolves the difference between the calling BitArray and the argument `bitarray`.



### Needle.DoublyLinkedList()

**head** - *Node* - The first node in the linked list.


**tail** - *Node* - The last node in the linked list.


**size** - *number* - The number of nodes in the linked list.



 - **(constructor)**([< * >data]) - *object* - Creates a Doubly Linked List and inserts a node at the head of the newly created list if `data` is given.

 - **insertFront**(< * >data) - *void* - Create a node from `data` and inserts at the front of the list.

 - **insertNth**(< *number* >index, < * >data) - *boolean* - Create a node from `data` and insert in the location of the linked list specified by `index`.

 - **insertAfter**(< * >targetData, < * >data) - *boolean* - Create a node from `data` and insert after the node which has the data specified by `targetData` and returns `true` if the element was successfully added to the linked list.

 - **insertBack**(< * >data) - *void* - Create a node from `data` and inserts at the back of the list.

 - **remove**(< * >data) - *boolean* - Removes the element specified by `data` and returns `true` if the element was successfully found and removed from the linked list.

 - **removeNth**(< *number* >index) - *void* - Removes the element in the location of the linked list specified by `index`.

 - **find**(< * >data) - *Node || false* - Finds the element specified by `data` and returns that `Node` if the element was successfully found but returns `false` if the node was not found.

 - **findNth**(< *number* >index) - *Node* - Finds the element in the location of the linked list specified by `index` and returns that `Node`.



### Needle.Hashmap()

**state** - *number* - Holds the current hash of the internal window.


 

 - **(constructor)**() - *object* - Creates and instatiates a Hashmap object.

 - **put**(< * >key, < * >value) - *void* - Inserts an entry into the hashmap, which maps the given `key` to its respective `value`.

 - **get**(< * >key) - *value* - Returns the value that is paired with the given `key`.

 - **delete**(< * >key) - *boolean* - Deletes the entry that is associated with the given `key`, returns `true` if deletion was successful and `false` if the entry was not found.

 - **iterator**() - *key* - Resets the internal iterator `Node` to the first entry and returns the unhashed key.

 - **next**() - *key* - Iterates to the next `Node` and returns an the unhashed key.

 - **size**() - *number* - Returns the amount of unique entries within the hashmap.



### Needle.RollingHash()

**state** - *number* - The internal hash value of the current window.



 - **(constructor)**(< *number* >base) - *object* - Creates and instatiates a rolling hash object and an argument is passed in which assigns the `base` of the rolling hash.

 - **set**(< *string || Array* >arg) - *void* - Sets the internal window of the rolling hash given `arg` in the relative base.

 - **slide**(< *string || number* >old, < *string || number* >new) - *number* - Shifts the internal window a single rotation by removing the `old` segment and appending on the `new` segment, then returns the newly updates `state` of the internal window.

 - **skip**(< *string || number* >old) - *void* - Disjoins the `old` segment from the internal window.

 - **append**(< *string || number* >new) - *void* - Appends a `new` segment onto the internal window.

 - **hash**(< *number || string || Array*arg>) - *number* - Takes in either a `string`, `number` (assumed in the relative `base`), or `Array` of elements in the relative base, and returns the hash of the argument.



### Needle.SinglyLinkedList()

**head** - *Node* - The first node in the linked list.


**size** - *number* - The number of nodes in the linked list.



 - **(constructor)**([< * >data]) - *object* - Creates a Singly Linked List and inserts a node at the head of the newly created list if `data` is given.

 - **insertFront**(< * >data) - *void* - Create a node from `data` and inserts at the front of the list.

 - **insertNth**(< *number* >index, < * >data) - *boolean* - Create a node from `data` and insert in the location of the linked list specified by `index`.

 - **insertAfter**(< * >targetData, < * >data) - *boolean* - Create a node from `data` and insert after the node which has the data specified by `targetData` and returns `true` if the element was successfully added to the linked list.

 - **insertBack**(< * >data) - *void* - Create a node from `data` and inserts at the back of the list.

 - **remove**(< * >data) - *boolean* - Removes the element specified by `data` and returns `true` if the element was successfully found and removed from the linked list.

 - **removeNth**(< *number* >index) - *void* - Removes the element in the location of the linked list specified by `index`.

 - **find**(< * >data) - *Node || false* - Finds the element specified by `data` and returns that `Node` if the element was successfully found but returns `false` if the node was not found.

 - **findNth**(< *number* >index) - *Node* - Finds the element in the location of the linked list specified by `index` and returns that `Node`.



### Needle.Stack()

**top** - *Node* - The top node in the stack.


**size** - *number* - The number of nodes in the stack.


 

 - **(constructor)**([< * >data]) - *object* - Creates a Stack and if data is passed given, the top element of the queue, defined by `data`, is created and inserted.

 - **peek**() - *Node* - Returns the top `Node` of the stack.

 - **push**(< * >data) - *void* - Adds and element, defined by `data`, to the top of the stack.

 - **pop**() - *Node* - Removes the top element of the stack and returns the `Node` that was previously the top, and just deleted.



### Needle.Queue()

**front** - *Node* - The first node in the queue.


**back** - *Node* - The last node in the queue.


**size** - *number* - The number of nodes in the queue.


 

 - **(constructor)**([< * >data]) - *object* - Creates a Queue and if data is passed given, the first element of the queue, defined by `data`, is created and inserted.

 - **enqueue**(< * >data) - *void* - Adds and element, defined by `data`, to the queue.

 - **dequeue**() - *void* - Removes the first element of the queue.



## Examples



Here are an assortment of examples using various data structures provided by Needle. If you wish there to be examples of a data structure in particular, [feel free to let me know what you have in mind](mailto:[email protected]).



```javascript

// Priority Queue implementation using a binary heap



const Needle = require('node-needle');



var Level = function(key, value){

  this.key = key;

  this.value = value;

}



var priorityQueue = new Needle.BinaryHeap(function(a, b){

  return a.key < b.key;

});



priorityQueue.insert(new Level(3, "Level 3"));

priorityQueue.insert(new Level(1, "Level 1"));

priorityQueue.insert(new Level(2, "Level 2"));



priorityQueue.peek(); // => {1, "Level 1"}

priorityQueue.size(); // => 3



priorityQueue.delete();



priorityQueue.peek(); // => {2, "Level 2"}

priorityQueue.size(); // => 2



```



```javascript

// Iterating through a Hashmap



const Needle = require('node-needle');



var map = new Needle.Hashmap();



map.put(1, "Level 1");

map.put("2", "Level 2");

map.put({key: "three"}, "Level 3");



// Insertion order is kept, despite key value

for(var it = map.iterator(); it !== null; it = map.next()){

  console.log(it); // 1 -> "2" -> {key: "three"}

  console.log(map.get(it)); // "Level 1" -> "Level 2" -> "Level 3"

}



```



## License

[MIT](https://opensource.org/licenses/MIT)



Copyright (c) 2015 Nick Zuber