nano-binary-search 1.0.10 → 1.0.11

package/README.md

@@ -9,10 +9,38 @@ because it is done right and fits JavaScript — it is ripe for code reuse.
 
 For TypeScript users the typings are included.
 
+This is equivalent to C++ `std::lower_bound` / Python `bisect.bisect_left`.
+
+## Quick reference
+
+```js
+import binarySearch from 'nano-binary-search';
+
+// Lower bound (first element >= value):
+binarySearch([1, 2, 4, 5], x => x < 3);   // → 2
+
+// Upper bound (first element > value):
+binarySearch([1, 2, 4, 5], x => x <= 2);   // → 2
+
+// Insert keeping sorted order:
+const idx = binarySearch(sortedArray, x => x < value);
+sortedArray.splice(idx, 0, value);
+
+// Remove all elements equal to value:
+const lo = binarySearch(sortedArray, x => x < value);
+const hi = binarySearch(sortedArray, x => x <= value, lo);
+sortedArray.splice(lo, hi - lo);
+
+// Edge cases — just work:
+binarySearch([], x => x < 5);              // → 0 (empty array)
+binarySearch([1, 2, 3], x => x < 1);       // → 0 (before all)
+binarySearch([1, 2, 3], x => x < 4);       // → 3 (after all)
+```
+
 ## Why?
 
 Why do I think it is done right? Because it supports important invariants with
-[splice()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice).
+[splice()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice).
 
 ### No need to worry about inserting values
 
@@ -70,7 +98,7 @@ const index: number = binarySearch<T>(
   lessFn: (value: T, index: number, array: readonly T[]) => boolean,
   l: number = 0,
   r: number = sortedArray.length
-): boolean;
+): number;
 ```
 
 - Inputs:
@@ -85,8 +113,8 @@ const index: number = binarySearch<T>(
 
 The function return an index, where we can safely insert the searched value with `splice()`:
 
-- if we used `<` operator as the comparison function, the index will point to the first value that is greater or equal than the searched value.
-- if we used `<=` operator as the comparison function, the index will point to the first value that is greater than the searched value.
+- if we used `<` operator as the comparison function, the index will point to the first value that is greater or equal than the searched value (**lower bound**, like C++ `std::lower_bound` or Python `bisect_left`).
+- if we used `<=` operator as the comparison function, the index will point to the first value that is greater than the searched value (**upper bound**, like C++ `std::upper_bound` or Python `bisect_right`).
 
 That's all Folks!
 
@@ -144,6 +172,7 @@ This project is licensed under the BSD-3-Clause license.
 
 ## Release history
 
+- 1.0.11 _Technical release: more tests to increase coverage, more AI-friendly changes_
 - 1.0.10 _Updated dev deps_
 - 1.0.9 _Updated dev deps_
 - 1.0.8 _Updated dev deps_

package/index.js

@@ -2,6 +2,20 @@
 
 'use strict';
 
+/**
+ * Binary search (lower bound). Equivalent to C++ `std::lower_bound` / Python `bisect.bisect_left`.
+ *
+ * Returns an insertion index compatible with `Array.prototype.splice()`.
+ * - With `<`: returns the index of the first element ≥ pivot (lower bound).
+ * - With `<=`: returns the index of the first element > pivot (upper bound).
+ *
+ * @template T
+ * @param {readonly T[]} sortedArray - sorted array of values.
+ * @param {(value: T, index: number, array: readonly T[]) => boolean} lessFn - returns true if value < pivot.
+ * @param {number} [l=0] - left index (inclusive).
+ * @param {number} [r=sortedArray.length] - right index (exclusive).
+ * @returns {number} insertion index.
+ */
 export const binarySearch = (sortedArray, lessFn, l = 0, r = sortedArray.length) => {
   while (l < r) {
     const m = l + Math.floor((r - l) / 2);

package/llms.txt

@@ -0,0 +1,55 @@
+# nano-binary-search
+
+> Binary search for JavaScript done right. Zero dependencies, single file.
+> Equivalent to C++ `std::lower_bound` / Python `bisect.bisect_left`.
+
+## Install
+
+```
+npm install nano-binary-search
+```
+
+## Usage
+
+```js
+import binarySearch from 'nano-binary-search';
+
+// Find insertion point (lower bound): index of first element >= value
+const index = binarySearch(sortedArray, x => x < value);
+sortedArray.splice(index, 0, value); // insert keeping sorted order
+
+// Find upper bound: index of first element > value
+const upper = binarySearch(sortedArray, x => x <= value);
+
+// Find and remove all elements equal to value
+const lo = binarySearch(sortedArray, x => x < value);
+const hi = binarySearch(sortedArray, x => x <= value, lo);
+sortedArray.splice(lo, hi - lo);
+```
+
+## API
+
+`binarySearch(sortedArray, lessFn, l?, r?)` → `number`
+
+- `sortedArray` — sorted array of values of type `T`.
+- `lessFn(value: T, index: number, array: readonly T[])` — returns `true` if `value` is less than the pivot. The comparison function.
+- `l` — left index, inclusive. Defaults to `0`.
+- `r` — right index, exclusive. Defaults to `sortedArray.length`.
+- Returns: insertion index compatible with `Array.prototype.splice()`.
+
+## Key properties
+
+- With `<` in lessFn: returns index of first element ≥ pivot (**lower bound**).
+- With `<=` in lessFn: returns index of first element > pivot (**upper bound**).
+- Works correctly with empty arrays, sub-ranges, duplicate values, and custom comparators.
+- The result is always a valid `splice()` index — no off-by-one errors.
+
+## Examples with results
+
+```js
+binarySearch([1, 2, 4, 5], x => x < 3)   // → 2 (insert 3 at index 2)
+binarySearch([1, 2, 4, 5], x => x <= 2)   // → 2 (upper bound of 2)
+binarySearch([], x => x < 5)              // → 0 (empty array)
+binarySearch([1, 2, 3], x => x < 1)       // → 0 (before all)
+binarySearch([1, 2, 3], x => x < 4)       // → 3 (after all)
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nano-binary-search",
   "description": "Binary search for JavaScript done right.",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -40,14 +40,24 @@
   "homepage": "https://github.com/uhop/nano-binary-search#readme",
   "keywords": [
     "binary search",
-    "algorithm"
+    "algorithm",
+    "sorted array",
+    "insertion point",
+    "lower bound",
+    "upper bound",
+    "bisect",
+    "search",
+    "splice",
+    "zero dependencies",
+    "lightweight"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
   "license": "BSD-3-Clause",
   "files": [
     "index.*",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "llms.txt"
   ],
   "tape6": {
     "tests": [
@@ -61,8 +71,8 @@
     }
   },
   "devDependencies": {
-    "tape-six": "^1.7.0",
-    "tape-six-proc": "^1.2.2",
+    "tape-six": "^1.7.2",
+    "tape-six-proc": "^1.2.3",
     "typescript": "^5.9.3"
   }
 }