feat: 🎉 begin project

README.md

@@ -0,0 +1 @@
+# nodejs-utilities

algorithms/binarySearch.js

@@ -0,0 +1,16 @@
+module.exports = function binarySearch(array, key) {
+  let start = 0;
+  let end = array.length - 1;
+  let middle = Math.floor((start + end) / 2);
+
+  while (array[middle] !== key && start <= end) {
+    if (key < array[middle]) {
+      end = middle - 1;
+    } else {
+      start = middle + 1;
+    }
+    middle = Math.floor((start + end) / 2);
+  }
+
+  return array[middle] === key ? middle : -1;
+};

algorithms/index.js

@@ -0,0 +1,4 @@
+module.exports = {
+  binarySearch: require('./binarySearch'),
+  selectionSort: require('./selectionSort'),
+};

algorithms/selectionSort.js

@@ -0,0 +1,10 @@
+module.exports = function selectionSort(array) {
+  for (let i = 0; i < array.length - 1; i++) {
+    let minIndex = i;
+    for (let j = i + 1; j < array.length; j++)
+      if (array[j] < array[minIndex]) minIndex = j;
+
+    [array[i], array[minIndex]] = [array[minIndex], array[i]];
+  }
+  return array;
+};

errors/index.js

@@ -0,0 +1,4 @@
+module.exports = {
+  QueueOverflowError: require('./queue'),
+  StackOverflowError: require('./stack'),
+};

errors/queue.js

@@ -0,0 +1,7 @@
+module.exports = class QueueOverflowError extends Error {
+  constructor(maxSize) {
+    super(`Queue is full (max size is ${maxSize})`);
+    this.name = Object.getPrototypeOf(this).constructor.name;
+    this.maxSize = maxSize;
+  }
+};

errors/stack.js

@@ -0,0 +1,7 @@
+module.exports = class StackOverflowError extends Error {
+  constructor(maxSize) {
+    super(`Stack is full (max size is ${maxSize})`);
+    this.name = Object.getPrototypeOf(this).constructor.name;
+    this.maxSize = maxSize;
+  }
+};

index.js

@@ -0,0 +1,5 @@
+module.exports = {
+  errors: require('./errors'),
+  ...require('./algorithms'),
+  ...require('./structures'),
+};

package.json

@@ -0,0 +1,23 @@
+{
+  "name": "nodejs-utilities",
+  "version": "1.0.0",
+  "description": "Utility functions and classes",
+  "main": "index.js",
+  "typings": "types/index.d.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RichardDorian/nodejs-utilities.git"
+  },
+  "keywords": [
+    "utilities"
+  ],
+  "author": "RichardDorian",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/RichardDorian/nodejs-utilities/issues"
+  },
+  "homepage": "https://github.com/RichardDorian/nodejs-utilities#readme"
+}

structures/index.js

@@ -0,0 +1,4 @@
+module.exports = {
+  ...require('./queue'),
+  ...require('./stack'),
+};

structures/queue.js

@@ -0,0 +1,56 @@
+const { QueueOverflowError } = require('../errors');
+
+class Queue {
+  #first;
+  #last;
+
+  constructor(maxSize) {
+    this.#first = null;
+    this.#last = null;
+    this.length = 0;
+    this.maxSize = maxSize;
+  }
+
+  enqueue(value) {
+    if (this.isFull()) throw new QueueOverflowError(this.maxSize);
+
+    const node = new QueueNode(value);
+
+    if (this.isEmpty()) {
+      this.#first = node;
+      this.#last = node;
+    } else {
+      this.#last.next = node;
+      this.#last = node;
+    }
+
+    this.length++;
+  }
+
+  dequeue() {
+    if (!this.#first) return null;
+
+    const value = this.#first.value;
+    this.#first = this.#first.next;
+    this.length--;
+
+    return value;
+  }
+
+  isEmpty() {
+    return this.length === 0;
+  }
+
+  isFull() {
+    return this.maxSize && this.length >= this.maxSize;
+  }
+}
+
+class QueueNode {
+  constructor(value) {
+    this.value = value;
+    this.next = null;
+  }
+}
+
+module.exports = { Queue, QueueNode };

structures/stack.js

@@ -0,0 +1,51 @@
+const { StackOverflowError } = require('../errors');
+
+class Stack {
+  #first;
+
+  constructor(maxSize) {
+    this.#first = null;
+    this.length = 0;
+    this.maxSize = maxSize;
+  }
+
+  push(value) {
+    if (this.isFull()) throw new StackOverflowError(this.maxSize);
+
+    const node = new StackNode(value);
+    node.next = this.#first;
+    this.#first = node;
+    this.length++;
+  }
+
+  pop() {
+    if (!this.#first) return null;
+
+    const value = this.#first.value;
+    this.#first = this.#first.next;
+    this.length--;
+    return value;
+  }
+
+  peek() {
+    if (!this.#first) return null;
+    return this.#first.value;
+  }
+
+  isEmpty() {
+    return this.length === 0;
+  }
+
+  isFull() {
+    return this.maxSize && this.length >= this.maxSize;
+  }
+}
+
+class StackNode {
+  constructor(value) {
+    this.value = value;
+    this.next = null;
+  }
+}
+
+module.exports = { Stack, StackNode };

types/algorithms.d.ts

@@ -0,0 +1,56 @@
+declare module 'nodejs-utilities/algorithms' {
+  /**
+   * In computer science, binary search, also known as half-interval
+   * search, logarithmic search, or binary chop, is a search algorithm
+   * that finds the position of a target value within a sorted array.
+   * Binary search compares the target value to the middle element
+   * of the array. [Wikipedia](https://en.wikipedia.org/wiki/Binary_search_algorithm)
+   *
+   * Time complexity:
+   * - `Ω(1)`
+   * - `O(log n)`
+   * @param array Sorted array to search in
+   * @param key The key to search for
+   * @returns The index of the key if found, `-1` otherwise
+   * @example In an sorted array of numbers
+   * ```javascript
+   * // Sorted array of numbers
+   * const arr = [ 2, 4, 8, 16, 32, 64, 128 ];
+   *
+   * binarySearch(arr, 8); // 2
+   * binarySearch(arr, 16); // 3
+   * binarySearch(arr, 256); // -1
+   * ```
+   * @example In a sorted array of strings
+   * ```javascript
+   * const arr = [ 'a', 'b', 'c', 'd', 'e', 'f', 'g' ];
+   * binarySearch(arr, 'c'); // 2
+   * binarySearch(arr, 'z'); // -1
+   * ```
+   * @since `[email protected]`
+   */
+  export function binarySearch<T = any>(array: T[], key: T): number;
+  /**
+   * In computer science, selection sort is an in-place comparison
+   * sorting algorithm. It has an O(n²) time complexity, which makes
+   * it inefficient on large lists, and generally performs worse
+   * than the similar insertion sort. [Wikipedia](https://en.wikipedia.org/wiki/Selection_sort)
+   *
+   * Time complexity:
+   * - `Θ(n²)`
+   * @param array The array to sort
+   * @returns The sorted array
+   * @example Unsorted array of numbers
+   * ```javascript
+   * const arr = [ 9, 7, 2, 6, 4, 42 ];
+   * selectionSort(arr); // [ 2, 4, 6, 7, 9, 42 ]
+   * ```
+   * @example Unsorted array of strings
+   * ```javascript
+   * const arr = [ 'b', 'y', 'q', 'k' ];
+   * selectionSort(arr); // [ 'b', 'k', 'q', 'y' ]
+   * ```
+   * @since `[email protected]`
+   */
+  export function selectionSort<T = any>(array: T[]): T[];
+}

types/errors.d.ts

@@ -0,0 +1,5 @@
+declare module 'nodejs-utilities/errors' {
+  export class QueueOverflowError extends Error {
+    public constructor(maxSize: number);
+  }
+}

types/index.d.ts

@@ -0,0 +1,10 @@
+/// <reference path="algorithms.d.ts" />
+/// <reference path="errors.d.ts" />
+/// <reference path="structures.d.ts" />
+
+declare module 'nodejs-utilities' {
+  import * as err from 'nodejs-utilities/errors';
+  export const errors = err;
+  export * from 'nodejs-utilities/algorithms';
+  export * from 'nodejs-utilities/structures';
+}