atomic-fns 0.3.5 → 0.4.3

package/{core → dist}/collections/index.js

@@ -3,8 +3,7 @@
  *
  * @module Collections
  */
-import { partial } from '../functools/index.js';
-import { call, get, isArray, isArrayLike, isBool, isEmpty, isFunction, isIterable, isNull, isNumber, isObject, isString, isSymbol, keys, set } from '../globals/index.js';
+import { call, get, isArray, isArrayLike, isBool, isEmpty, isFunction, isIterable, isNull, isNumber, isObject, isString, keys, set } from '../globals/index.js';
 import { enumerate } from '../itertools/index.js';
 import { compare, eq, id } from '../operators/index.js';
 export * from './abc.js';
@@ -13,12 +12,12 @@ export * from './deque.js';
 export * from './frozenset.js';
 export * from './Heap.js';
 export * from './LRUCache.js';
-export * from './SortedSet.js';
 export * from './SortedMap.js';
+export * from './SortedSet.js';
 export * from './SortedTree.js';
 export * from './SplayTree.js';
 export function compact(arr) {
-    if (arr == null)
+    if (!arr)
         return;
     if (Array.isArray(arr))
         return arr.filter((x) => !isEmpty(x));
@@ -30,9 +29,9 @@ export function compact(arr) {
     }
     return result;
 }
-export function count(iterable, func) {
+export function count(obj, func) {
     const counters = {};
-    forEach(iterable, (value, key) => {
+    forEach(obj, (value, key) => {
         const result = func(value, key);
         counters[result] = get(result, counters, 0) + 1;
     });
@@ -42,116 +41,34 @@ export function count(iterable, func) {
  * Creates a function that can be used to create named tuple-like objects.
  * @example
 ```js
- * let Point = namedtuple('x', 'y', 'z')
- * let userObj = User(0, 0, 0)
- * // => {x: 0, y: 0, z: 0}
+let Point = namedtuple('x', 'y', 'z')
+let userObj = User(0, 0, 0)
+// {x: 0, y: 0, z: 0}
 ```
  * @param fields - A list of field names
  * @returns A function that can be called with the field values
  */
-export function namedtuple(...fields) {
-    return (...args) => fields.reduce((prev, f, i) => set(f, prev, args[i], false, true), {});
-}
-/**
- * Iterates over elements of collection, returning an array of all elements where predicate returns truthy value.
- *
- * The predicate is invoked with three arguments: `(value, index|key, arr)`.
- *
- * @example
-```js
- * let users = [
-  { 'user': 'barney', 'age': 36, 'active': true },
-  { 'user': 'fred',   'age': 40, 'active': false }
-]
-
-filter(users, o => !o.active)
- // => objects for ['fred']
-
-// The shape iteratee shorthand.
-filter(users, { age: 36, active: true })
-// => objects for ['barney']
-
-// The property iteratee shorthand.
-filter(users, 'active')
-// => objects for ['barney']
-```
- * @param {Array} arr The collection to iterate over
- * @param {Function} fn The predicate function invoked for each item
- * @returns {Array} The new filtered array
- */
+export const namedtuple = (...fields) => (...args) => fields.reduce((prev, f, i) => set(f, prev, args[i], false, true), {});
 export function filter(arr, fn = isNull) {
-    if (Array.isArray(arr)) {
-        if (isFunction(fn))
-            return arr.filter(fn);
-        if (isNumber(fn) || isString(fn) || isSymbol(fn))
-            return arr.filter((x) => get(fn, x));
-        if (isObject(fn))
-            return arr.filter(matches(fn));
-    }
+    if (!arr)
+        return;
+    const predicate = isFunction(fn) ? fn : isObject(fn) ? matches(fn) : (obj) => get(fn, obj);
+    const results = [];
+    forEach(arr, (value, key) => {
+        if (predicate(value, key, arr))
+            results.push(value);
+    });
+    return results;
 }
-/**
- * Iterates over elements of collection, returning the first element where predicate returns truthy value. The predicate is invoked with three arguments: `(value, index|key, collection)`.
- * @example
-```js
- let users = [
-  { 'user': 'barney',  'age': 36, 'active': true },
-  { 'user': 'fred',    'age': 40, 'active': false },
-  { 'user': 'pebbles', 'age': 1,  'active': true }
-]
-
-find(users, (o) => o.age < 40)
-// => object for 'barney'
-
-// The shape iteratee shorthand.
-find(users, { 'age': 1, 'active': true })
-// => object for 'pebbles'
-
-// The `property` iteratee shorthand.
-find(users, 'active')
-// => object for 'barney'
-```
- * @param {Array} arr The collection to iterate over.
- * @param {Function} fn The function invoked per iteration.
- * @returns {*} The matched element, else `undefined`.
- * @see {@link findRight}
- */
 export function find(arr, fn) {
+    const it = isFunction(fn) ? fn : isObject(fn) ? matches(fn) : (obj) => get(fn, obj);
     if (Array.isArray(arr)) {
-        if (isFunction(fn))
-            return arr.find(fn);
-        if (isNumber(fn) || isString(fn) || isSymbol(fn))
-            return arr.find((x) => x?.[fn]);
-        if (isObject(fn))
-            return arr.find(matches(fn));
+        return arr.find(it);
     }
-}
-/**
- * This method is like {@link find} except that it iterates from right to left.
- * @example
-```js
-findRight([1, 2, 3, 4], (n) => n % 2 === 1)
-//  => 3
-```
- * @param {Array} arr The collection to iterate over.
- * @param {Function} fn The function invoked per iteration.
- * @returns {*} The matched element, else `undefined`.
- * @see {@link find}
- */
-export function findRight(arr, fn) {
-    if (Array.isArray(arr)) {
-        for (let i = arr.length - 1; i >= 0; i--) {
-            const x = arr[i];
-            if (typeof fn === 'function') {
-                if (fn(x))
-                    return x;
-            }
-            else if (typeof fn === 'string') {
-                if (x?.[fn])
-                    return x;
-            }
-            else if (isObject(fn)) {
-                if (matches(fn)(x))
-                    return x;
+    else if (isObject(arr)) {
+        for (const key of Object.keys(arr)) {
+            if (it(arr[key], key, arr)) {
+                return arr[key];
             }
         }
     }
@@ -167,7 +84,7 @@ export function findRight(arr, fn) {
  * @returns {Array<*>} The given array.
  */
 export function insert(arr, index, value) {
-    if (!arr || arr.length <= index || index < 0)
+    if (!arr || index < 0)
         return arr;
     arr.splice(index, 0, value);
     return arr;
@@ -182,7 +99,7 @@ let objects = [
 ]
 
 filter(objects, matches({ a: 4, c: 6 }))
-// => [{ a: 4, b: 5, c: 6 }]
+// [{ a: 4, b: 5, c: 6 }]
 ```
  * @param shape
  * @returns
@@ -201,48 +118,42 @@ export function forEach(collection, fn) {
         for (let i = 0; i < collection.length; i++) {
             const res = fn(collection[i], i, collection);
             if (res === false)
-                return collection;
+                return;
         }
     }
     else if (isIterable(collection)) {
         for (const [index, value] of enumerate(collection)) {
             const res = fn(value, index, collection);
             if (res === false)
-                return collection;
+                return;
         }
     }
     else {
         for (const key of keys(collection)) {
             const res = fn(collection[key], key, collection);
             if (res === false)
-                return collection;
+                return;
         }
     }
 }
-/**
- * This method is like {@link forEach} except that it iterates over the collection from right to left.
-
- * @example
-```js
-forEachRight([1, 2], (value) => {
-  console.log(value)
-})
-// => Logs `2` then `1`.
-```
- * @param {Array|Object} collection The collection to iterate over.
- * @param {Iteratee} fn The function invoked per iteration.
- * @returns {*} Returns `collection`.
- * @see {@link forEach}
- * @see {@link filter}
- * @see {@link map}
- */
+export function findLast(arr, fn) {
+    let result;
+    const it = isFunction(fn) ? fn : matches(fn);
+    forEachRight(arr, (val, key) => {
+        if (it(val, key, arr)) {
+            result = val;
+            return false;
+        }
+    });
+    return result;
+}
 export function forEachRight(collection, fn) {
     if (Array.isArray(collection)) {
         for (let i = collection.length - 1; i >= 0; i--) {
             const value = collection[i];
             const res = fn(value, i, collection);
             if (res === false)
-                return collection;
+                return;
         }
     }
     else if (isObject(collection)) {
@@ -250,50 +161,12 @@ export function forEachRight(collection, fn) {
         for (let i = keys.length - 1; i >= 0; i--) {
             const key = keys[i];
             const value = collection[key];
-            const res = fn(value, i, collection);
+            const res = fn(value, key, collection);
             if (res === false)
-                return collection;
+                return;
         }
     }
-    return collection;
-}
-/**
- * Flattens an array or object. Arrays will be flattened recursively up to `depth` times. Objects will be flattened recursively.
- * @example
-```js
-flatten([1, [2, [3, [4]], 5]])
-// => [1, 2, [3, [4]], 5]
-
-flatten({
-  dates: {
-    expiry_date: '30 sep 2018',
-    available: '30 sep 2017',
-    min_contract_period: [
-      {
-        id: 1,
-        name: '1 month'
-      }
-    ]
-  },
-  price: {
-    currency: 'RM',
-    value: 1500
-  }
-})
-// => {
-  'dates.expiry_date': '30 sep 2018',
-  'dates.available': '30 sep 2017',
-  'dates.min_contract_period[0].id': 1,
-  'dates.min_contract_period[0].name': '1 month',
-  'price.currency': 'RM',
-  'price.value': 1500
 }
-```
- * @param {Array|Object} arr The array or object to flatten.
- * @param {number} [depth=1] The max recursion depth.
- * @returns {*} The new flattened array or object.
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat Array.flat()}
- */
 export function flatten(arr, depth = 1) {
     if (!depth)
         return arr;
@@ -339,73 +212,20 @@ function flattenObj(obj, prefix = '', result = {}, keepNull = false) {
     }
     return result;
 }
-/**
- * Creates an array of values by running each element in collection thru iteratee. The iteratee is invoked with three arguments: `(value, index|key, collection)`.
- * @example
-```js
-function square(n) {
-  return n * n
-}
-
-map([4, 8], square)
-// => [16, 64]
-
-map({ a: 4, b: 8 }, square)
-// => [16, 64] (iteration order is not guaranteed)
-
-let users = [
-  { user: 'barney' },
-  { user: 'fred' }
-]
-
-// The `property` iteratee shorthand.
-map(users, 'user')
-// => ['barney', 'fred']
-```
- * @param {Array|Object} arr The collection to iterate over.
- * @param {Iteratee|PropertyKey} fn The function invoked per iteration.
- * @returns Returns the new mapped array.
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map Array.map()}
- */
 export function map(arr, fn) {
+    const it = isFunction(fn) ? fn : (obj) => get(fn, obj);
     if (Array.isArray(arr)) {
-        return arr.map((x, i) => {
-            if (typeof fn === 'function')
-                return fn(x, i, arr);
-            return x?.[fn];
-        });
+        return arr.map((x, i) => it(x, i, arr));
     }
     if (isObject(arr)) {
-        return Object.keys(arr).map((key) => {
-            if (typeof fn === 'function')
-                return fn(arr[key], key, arr);
-            return get(fn, arr[key]);
-        });
+        return Object.keys(arr).map((key) => it(arr[key], key, arr));
     }
 }
-/**
- * Creates an object composed of the picked object properties.
- * @param {Object} obj The source object.
- * @param {Iteratee|PropertyKey[]} paths The properties to pick. If `paths` is a function, it will be invoked per property with two values `(value, key)`.
- * @returns A new object with the properties.
- * @example
-```js
-let object = { a: 1, b: '2', c: 3 }
-
-pick(object, ['a', 'c'])
-// => { a: 1, c: 3 }
-
-pick(object, (x) => isNumber(x))
-// => { a: 1, c: 3 }
-```
- *
- * @see {@link omit}
- */
 export function pick(obj, paths) {
     if (!obj)
         return {};
     const result = {};
-    if (typeof paths === 'function') {
+    if (isFunction(paths)) {
         for (const key of Object.keys(obj)) {
             if (paths(obj[key], key)) {
                 result[key] = obj[key];
@@ -418,28 +238,11 @@ export function pick(obj, paths) {
     }
     return result;
 }
-/**
- * The opposite of {@link pick} - this method creates an object composed of the own and inherited enumerable property paths of `object` that are not omitted.
- * @example
-```js
-let object = { 'a': 1, 'b': '2', 'c': 3 }
-
-omit(object, ['a', 'c'])
-// => { 'b': '2' }
-
-omit(object, (x) => isNumber(x))
-// => { 'b': '2' }
-```
- * @param {Object} obj The source object.
- * @param {Iteratee|PropertyKey[]} paths The property paths to omit.
- * @returns {Object} Returns the new object.
- * @see {@link pick}
- */
 export function omit(obj, paths) {
     if (!obj)
         return {};
     const result = {};
-    if (typeof paths === 'function') {
+    if (isFunction(paths)) {
         for (const key of Object.keys(obj)) {
             if (!paths(obj[key], key)) {
                 result[key] = obj[key];
@@ -453,61 +256,24 @@ export function omit(obj, paths) {
     }
     return result;
 }
-/**
- * This method is like {@link find} except that it returns the index of the first element `predicate` returns truthy for instead of the element itself.
- * @param {Array} obj The array to inspect.
- * @param {string|Object|Iteratee} fn The predicate function
- * @param {number} [start=0] The index to search from.
- * @returns {number} The index of the found value, else -1
- * @example
-```js
-let users = [
-  { 'user': 'barney',  'active': false },
-  { 'user': 'fred',    'active': false },
-  { 'user': 'pebbles', 'active': true }
-]
-
-index(users, (o) => o.user == 'barney')
-// => 0
-
-// The `shape` iteratee shorthand.
-index(users, { 'user': 'fred', 'active': false })
-// => 1
-
-// The `property` iteratee shorthand.
-index(users, 'active')
-// => 2
-```
- * @see {@link indexOf}
- * @see {@link lastIndex}
- *
- */
-export function index(obj, fn, start = 0) {
-    if (obj == null)
-        return;
+export function findIndex(obj, fn, start = 0) {
+    if (!obj)
+        return -1;
     const length = obj.length;
     if (length && start < 0) {
         start = Math.max(start + length, 0);
     }
     if (!length || start >= length)
         return -1;
-    if (isObject(fn)) {
-        fn = matches(fn);
-    }
+    const it = isFunction(fn) ? fn : isObject(fn) ? matches(fn) : (obj) => get(fn, obj);
     for (; start < length; start++) {
-        if (typeof fn === 'function') {
-            if (fn(obj[start], start, obj))
-                return start;
-        }
-        else {
-            if (obj[start]?.[fn])
-                return start;
-        }
+        if (it(obj[start], start, obj))
+            return start;
     }
     return -1;
 }
 /**
- * This method is like {@link index} except that it searches for a given value directly, instead of using a predicate function.
+ * This method is like {@link findIndex} except that it searches for a given value directly, instead of using a predicate function.
  * @param {Array} obj The array to inspect.
  * @param {*} value The value to find
  * @param {number} [start=0] The index to search from.
@@ -515,18 +281,18 @@ export function index(obj, fn, start = 0) {
  * @example
 ```js
 indexOf([1, 2, 1, 2], 2)
-// => 1
+// 1
 
 // Search from a `start` index.
 indexOf([1, 2, 1, 2], 2, 2)
-// => 3
+// 3
 ```
- * @see {@link index}
+ * @see {@link findIndex}
  * @see {@link lastIndexOf}
  */
 export function indexOf(obj, value, start = 0) {
-    if (obj == null)
-        return;
+    if (!obj)
+        return -1;
     const op = call(obj, 'indexOf', value, start);
     if (op != null)
         return op;
@@ -542,54 +308,18 @@ export function indexOf(obj, value, start = 0) {
     }
     return -1;
 }
-/**
- * This method is like {@link index} except that it iterates the collection from right to left.
- * @param {Array} obj The array to inspect.
- * @param {string|Iteratee|Object} fn The function invoked per iteration.
- * @param {number} [start] The index to search from.
- * @returns {number} The index of the found value, else -1
- * @example
-```js
-let users = [
-  { 'user': 'barney',  'active': true },
-  { 'user': 'fred',    'active': false },
-  { 'user': 'pebbles', 'active': false }
-]
-
-findLastIndex(users, (o) => o.user == 'pebbles')
-// => 2
-
-// The `shape` iteratee shorthand.
-findLastIndex(users, { 'user': 'barney', 'active': true })
-// => 0
-
-// The `property` iteratee shorthand.
-findLastIndex(users, 'active')
-// => 0
-```
- * @see {@link index}
- * @see {@link lastIndexOf}
- */
-export function lastIndex(obj, fn, start) {
-    if (obj == null)
-        return;
-    const length = obj.length;
+export function findLastIndex(arr, fn, start) {
+    if (arr == null)
+        return -1;
+    const length = arr.length;
     if (start == null)
         start = length - 1;
     if (!length || start < 0)
         return -1;
-    if (isObject(fn)) {
-        fn = matches(fn);
-    }
+    const it = isFunction(fn) ? fn : isObject(fn) ? matches(fn) : (obj) => get(fn, obj);
     for (; start >= 0; start--) {
-        if (typeof fn === 'function') {
-            if (fn(obj[start]))
-                return start;
-        }
-        else {
-            if (obj[start]?.[fn])
-                return start;
-        }
+        if (it(arr[start], start, arr))
+            return start;
     }
     return -1;
 }
@@ -602,18 +332,18 @@ export function lastIndex(obj, fn, start) {
  * @example
 ```js
 lastIndexOf([1, 2, 1, 2], 2)
-// => 3
+// 3
 
 // Search from the `fromIndex`.
 lastIndexOf([1, 2, 1, 2], 2, 2)
-// => 1
+// 1
 ```
- * @see {@link lastIndex}
+ * @see {@link findLastIndex}
  * @see {@link indexOf}
  */
 export function lastIndexOf(obj, value, start) {
     if (obj == null)
-        return;
+        return -1;
     const op = call(obj, 'lastIndexOf', value, start);
     if (op != null)
         return op;
@@ -628,14 +358,6 @@ export function lastIndexOf(obj, value, start) {
     }
     return -1;
 }
-/**
- * Creates a shallow clone of `value`. If `deep` is `true` it will clone it recursively.
- * @param {*} value
- * @param {boolean} [deep=false]
- * @return The clone value
- * @see {@link cloneArray}
- * @see {@link cloneTypedArray}
- */
 export function clone(value, deep = false) {
     if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
         return cloneTypedArray(value, deep);
@@ -679,46 +401,18 @@ export function cloneArray(arr, deep = false) {
  * @returns The new array
  * @see {@link clone}
  */
-export function cloneTypedArray(typedArray, isDeep) {
+export function cloneTypedArray(typedArray, isDeep = false) {
     const buffer = isDeep ? structuredClone(typedArray) : typedArray.buffer;
     return new typedArray.constructor(buffer, typedArray.byteOffset, typedArray.length);
 }
-/**
- * Creates a duplicate-free version of an array, using a `Set` for equality comparisons, in which only the first occurrence of each element is kept. The order of result values is not guaranteed.
- * @param arr The array containing duplicated elements
- * @param fn The iteratee invoked per element.
- * @returns Returns the new duplicate free array.
- * @example
-```js
-uniq([2, 1, 2])
-// => [2, 1]
-
-uniq([2.1, 1.2, 2.3], Math.floor)
-// => [2.1, 1.2]
-```
- *
- * @see {@link sortedUniq}
- */
 export function uniq(arr, fn = id) {
     const keys = new Set();
-    const mapper = typeof fn === 'function' ? fn : (x) => x?.[fn];
+    const it = isFunction(fn) ? fn : (x) => get(fn, x);
     for (const x of arr) {
-        keys.add(mapper(x));
+        keys.add(it(x));
     }
     return Array.from(keys.values());
 }
-/**
- * This method is like {@link uniq} except that it sorts the results in ascending order
- * @param arr The array containing duplicated elements
- * @param fn The iteratee invoked per element.
- * @returns Returns the new duplicate free array
- * @example
-```js
-uniq([2, 1, 2])
-// => [1, 2]
-```
- * @see {@link uniq}
- */
 export function sortedUniq(arr, fn = id) {
     const values = uniq(arr, fn);
     values.sort(compare);
@@ -804,7 +498,7 @@ let other = {
 }
 
 merge(object, other)
-// => { 'a': [{ 'b': 2, 'c': 3 }, { 'd': 4, 'e': 5 }] }
+// { 'a': [{ 'b': 2, 'c': 3 }, { 'd': 4, 'e': 5 }] }
 ```
  */
 export function merge(object, ...sources) {
@@ -823,7 +517,7 @@ export function merge(object, ...sources) {
  * @example
 ```js
 defaults({ 'a': 1 }, { 'b': 2 }, { 'a': 3 })
-// => { 'a': 1, 'b': 2 }
+// { 'a': 1, 'b': 2 }
 ```
  */
 export function defaults(object, ...sources) {
@@ -842,7 +536,7 @@ export function defaults(object, ...sources) {
  * @example
 ```js
 [...difference([2, 1], [2, 3])]
-// => [1]
+// [1]
 ```
  * @see {@link union}
  * @see {@link intersection}
@@ -866,7 +560,7 @@ export function* difference(...args) {
  * @example
 ```js
 [...intersection([2, 1], [2, 3])]
-// => [2]
+// [2]
 ```
 * @see {@link difference}
  * @see {@link union}
@@ -893,7 +587,7 @@ export function* intersection(...args) {
  * @example
 ```js
 [...union([2], [1, 2])]
-// => [2, 1]
+// [2, 1]
 ```
  * @see {@link difference}
  * @see {@link intersection}
@@ -909,26 +603,9 @@ export function* union(...args) {
         yield item;
     }
 }
-/**
- * Creates an object composed of keys generated from the results of running each element of `arr` thru `func`. The order of grouped values is determined by the order they occur in `arr`. The corresponding value of each key is an array of elements responsible for generating the key.
- *
- * @param arr The collection to iterate over.
- * @param [func=id] The iteratee to transform keys.
- * @returns Returns the aggregated object.
- *
- * @example
-```js
-groupBy([6.1, 4.2, 6.3], Math.floor)
-// => { '4': [4.2], '6': [6.1, 6.3] }
-
-// The `property` iteratee shorthand.
-groupBy(['one', 'two', 'three'], 'length')
-// => { '3': ['one', 'two'], '5': ['three'] }
-```
- */
 export function groupBy(arr, func = id) {
+    const useKey = isFunction(func) ? func : (obj) => get(func, obj);
     const results = {};
-    const useKey = typeof func === 'function' ? func : partial(get, func);
     forEach(arr, (value) => {
         const groupKey = useKey(value);
         const values = results[groupKey] || [];
@@ -937,27 +614,9 @@ export function groupBy(arr, func = id) {
     });
     return results;
 }
-/**
- * Similar to {@link groupBy} but it returns a {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map Map} object with the results.
- *
- * @param arr The collection to iterate over.
- * @param {Function | PropertyKey} [func=id] The iteratee to transform keys.
- * @returns {Map} Returns the aggregated map object.
- * @template K, V
- *
- * @example
-```js
-groupByMap([6.1, 4.2, 6.3], Math.floor)
-// => Map { 4: [4.2], 6: [6.1, 6.3] }
-
-// The `property` iteratee shorthand.
-groupByMap(['one', 'two', 'three'], 'length')
-// => Map { 3: ['one', 'two'], 5: ['three'] }
-```
- */
 export function groupByMap(arr, func = id) {
     const results = new Map();
-    const useKey = typeof func === 'function' ? func : partial(get, func);
+    const useKey = isFunction(func) ? func : (obj) => get(func, obj);
     forEach(arr, (value) => {
         const groupKey = useKey(value);
         const values = results.get(groupKey) || [];
@@ -966,20 +625,104 @@ export function groupByMap(arr, func = id) {
     });
     return results;
 }
+export function remove(arr, func) {
+    const it = isFunction(func) ? func : isArray(func) ? (x) => func.includes(x) : (x) => func === x;
+    return arr.filter((x, i) => !it(x, i, arr));
+}
 /**
- * Removes all elements from array that `func` returns truthy for and returns an array of the removed elements.
- * @param arr The array to remove from.
- * @param func The function invoked per iteration or value(s) or value to remove.
- * @returns
+ * Returns the index of `x` in a **sorted** array if found, in `O(log n)` using binary search.
+ * If the element is not found, returns a negative integer.
+ * @param arr The array to sort
+ * @param x The element to find
+ * @param lo The starting index
+ * @param hi The end index to search within
+ * @param comp The compare function to check for `x`
+ * @returns {number} The index if the element is found or a negative integer.
  */
-export function remove(arr, func) {
-    return arr.filter((x, i) => {
-        if (isArray(func))
-            return !func.includes(x);
-        else if (isFunction(func))
-            return !func(x, i, arr);
-        return x !== func;
-    });
+export function binarySearch(arr, x, lo = 0, hi, comp = compare) {
+    hi = hi ?? arr.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        const check = comp(x, arr[mid]);
+        if (check === 0)
+            return mid;
+        if (check > 0)
+            lo = mid + 1;
+        else
+            hi = mid - 1;
+    }
+    if (comp(x, arr[lo]) === 0)
+        return lo;
+    // Returns (-lo - 1) where n is the insertion point for new element in the range
+    return -lo - 1;
+}
+/**
+ * Returns an insertion index which comes after any existing entries of `x` in a **sorted** array, using binary search.
+ * @param arr The array to sort
+ * @param x The element to find
+ * @param lo The starting index
+ * @param hi The end index to search within
+ * @param comp The compare function to check for `x`
+ * @returns {number}
+ */
+export function bisect(arr, x, lo = 0, hi, comp = compare) {
+    hi = hi ?? arr.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        const check = comp(x, arr[mid]);
+        if (check >= 0)
+            lo = mid + 1;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}
+/**
+ * Returns an insertion index which comes before any existing entries of `x` in a **sorted** array, using binary search.
+ * @param arr The array to sort
+ * @param x The element to find
+ * @param lo The starting index
+ * @param hi The end index to search within
+ * @param comp The compare function to check for `x`
+ * @returns {number}
+ */
+export function bisectLeft(arr, x, lo = 0, hi, comp = compare) {
+    hi = hi ?? arr.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        const check = comp(x, arr[mid]);
+        if (check <= 0)
+            hi = mid - 1;
+        else
+            lo = mid + 1;
+    }
+    return lo;
+}
+/**
+ * Runs {@link bisect} first to locate an insertion point, and inserts the value `x` in the sorted array after any existing entries of `x` to maintain sort order.
+ * Please note this method is `O(n)` because insertion resizes the array.
+ * @param arr The array to insert into
+ * @param x The element to insert
+ * @param lo The starting index
+ * @param hi The end index to search within
+ * @param comp The compare function to check for `x`
+ * @returns {Array}
+ */
+export function insort(arr, x, lo = 0, hi, comp = compare) {
+    const index = bisect(arr, x, lo, hi, comp);
+    return insert(arr, index, x);
+}
+/**
+ * Runs {@link bisectLeft} first to locate an insertion point, and inserts the value `x` in the sorted array before any existing entries of `x` to maintain sort order.
+ * Please note this method is `O(n)` because insertion resizes the array.
+ * @param arr The array to insert into
+ * @param x The element to insert
+ * @param lo The starting index
+ * @param hi The end index to search within
+ * @param comp The compare function to check for `x`
+ * @returns {Array}
+ */
+export function insortLeft(arr, x, lo = 0, hi, comp = compare) {
+    const index = bisectLeft(arr, x, lo, hi, comp);
+    return insert(arr, index, x);
 }
-// TODO: binary search utils
-// TODO: Counter