{"id":13510320,"url":"https://github.com/nickzuber/needle","last_synced_at":"2025-05-07T21:44:52.562Z","repository":{"id":67102501,"uuid":"47858837","full_name":"nickzuber/needle","owner":"nickzuber","description":":pushpin::books: An extensive standalone data structure library for JavaScript.","archived":false,"fork":false,"pushed_at":"2017-07-23T04:53:56.000Z","size":573,"stargazers_count":25,"open_issues_count":6,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-09-21T13:24:13.725Z","etag":null,"topics":["binary-trees","bitarray","data-structures","hashmap","heap","javascript","k-ary-tree","library","linked-list","needle","node","queue","rabin-karp","rolling-hash-functions","stack"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickzuber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-12-12T01:05:12.000Z","updated_at":"2021-01-09T03:48:03.000Z","dependencies_parsed_at":"2024-01-13T19:26:16.083Z","dependency_job_id":"bfc1686e-dca0-4860-9d2e-34a44318662f","html_url":"https://github.com/nickzuber/needle","commit_stats":{"total_commits":200,"total_committers":2,"mean_commits":100.0,"dds":"0.30000000000000004","last_synced_commit":"9565b3c193b93d67ffed39d430eba395a7bb5531"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzuber%2Fneedle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzuber%2Fneedle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzuber%2Fneedle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzuber%2Fneedle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickzuber","download_url":"https://codeload.github.com/nickzuber/needle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252954407,"owners_count":21830902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-trees","bitarray","data-structures","hashmap","heap","javascript","k-ary-tree","library","linked-list","needle","node","queue","rabin-karp","rolling-hash-functions","stack"],"created_at":"2024-08-01T02:01:33.670Z","updated_at":"2025-05-07T21:44:52.535Z","avatar_url":"https://github.com/nickzuber.png","language":"JavaScript","readme":"# [Needle](https://github.com/nickzuber/needle) \n\n\u003cimg src=\"https://travis-ci.org/nickzuber/needle.svg?branch=master\" /\u003e \u003cimg src=\"https://img.shields.io/badge/license-mit-blue.svg?style=flat\" /\u003e \u003cimg src=\"https://badge.fury.io/js/node-needle.svg\" /\u003e\n\u003cbr /\u003e\n\u003cimg src=\"https://david-dm.org/nickzuber/Needle/dev-status.svg\" /\u003e \u003cimg src=\"https://david-dm.org/nickzuber/Needle.svg\" /\u003e\n\nNeedle is a standalone extensive data structure library in JavaScript.\n\n_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)._\n\n\n## Installation \n\n\nYou can install Needle as a [node package with npm](https://www.npmjs.com/package/node-needle), and it's as easy as:\n```\n$ npm install --save node-needle\n```\n\nIf 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:\n```html\n\u003c!-- The complete Needle library --\u003e\n\u003cscript src=\"path/to/needle.min.js\"\u003e\u003c/script\u003e\n```\n\n## Usage\n\nWhen you have Needle installed, you can use it on the server in Node like so:\n```javascript\nconst Needle = require('node-needle');\n\n// Example: Create a new instance of a hashmap\nvar map = Needle.Hashmap();\n```\n\nor you can just use it on the client side like so:\n```javascript\n// Needle gets pushed onto the global scope under the alias \"Needle\"\nvar bst = new Needle.BinarySearchTree();\n```\n\n\n## API Reference\n\nNeedle 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.\n\n*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:zuber.nicholas@gmail.com)*\n\n**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.\n\n---\n\n#### Arrays\n - [Bit Array](#bitarray)\n - Bitmap\n - Hashed Array Tree\n - [Sorted Array](#sortedarray)\n\n#### Lists\n - [Doubly Linked List](#doublylinkedlist)\n - [Singly Linked List](#singlylinkedlist)\n - [Queue](#queue)\n - [Stack](#stack)\n\n#### Heaps\n - [Binary Heap](#binaryheap)\n - Binomial Heap\n - Soft Heap\n\n#### General Trees\n - Trie\n - Radix Tree\n - B Trie\n\n#### Binary Trees\n - [Binary Search Tree](#bst)\n - AVL Tree\n - B Tree\n - B+ Tree\n - Red-Black Tree\n\n#### Multiway Trees\n - Ternary Tree\n - [K-ary Tree](#karytree)\n - And-Or Tree\n\n#### Metric Trees\n - VP Tree\n - BK Tree\n - M Tree\n - Cover Tree\n\n#### Hashes\n - [Hashmap](#hashmap)\n - Concurrent Hash Trie\n - [Rolling Hash](#rollinghash)\n\n#### Graphs\n - Adjacency Matrix\n - Directed Graph\n - Multigraph\n\n---\n\n### \u003ca href=\"#bst\" name=\"bst\"\u003eNeedle.BinarySearchTree()\u003c/a\u003e\n**root** - *Node* - The root node of the binary tree.\u003cbr /\u003e\n**compare** - *function* - Compares two elements to each other to determine the ordering of the heap.\u003cbr /\u003e\n\n**Note:** The default `compare` function is defined as\n```javascript\nfunction defaultCompare(a, b){\n  return (a \u003c b);\n}\n```\n \n - **(constructor)**([\u003c *function* \u003ecompare]) - *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`.\n - **hasRight**(\u003c *Node* \u003enode) - *boolean* - Returns true if the given `Node` has a right component.\n - **hasLeft**(\u003c *Node* \u003enode) - *boolean* - Returns true if the given `Node` has a left component.\n - **isLeaf**(\u003c *Node* \u003enode) - *boolean* - Returns true if the given `Node` is a leaf.\n - **emptySubtree**(\u003c *Node* \u003enode) - *void* - Empties the subtree of the given `Node`.\n - **emptyTree**() - *void* - Empties the entire tree.\n - **heightSubtree**(\u003c *Node* \u003enode) - *number* - Returns the height of the subtree derived from `Node`.\n - **numNodesSubtree**(\u003c *Node* \u003enode) - *number* - Returns the number of nodes of the subtree derived from `Node`.\n - **numLeavesSubtree**(\u003c *Node* \u003enode) - *number* - Returns the number of leaves of the subtree derived from `Node`.\n - **insert**(\u003c * \u003edata [, \u003c *Node* \u003enode]) - *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).\n - **search**(\u003c * \u003edata [, \u003c *Node* \u003enode]) - *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).\n\n### \u003ca href=\"#binaryheap\" name=\"binaryheap\"\u003eNeedle.BinaryHeap()\u003c/a\u003e\n**heap** - *Array* - The array based heap acting as a binary heap.\u003cbr /\u003e\n**compare** - *function* - Compares two elements to each other to determine the ordering of the heap.\u003cbr /\u003e\n\n**Note:** The default `compare` function is defined as\n```javascript\nfunction defaultCompare(a, b){\n  return (a \u003c b);\n}\n```\n \n - **(constructor)**([\u003c *function* \u003ecompare]) - *object* - Creates a Binary Heap and if a function is passed in, it overrides the default compare function with the function defined by `compare`.\n - **peek**() - *element* - Returns the root or top element of the heap.\n - **size**() - *number* - Returns the amount of elements stored in the heap.\n - **insert**(\u003c * \u003edata) - *void* - Inserts the element given by `data` into the heap and adjusts the heap accordingly.\n - **delete**() - *void* - Removes the root or top element from the heap and adjusts the heap accordingly.\n - **heapify**(\u003c *array* \u003earr) - *void* - Converts the input array into a legal binary heap.\n\n### \u003ca href=\"#bitarray\" name=\"bitarray\"\u003eNeedle.BitArray()\u003c/a\u003e\n**data** - *Array* - The array of bit sequences.\u003cbr /\u003e\n \n - **(constructor)**([\u003c *number* \u003esize = 0]) - *object* - Creates a Bit Array and allocates memory for the `size` if argument is given.\n - **get**(\u003c *number* \u003eindex) - *number* - Returns the bit in the BitArray at location `index`.\n - **set**(\u003c *number* \u003eindex, \u003c *boolean* \u003evalue) - *void* - \n - **size**(\u003c *number* \u003esize) - *void* - \n - **resize**() - *void* - Adjusts the BitArray size to the given argument `size`.\n - **complement**() - *BitArray* - Resolves the complement of the calling BitArray.\n - **union**(\u003c *BitArray* \u003ebitarray) - *BitArray* - Resolves the union between the calling BitArray and the argument `bitarray`.\n - **intersection**(\u003c *BitArray* \u003ebitarray) - *BitArray* - Resolves the intersection between the calling BitArray and the argument `bitarray`.\n - **difference**(\u003c *BitArray* \u003ebitarray) - *BitArray* - Resolves the difference between the calling BitArray and the argument `bitarray`.\n\n### \u003ca href=\"#doublylinkedlist\" name=\"doublylinkedlist\"\u003eNeedle.DoublyLinkedList()\u003c/a\u003e\n**head** - *Node* - The first node in the linked list.\u003cbr /\u003e\n**tail** - *Node* - The last node in the linked list.\u003cbr /\u003e\n**size** - *number* - The number of nodes in the linked list.\u003cbr /\u003e\n\n - **(constructor)**([\u003c * \u003edata]) - *object* - Creates a Doubly Linked List and inserts a node at the head of the newly created list if `data` is given.\n - **insertFront**(\u003c * \u003edata) - *void* - Create a node from `data` and inserts at the front of the list.\n - **insertNth**(\u003c *number* \u003eindex, \u003c * \u003edata) - *boolean* - Create a node from `data` and insert in the location of the linked list specified by `index`.\n - **insertAfter**(\u003c * \u003etargetData, \u003c * \u003edata) - *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.\n - **insertBack**(\u003c * \u003edata) - *void* - Create a node from `data` and inserts at the back of the list.\n - **remove**(\u003c * \u003edata) - *boolean* - Removes the element specified by `data` and returns `true` if the element was successfully found and removed from the linked list.\n - **removeNth**(\u003c *number* \u003eindex) - *void* - Removes the element in the location of the linked list specified by `index`.\n - **find**(\u003c * \u003edata) - *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.\n - **findNth**(\u003c *number* \u003eindex) - *Node* - Finds the element in the location of the linked list specified by `index` and returns that `Node`.\n\n\n### \u003ca href=\"#hashmap\" name=\"hashmap\"\u003eNeedle.Hashmap()\u003c/a\u003e\n**state** - *number* - Holds the current hash of the internal window.\u003cbr /\u003e\n \n - **(constructor)**() - *object* - Creates and instatiates a Hashmap object.\n - **put**(\u003c * \u003ekey, \u003c * \u003evalue) - *void* - Inserts an entry into the hashmap, which maps the given `key` to its respective `value`.\n - **get**(\u003c * \u003ekey) - *value* - Returns the value that is paired with the given `key`.\n - **delete**(\u003c * \u003ekey) - *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.\n - **iterator**() - *key* - Resets the internal iterator `Node` to the first entry and returns the unhashed key.\n - **next**() - *key* - Iterates to the next `Node` and returns an the unhashed key.\n - **size**() - *number* - Returns the amount of unique entries within the hashmap.\n\n\n### \u003ca href=\"#rollinghash\" name=\"rollinghash\"\u003eNeedle.RollingHash()\u003c/a\u003e\n**state** - *number* - The internal hash value of the current window.\u003cbr /\u003e\n\n - **(constructor)**(\u003c *number* \u003ebase) - *object* - Creates and instatiates a rolling hash object and an argument is passed in which assigns the `base` of the rolling hash.\n - **set**(\u003c *string || Array* \u003earg) - *void* - Sets the internal window of the rolling hash given `arg` in the relative base.\n - **slide**(\u003c *string || number* \u003eold, \u003c *string || number* \u003enew) - *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.\n - **skip**(\u003c *string || number* \u003eold) - *void* - Disjoins the `old` segment from the internal window.\n - **append**(\u003c *string || number* \u003enew) - *void* - Appends a `new` segment onto the internal window.\n - **hash**(\u003c *number || string || Array*arg\u003e) - *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.\n\n\n### \u003ca href=\"#singlylinkedlist\" name=\"singlylinkedlist\"\u003eNeedle.SinglyLinkedList()\u003c/a\u003e\n**head** - *Node* - The first node in the linked list.\u003cbr /\u003e\n**size** - *number* - The number of nodes in the linked list.\u003cbr /\u003e\n\n - **(constructor)**([\u003c * \u003edata]) - *object* - Creates a Singly Linked List and inserts a node at the head of the newly created list if `data` is given.\n - **insertFront**(\u003c * \u003edata) - *void* - Create a node from `data` and inserts at the front of the list.\n - **insertNth**(\u003c *number* \u003eindex, \u003c * \u003edata) - *boolean* - Create a node from `data` and insert in the location of the linked list specified by `index`.\n - **insertAfter**(\u003c * \u003etargetData, \u003c * \u003edata) - *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.\n - **insertBack**(\u003c * \u003edata) - *void* - Create a node from `data` and inserts at the back of the list.\n - **remove**(\u003c * \u003edata) - *boolean* - Removes the element specified by `data` and returns `true` if the element was successfully found and removed from the linked list.\n - **removeNth**(\u003c *number* \u003eindex) - *void* - Removes the element in the location of the linked list specified by `index`.\n - **find**(\u003c * \u003edata) - *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.\n - **findNth**(\u003c *number* \u003eindex) - *Node* - Finds the element in the location of the linked list specified by `index` and returns that `Node`.\n\n### \u003ca href=\"#stack\" name=\"stack\"\u003eNeedle.Stack()\u003c/a\u003e\n**top** - *Node* - The top node in the stack.\u003cbr /\u003e\n**size** - *number* - The number of nodes in the stack.\u003cbr /\u003e\n \n - **(constructor)**([\u003c * \u003edata]) - *object* - Creates a Stack and if data is passed given, the top element of the queue, defined by `data`, is created and inserted.\n - **peek**() - *Node* - Returns the top `Node` of the stack.\n - **push**(\u003c * \u003edata) - *void* - Adds and element, defined by `data`, to the top of the stack.\n - **pop**() - *Node* - Removes the top element of the stack and returns the `Node` that was previously the top, and just deleted.\n\n\n### \u003ca href=\"#queue\" name=\"queue\"\u003eNeedle.Queue()\u003c/a\u003e\n**front** - *Node* - The first node in the queue.\u003cbr /\u003e\n**back** - *Node* - The last node in the queue.\u003cbr /\u003e\n**size** - *number* - The number of nodes in the queue.\u003cbr /\u003e\n \n - **(constructor)**([\u003c * \u003edata]) - *object* - Creates a Queue and if data is passed given, the first element of the queue, defined by `data`, is created and inserted.\n - **enqueue**(\u003c * \u003edata) - *void* - Adds and element, defined by `data`, to the queue.\n - **dequeue**() - *void* - Removes the first element of the queue.\n\n\n## Examples\n\nHere 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:zuber.nicholas@gmail.com).\n\n```javascript\n// Priority Queue implementation using a binary heap\n\nconst Needle = require('node-needle');\n\nvar Level = function(key, value){\n  this.key = key;\n  this.value = value;\n}\n\nvar priorityQueue = new Needle.BinaryHeap(function(a, b){\n  return a.key \u003c b.key;\n});\n\npriorityQueue.insert(new Level(3, \"Level 3\"));\npriorityQueue.insert(new Level(1, \"Level 1\"));\npriorityQueue.insert(new Level(2, \"Level 2\"));\n\npriorityQueue.peek(); // =\u003e {1, \"Level 1\"}\npriorityQueue.size(); // =\u003e 3\n\npriorityQueue.delete();\n\npriorityQueue.peek(); // =\u003e {2, \"Level 2\"}\npriorityQueue.size(); // =\u003e 2\n\n```\n\n```javascript\n// Iterating through a Hashmap\n\nconst Needle = require('node-needle');\n\nvar map = new Needle.Hashmap();\n\nmap.put(1, \"Level 1\");\nmap.put(\"2\", \"Level 2\");\nmap.put({key: \"three\"}, \"Level 3\");\n\n// Insertion order is kept, despite key value\nfor(var it = map.iterator(); it !== null; it = map.next()){\n  console.log(it); // 1 -\u003e \"2\" -\u003e {key: \"three\"}\n  console.log(map.get(it)); // \"Level 1\" -\u003e \"Level 2\" -\u003e \"Level 3\"\n}\n\n```\n\n## License\n[MIT](https://opensource.org/licenses/MIT)\n\nCopyright (c) 2015 Nick Zuber\n","funding_links":[],"categories":["JavaScript","node"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickzuber%2Fneedle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickzuber%2Fneedle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickzuber%2Fneedle/lists"}