New: HashMap implementation

Author: nzakas

src/data-structures/doubly-linked-list/README.md

@@ -11,7 +11,8 @@ A JavaScript implementation of a doubly linked list. This class uses the convent
 1. There is a `[Symbol.iterator]` method so each instance is iterable.
 1. The `size` getter property instead of a `length` data property to indicate that the size of the list is dynamically counted rather than stored.
 1. Defining a `values()` generator method.
-1. Defining a `find()` method for searching the list.
+1. Defining a `find()` method for searching the list to return data.
+1. Defining a `findIndex()` method for searching the list to return an index.
 1. Returning `undefined` from `get()` when no such index exists.
 
 Read the [blog post](https://humanwhocodes.com/blog/2019/02/computer-science-in-javascript-doubly-linked-lists/) about the design of this class.
@@ -47,6 +48,7 @@ let index = list.indexOf("foo");
 
 // search for a value
 let result = list.find(value => value.length > 3);
+let foundIndex = list.findIndex(value => value.length > 3);
 
 // convert to an array using iterators
 let array1 = [...list.values()];

src/data-structures/doubly-linked-list/doubly-linked-list.js

@@ -408,6 +408,45 @@ class DoublyLinkedList {
          * of the loop below.
          */
         let current = this[head];
+        
+        /*
+         * This loop checks each node in the list to see if it matches.
+         * If a match is found, it returns the data immediately, exiting the
+         * loop because there's no reason to keep searching. The search
+         * continues until there are no more nodes to search (when `current` is `null`).
+         */
+        while (current !== null) {
+            if (matcher(current.data)) {
+                return current.data;
+            }
+
+            // traverse to the next node in the list
+            current = current.next;
+        }
+
+        /*
+         * If execution gets to this point, it means we reached the end of the
+         * list and didn't find `data`. Just return `undefined` as the 
+         * "not found" value.
+         */
+        return undefined;
+    }
+    
+    /**
+     * Returns the index of the first item that matches a given function.
+     * @param {Function} matcher A function returning true when an item matches
+     *      and false when an item doesn't match.
+     * @returns {int} The index of the first item that matches a given function
+     *      or -1 if there are no matching items.
+     */
+    findIndex(matcher) {
+    
+        /*
+         * The `current` variable is used to iterate over the list nodes.
+         * It starts out pointing to the head and is overwritten inside
+         * of the loop below.
+         */
+        let current = this[head];
 
         /*
          * The `index` variable is used to track how deep into the list we've
@@ -418,13 +457,13 @@ class DoublyLinkedList {
 
         /*
          * This loop checks each node in the list to see if it matches.
-         * If a match is found, it returns the data immediately, exiting the
+         * If a match is found, it returns the index immediately, exiting the
          * loop because there's no reason to keep searching. The search
          * continues until there are no more nodes to search (when `current` is `null`).
          */
         while (current !== null) {
             if (matcher(current.data)) {
-                return current.data;
+                return index;
             }
 
             // traverse to the next node in the list
@@ -436,10 +475,10 @@ class DoublyLinkedList {
 
         /*
          * If execution gets to this point, it means we reached the end of the
-         * list and didn't find `data`. Just return `undefined` as the 
+         * list and didn't find `data`. Just return -1 as the 
          * "not found" value.
          */
-        return undefined;
+        return -1;
     }
 
     /**

src/data-structures/doubly-linked-list/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanwhocodes/doubly-linked-list",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A doubly linked list implementation in JavaScript",
   "main": "doubly-linked-list.js",
   "scripts": {

src/data-structures/hash-map/README.md

@@ -0,0 +1,71 @@
+# JavaScript Hash Map Class
+
+by [Nicholas C. Zakas](https://humanwhocodes.com)
+
+If you find this useful, please consider supporting my work with a [donation](https://humanwhocodes.com/donate).
+
+## Overview
+
+A JavaScript implementation of a hash map where all keys must be strings. This class uses the conventions of built-in JavaScript collection objects, such as:
+
+1. There is a `[Symbol.iterator]` method so each instance is iterable.
+1. The `size` getter property instead of a `length` data property to indicate that the size of the list is dynamically counted rather than stored.
+1. Defining `entries()`, `keys()`, and `values()` generator methods.
+
+## Usage
+
+Use CommonJS to get access to the `HashMap` constructor:
+
+```js
+const { HashMap } = require("@humanwhocodes/hash-map");
+```
+
+Each instance of `HashMap` has the following properties and methods:
+
+```js
+const map = new HashMap();
+
+// add an item
+map.set("foo", 1);
+
+// get the value of an item
+let value = map.get("foo");
+
+// get the number of items
+let count = map.size;
+
+// does the key exist in the map?
+let found = map.has("foo");
+
+// remove a key
+map.delete("foo");
+
+// get all key-value pairs
+let entries1 = [...map.entries()];
+let entries2 = [...map];
+
+// get all keys
+let keys = [...map.keys()];
+
+// get all values
+let values = [...map.values()];
+
+// remove all items
+map.clear();
+```
+
+## Note on Code Style
+
+You may find the code style of this module to be overly verbose with a lot of comments. That is intentional, as the primary use of this module is intended to be for educational purposes. There are frequently more concise ways of implementing the details of this class, but the more concise ways are difficult for newcomers who are unfamiliar with linked lists as a concept or JavaScript as a whole.
+
+## Note on Usage
+
+This module is intended for educational purposes. For production purposes, you should use the native JavaScript `Map` class.
+
+## Issues and Pull Requests
+
+As this is part of series of tutorials I'm writing, only bug fixes will be accepted. No new functionality will be added to this module.
+
+## License
+
+MIT