Add SinglyLinkedList Data Structure Class (#1)

* Add SinglyLinkedList with push method

* Add Pop to SinglyLinkedList

* Add lessons learned to README

* Add todo methods and snub tests

* Add shift method to SinglyLinkedList

* Add unshift method to SinglyLinkedList class

* Add get method to SinglyLinkedList

* Add link to SinglyLinkedList README

* Add set method to SinglyLinkedList

* Add insert and remove methods to SinglyLinkedList

* Add reverse method to SLL

* Make methods private and remove optional chaining

* Update method names

* Update tests

* Add list v array to README

* Update class to use TS private modifier

* Update tests to utilize beforeEach

Author: rfearing

README.md

@@ -15,7 +15,7 @@ If you are looking for a location to learn data structures in JavaScript, [this
 Each Data Structure will have it's own README describing the data structure. Hopefully, this list will continue to grow.
 
 **Data Structures:**
-- [ ] Singly Linked List
+- [Singly Linked List](src/singlyLinkedList/README.md)
 - [ ] Double Linked List
 - [ ] Stack
 - [ ] Queue
@@ -24,7 +24,9 @@ Each Data Structure will have it's own README describing the data structure. Hop
 - [ ] Hash Table
 - [ ] Graph
 
+I'm utilizing the [Wiki page as a "lessons learned" section][lessons-learned]. Hopefully it'll help future me, and whoever stumbles upon this repo.
+
 <!-- Links -->
 [datastructures-js]:https://datastructures-js.github.io/
 [js-algo]:https://github.com/trekhleb/javascript-algorithms
-
+[lessons-learned]:https://github.com/rfearing/js-data-structures/wiki/What-I-learned-along-the-way

assets/singly-linked-assert-error.png

@@ -1,6 +1,6 @@
 {
   "name": "@rfearing/js-data-structures",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Examples of Data Structures in JavaScript",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

assets/singly-linked-list.png

@@ -1 +1 @@
-export const Greeter = (name: string) => `Hello ${name}`;
+export { SinglyLinkedList } from './singlyLinkedList';

package.json

@@ -0,0 +1,19 @@
+# Singly Linked List
+
+From [geeksongeeks.com][geeks]:
+
+> [A singly linked list] is the simplest type of linked list in which every node contains some data and a pointer to the next node of the same data type. The node contains a pointer to the next node means that the node stores the address of the next node in the sequence. A single linked list allows traversal of data only in one way
+
+<img src="../../assets/singly-linked-list.png" width="300" alt="Graph representation of a singly linked list" />
+
+### Singly Linked List vs Array
+
+| Lists                                       | Array                                       |
+|---------------------------------------------|---------------------------------------------|
+| Do not have indexes                         | Indexed in order                            |
+| Connected via nodes with a **next** pointer | Insertion &amp; deletion can be expensive   |
+| Random access is not allowed                | Can quickly be accessed at a specific index |
+
+Singly linked list is preferred when we need to save memory and searching is not required as pointer of single index is stored.
+
+[geeks]: https://www.geeksforgeeks.org/types-of-linked-list/#:~:text=Singly%20Linked%20List%3A%20It%20is,next%20node%20in%20the%20sequence.

src/index.ts

@@ -0,0 +1,259 @@
+import { SinglyLinkedNode as Node } from './node';
+import assert from 'assert';
+
+export class SinglyLinkedList<T> {
+  constructor() {
+    this.head = null;
+    this.tail = null;
+    this.length = 0;
+  }
+
+  private head: Node<T> | null;
+  private tail: Node<T> | null;
+  private length: number;
+
+  /**
+   * Return whether or not the SinglyLinkedList has any nodes.
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.length === 0;
+  }
+
+  /**
+   * Get a node at a given position.
+   * @param {number} index - Where the node is located in the list.
+   * @returns {SinglyLinkedNode | null}
+   */
+  private getNode(index: number) {
+    if (this.isEmpty() || index >= this.length || index < 0) {
+      return null;
+    }
+    let current: Node<T> | null = this.head;
+    // If index is 0, we'll never loop
+    for (let i = 0; i < index; i++) {
+      assert(current); // We are sure we're never out of bounds
+      current = current.getNext();
+    }
+    return current;
+  }
+
+  /**
+   * Get length of the list.
+   * @returns {number}
+   */
+  getLength() {
+    return this.length;
+  }
+
+  /**
+   * Insert a node at the end of the list
+   * @param {T} val
+   * @returns {SinglyLinkedNode}
+   */
+  insertLast(val: T) {
+    const newNode = new Node(val);
+    if (this.isEmpty()) {
+      this.head = newNode;
+      this.tail = this.head;
+    } else {
+      assert(this.tail);
+      this.tail.setNext(newNode);
+      this.tail = newNode;
+    }
+    this.length++;
+    return this.head;
+  }
+
+  /**
+   * Remove a node from the end of the list
+   * @returns {SinglyLinkedNode} The removed node
+   */
+  removeLast() {
+    if (this.isEmpty()) {
+      return null;
+    }
+    assert(this.head);
+
+    let newTail = this.head;
+    let current: Node<T> | null = this.head;
+    let persist = true;
+
+    // We want to get to the second to last node:
+    while (persist) {
+      assert(current);
+      newTail = current;
+      if (current.getNext()) {
+        current = current.getNext();
+      } else {
+        // If getNext is null. We can safely exit.
+        persist = false;
+      }
+    }
+
+    // and then set it to the new tail:
+    newTail.setNext();
+    this.tail = newTail;
+    this.length--;
+
+    // Reset if popped the last node.
+    if (this.isEmpty()) {
+      this.head = null;
+      this.tail = null;
+    }
+
+    return current;
+  }
+
+  /**
+   * Remove a node from the beginning of the list.
+   * returns {SinglyLinkedNode} The removed node
+   */
+  removeFirst() {
+    if (this.isEmpty()) {
+      return null;
+    }
+    assert(this.head);
+    const oldHead = this.head;
+    this.head = oldHead.getNext() || null;
+    this.length--;
+
+    // Unlink the old head.
+    oldHead.setNext();
+
+    // Reset tail if shifted the last node.
+    if (this.isEmpty()) {
+      this.tail = null;
+    }
+    return oldHead;
+  }
+
+  /**
+   * Add a node to the beginning of the list.
+   * @param {T} val
+   * @returns {SinglyLinkedNode}
+   */
+  insertFirst(value: T) {
+    const newNode = new Node(value);
+    // Tail and head are the newNode if empty.
+    if (this.isEmpty()) {
+      this.head = newNode;
+      this.tail = this.head;
+    }
+    // Set newNode next to the current head's next
+    newNode.setNext(this.head);
+    // Then set as the new head
+    this.head = newNode;
+    this.length++;
+    return this.head;
+  }
+
+  /**
+   * Get a value from a node at a given position.
+   * @param {number} index - Where the node is located in the list.
+   * @returns {T} - the value passed into the SinglyLinkedNode constructor
+   */
+  get(index: number) {
+    const searchedNode = this.getNode(index);
+    return searchedNode ? searchedNode.getValue() : null;
+  }
+
+  /**
+   * Set a node at the current position.
+   * @param {T} value - Value to replace at index.
+   * @param {number} index - Where the node is located in the list
+   * @returns {SinglyLinkedNode | null}
+   */
+  set(value: T, index: number) {
+    // We can utilize the logic from our get method
+    const foundNode = this.getNode(index);
+    if (!foundNode) {
+      return null;
+    }
+    foundNode.setValue(value);
+    return foundNode;
+  }
+
+  /**
+   * Insert a new node at the specified position
+   * @param {T} value - Value for the new node to place at index
+   * @param {number} index - Where the node is located in the list
+   */
+  insert(value: T, index: number) {
+    if (index > this.length || index < 0) {
+      throw new Error('The index was outside of the List');
+    }
+
+    if (index === 0) {
+      return !!this.unshift(value);
+    }
+
+    if (index === this.length) {
+      return !!this.push(value);
+    }
+
+    const newNode = new Node(value);
+    const previous = this.getNode(index - 1);
+    if (previous) {
+      newNode.setNext(previous.getNext());
+      previous.setNext(newNode);
+    }
+
+    this.length++;
+    return true;
+  }
+
+  /**
+   * Remove a node from the list at a given index.
+   * @param index - The index of the node we want to remove.
+   * @returns {SinglyLinkedNode | null} - The removed node.
+   */
+  remove(index: number) {
+    // Get head, tail cases first:
+    if (index === 0) {
+      return this.shift();
+    }
+    if (index === this.length - 1) {
+      return this.pop();
+    }
+
+    const previous = this.getNode(index - 1);
+    assert(previous);
+
+    const removed = previous.getNext();
+    assert(removed);
+
+    previous.setNext(removed.getNext());
+    this.length--;
+    return removed;
+  }
+
+  /**
+   * Reverse the list to point in the opposite direction.
+   * Note, this does not really have a real-world use-case.
+   * Other than to learn, this could be asked, in some contexts, as an interview question.
+   * @returns {SinglyLinkedList<T>}
+   */
+  reverse() {
+    // Swap head for tail:
+    let node = this.head;
+    this.head = this.tail;
+    this.tail = node;
+    let next;
+    let previous = null;
+    for (let i = 0; i < this.length; i++) {
+      assert(node);
+      next = node.getNext(); // First iteration, this will be this.head.next
+      node.setNext(previous); // First iteration, will set next to null, as it's the new tail.
+      previous = node;
+      node = next;
+    }
+    return null;
+  }
+
+  // Aliases
+  push = this.insertLast;
+  pop = this.removeLast;
+  shift = this.removeFirst;
+  unshift = this.insertFirst;
+}

src/singlyLinkedList/README.md

@@ -0,0 +1,32 @@
+export class SinglyLinkedNode<T> {
+  constructor(value: T) {
+    this.value = value;
+    this.next = null;
+  }
+
+  private next: SinglyLinkedNode<T> | null;
+  private value: T | null;
+
+  setValue(value: T) {
+    this.value = value;
+  }
+
+  getValue() {
+    return this.value;
+  }
+
+  setNext(next?: SinglyLinkedNode<T> | null) {
+    if (next && !(next instanceof SinglyLinkedNode)) {
+      throw new Error('setNext expects a SinglyLinkedNode or null');
+    }
+    this.next = next || null;
+  }
+
+  getNext() {
+    return this.next;
+  }
+
+  hasNext() {
+    return !!this.next;
+  }
+}