chore: integrate binary-search (#10)

* chore: integrate binary-search

* add readme.md

Author: Uzlopak

package-lock.json

@@ -36,8 +36,5 @@
     "borp": "^0.17.0",
     "tslint": "^5.20.1",
     "typescript": "^5.5.4"
-  },
-  "dependencies": {
-    "binary-search": "^1.3.6"
   }
 }

package.json

@@ -0,0 +1,35 @@
+binary-search
+=============
+
+Integrated from https://github.com/darkskyapp/binary-search
+
+This is a really tiny, stupid, simple binary search library for Node.JS. We wrote it because existing solutions were bloated and incorrect. This version is a straight port of the Java version mentioned by Joshua Bloch in his article, [Nearly All Binary Searches and Merge Sorts are Broken](http://googleresearch.blogspot.com/2006/06/extra-extra-read-all-about-it-nearly.html).
+
+You pass the function a sorted array, a value, and the sort comparator function. If the value is found in the array, it returns a nonnegative integer representing the index of the value in the array. (Note that if your array contains duplicates, the index within the run of duplicates is arbitrary.) If the value is _not_ in the array, then `-(index + 1)` is returned, where `index` is where the value should be inserted into the array to maintain sorted order.
+
+You may also pass the search function optional fourth and fifth arguments, representing the minimum and maximum indices of the array to search, in case you wish to limit the section of the array searched. (These default, of course, to `0` and `length-1`, respectively.)
+
+The sort comparator function should be the same one you use to sort your array. It accepts optional third and fourth arguments, the current index and the overall array: these should not be necessary except in highly unusual circumstances.
+
+Thanks to [Conrad Irwin](https://github.com/ConradIrwin) and [Michael Marino](https://github.com/mgmarino) for, ironically, pointing out bugs.
+
+Example
+-------
+
+```js
+var bs = require("binary-search");
+
+bs([1, 2, 3, 4], 3, function(element, needle) { return element - needle; });
+// => 2
+
+bs([1, 2, 4, 5], 3, function(element, needle) { return element - needle; });
+// => -3
+```
+
+License
+-------
+
+To the extent possible by law, The Dark Sky Company, LLC has [waived all
+copyright and related or neighboring rights][cc0] to this library.
+
+[cc0]: http://creativecommons.org/publicdomain/zero/1.0/

src/binary-search/README.md

@@ -0,0 +1,65 @@
+/**
+ * @param haystack
+ * @param needle
+ * @param comparator Notes about comparator return value:
+ *   when a<b the comparator's returned value should be:
+ *   negative number or a value such that `+value` is a negative number
+ *   examples: `-1` or the string `"-1"`
+ *   when a>b the comparator's returned value should be:
+ *   positive number or a value such that `+value` is a positive number
+ *   examples: `1` or the string `"1"`
+ *   when a===b
+ * any value other than the return cases for a<b and a>b
+ * examples: undefined, NaN, 'abc'
+ * @param low
+ * @param high
+ * @returns {number} returns index of found result or number < 0 if not found
+ */
+export function binarySearch<A, B>(
+    haystack: ArrayLike<A>,
+    needle: B,
+    comparator: (a: A, b: B, index?: number, haystack?: ArrayLike<A>) => any,
+    low?: number,
+    high?: number): number {
+    let mid;
+    let cmp;
+
+    if (low === undefined) {
+      low = 0;
+    } else {
+      low = low | 0;
+      if (low < 0 || low >= haystack.length) {
+        throw new RangeError('invalid lower bound');
+      }
+    }
+
+    if (high === undefined) {
+      high = haystack.length - 1;
+    } else {
+      high = high | 0;
+      if (high < low || high >= haystack.length) {
+        throw new RangeError('invalid upper bound');
+      }
+    }
+
+    while (low <= high) {
+      // The naive `low + high >>> 1` could fail for array lengths > 2**31
+      // because `>>>` converts its operands to int32. `low + (high - low >>> 1)`
+      // works for array lengths <= 2**32-1 which is also Javascript's max array
+      // length.
+      mid = low + ((high - low) >>> 1);
+      cmp = +comparator(haystack[mid], needle, mid, haystack);
+
+      // Too low.
+      if (cmp < 0.0) {
+        low  = mid + 1;
+      } else if (cmp > 0.0) {
+        high = mid - 1;
+ } else {
+        return mid;
+ }
+    }
+
+    // Key not found.
+    return ~low;
+  }

src/binary-search/binary-search.ts

@@ -1,5 +1,5 @@
 import * as assert from 'assert';
-import binarySearch = require('binary-search');
+import { binarySearch } from '../binary-search/binary-search';
 import { Edge } from '../edge';
 
 /**

src/node/base.ts

@@ -0,0 +1,50 @@
+import { describe, it, type TestContext } from 'node:test';
+import { binarySearch } from '../src/binary-search/binary-search';
+
+describe('binarysearch', () => {
+  const arr = [1, 2, 2, 2, 3, 5, 9];
+  const cmp = (a: number, b: number) => a - b;
+
+  it('should bail if not passed an array', (t: TestContext) => {
+    // @ts-expect-error
+    t.assert.throws(() => { binarySearch(undefined, 3, cmp); }, TypeError);
+  });
+
+  it('should bail if not passed a comparator', (t: TestContext) => {
+    // @ts-expect-error
+    t.assert.throws(() => { binarySearch(arr, 3, undefined); }, TypeError);
+  });
+
+  it('should return the index of an item in a sorted array', (t: TestContext) => {
+    t.assert.strictEqual(binarySearch(arr, 3, cmp), 4);
+  });
+
+  it('should return the index of where the item would go plus one, negated, if the item is not found',
+    (t: TestContext) => {
+      t.assert.strictEqual(binarySearch(arr, 4, cmp), -6);
+    });
+
+  it('should return any valid index if an item exists multiple times in the array',
+    (t: TestContext) => {
+      t.assert.strictEqual(binarySearch(arr, 2, cmp), 3);
+    });
+
+  it('should work even on empty arrays', (t: TestContext) => {
+    t.assert.strictEqual(binarySearch([], 42, cmp), -1);
+  });
+
+  it('should work even on arrays of doubles', (t: TestContext) => {
+    t.assert.strictEqual(binarySearch([0.0, 0.1, 0.2, 0.3, 0.4], 0.25, cmp), -4);
+  });
+
+  it('should pass the index and array parameters to the comparator', (t: TestContext) => {
+    const indexes: number[] = [];
+    const indexCmp = (a: number, b: number, i?: number, array?: ArrayLike<number>) => {
+      t.assert.strictEqual(array, arr);
+      indexes.push(i!);
+      return cmp(a, b);
+    };
+    binarySearch(arr, 3, indexCmp);
+    t.assert.deepStrictEqual(indexes, [3, 5, 4]);
+  });
+});