nano-binary-search 1.0.0 → 1.0.2

package/README.md

@@ -7,6 +7,8 @@ This is a nano binary search implementation. It is a tiny single file with no de
 The only reason I wrote it because I wrote it countless times before, I think it is perfect now
 because it is done right and fits JavaScript — it is ripe for code reuse.
 
+For TypeScript users the typings are included.
+
 ## Why?
 
 Why do I think it is done right? Because it supports important invariants with
@@ -60,7 +62,16 @@ Do you want to search a sub-array? Just pass in indices.
 
 ## API
 
-`binarySearch(sortedArray, lessFn, l = 0, r = sortedArray.length)`:
+The TypeScript-like API is as follows:
+
+```ts
+const index: number = binarySearch<T>(
+  sortedArray: readonly T[],
+  lessFn: (value: T, index: number, array: readonly T[]) => boolean,
+  l: number = 0,
+  r: number = sortedArray.length
+): boolean;
+```
 
 * Inputs:
   * `sortedArray` &mdash; sorted array of some values. We don't care about values in this array.
@@ -68,15 +79,14 @@ Do you want to search a sub-array? Just pass in indices.
   * `lessFn` &mdash; function that takes three argument and returns a truthy value if the first argument
     (a value from array) is less than our value, whatever it is. The second value is its index,
     and the third is the `sortedArray`.
-    * The function interface is modeled on callback function of array methods.
-    * The signature: `lessFn(value, index, array) => boolean`.
+    * The function interface is modeled on the callback function of array methods.
   * `l` &mdash; left index. This index is inclusive. Defaults to 0.
   * `r` &mdash; right index. This index is exclusive. Defaults to `sortedArray.length`.
 
 The function return an index, where we can safely insert the searched value with `splice()`:
 
-* if we used `<` operator, the index will point to the first value that is greater or equal than the searched value.
-* if we used `<=` operator, 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.
+* if we used `<=` operator as the comparison function, the index will point to the first value that is greater than the searched value.
 
 That's all Folks!
 
@@ -134,4 +144,6 @@ This project is licensed under the BSD-3-Clause license.
 
 ## Release history
 
+- 1.0.2 *Improved docs*
+- 1.0.1 *Added TS typings*
 - 1.0.0 *Initial release*

package/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Comparison function type. It compares a value with some internal pivot value and returns a boolean.
+ * Additional arguments are `index` (the pivot index) and `sortedArray`.
+ */
+type LessFn<T = any> = (value: T, index: number, sortedArray: readonly T[]) => boolean;
+
+/**
+ * Binary search (see [docs](https://github.com/uhop/nano-binary-search#readme)):
+ * `binarySearch([1, 2, 3], x => x < 3)`
+ *
+ * @param sortedArray sorted array. It should be sorted in a compatible way with the comparison function.
+ * @param lessFn comparison function that takes a value, compares it with the pivot value, and returns a boolean. See {@link LessFn}.
+ * @param l left index. Defaults to 0.
+ * @param r right index. Defaults to `sortedArray.length`.
+ * @returns index where the pivot value can be inserted without breaking the sorted-ness of the array.
+ */
+export declare function binarySearch<T>(sortedArray: readonly T[], lessFn: LessFn<T>, l?: number, r?: number): number;
+
+export default binarySearch;

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "nano-binary-search",
   "description": "Binary search for JavaScript done right.",
-  "version": "1.0.0",
-  "main": "index.js",
+  "version": "1.0.2",
   "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
   "scripts": {
-    "test": "tape6 --flags FO"
+    "test": "tape6 --flags FO",
+    "ts-check": "tsc --noEmit"
   },
   "repository": {
     "type": "git",
@@ -26,7 +34,7 @@
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
   "license": "BSD-3-Clause",
   "files": [
-    "index.js",
+    "index.*",
     "LICENSE",
     "README.md"
   ],
@@ -36,6 +44,7 @@
     ]
   },
   "devDependencies": {
-    "tape-six": "^0.9.6"
+    "tape-six": "^0.9.6",
+    "typescript": "^5.5.4"
   }
 }