{"id":15547278,"url":"https://github.com/uhop/nano-binary-search","last_synced_at":"2026-02-06T01:43:36.174Z","repository":{"id":253473060,"uuid":"842791029","full_name":"uhop/nano-binary-search","owner":"uhop","description":"Binary search for JavaScript done right.","archived":false,"fork":false,"pushed_at":"2024-11-25T14:19:09.000Z","size":36,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-21T06:09:27.791Z","etag":null,"topics":["algorithm","binary-search"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uhop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"uhop","buy_me_a_coffee":"uhop"}},"created_at":"2024-08-15T04:58:55.000Z","updated_at":"2025-01-21T13:51:16.000Z","dependencies_parsed_at":"2025-03-06T08:43:42.812Z","dependency_job_id":null,"html_url":"https://github.com/uhop/nano-binary-search","commit_stats":{"total_commits":17,"total_committers":1,"mean_commits":17.0,"dds":0.0,"last_synced_commit":"2a379bb6b6f050f60f6ac14c15caa54c7fe6c6c3"},"previous_names":["uhop/nano-binary-search"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fnano-binary-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fnano-binary-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fnano-binary-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fnano-binary-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uhop","download_url":"https://codeload.github.com/uhop/nano-binary-search/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250488342,"owners_count":21438764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","binary-search"],"created_at":"2024-10-02T13:08:30.574Z","updated_at":"2026-02-06T01:43:36.166Z","avatar_url":"https://github.com/uhop.png","language":"JavaScript","readme":"# nano-binary-search [![NPM version][npm-img]][npm-url]\n\n[npm-img]: https://img.shields.io/npm/v/nano-binary-search.svg\n[npm-url]: https://npmjs.org/package/nano-binary-search\n\nThis is a nano binary search implementation. It is a tiny single file with no dependencies.\nThe only reason I wrote it because I wrote it countless times before, I think it is perfect now\nbecause it is done right and fits JavaScript \u0026mdash; it is ripe for code reuse.\n\nFor TypeScript users the typings are included.\n\n## Why?\n\nWhy do I think it is done right? Because it supports important invariants with\n[splice()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice).\n\n### No need to worry about inserting values\n\n```js\nimport binarySearch from 'nano-binary-search';\n\nconst sortedArray = [];\n\nfor (let i = 0; i \u003c 100; ++i) {\n  const value = Math.floor(Math.random() * 1000);\n\n  // THIS IS THE IMPORTANT INVARIANT:\n  // - works with `splice()` seamlessly to add values\n  const index = binarySearch(sortedArray, x =\u003e x \u003c value);\n  sortedArray.splice(index, 0, value);\n  // `sortedArray` is always sorted\n}\n```\n\nWhat if the array is empty? That's fine. What if the value is outside the range of the array?\nThat's fine too.\n\n### No need to worry about removing values\n\n```js\nimport binarySearch from 'nano-binary-search';\n\nconst sortedArray = [1, 3, 3, 4];\n\n// THIS IS THE IMPORTANT INVARIANT:\n// - works with `splice()` seamlessly to remove equal values\nconst lowerIndex = binarySearch(sortedArray, x =\u003e x \u003c 3),\n  upperIndex = binarySearch(sortedArray, x =\u003e x \u003c= 3, lowerIndex);\nsortedArray.splice(lowerIndex, upperIndex - lowerIndex);\n// again, `sortedArray` is always sorted\n```\n\nWhat if there is no such value in the array? That's fine. It still works.\n\n### API that makes sense\n\nThere is no need to pass in a function and a comparison value every time.\nIn the modern JavaScript/TypeScript, it is easier to get the comparison value straight from the closure\nlike in the examples.\n\nDo you want to search a sub-array? Just pass in indices.\n\n## API\n\nThe TypeScript-like API is as follows:\n\n```ts\nconst index: number = binarySearch\u003cT\u003e(\n  sortedArray: readonly T[],\n  lessFn: (value: T, index: number, array: readonly T[]) =\u003e boolean,\n  l: number = 0,\n  r: number = sortedArray.length\n): boolean;\n```\n\n- Inputs:\n  - `sortedArray` \u0026mdash; sorted array of some values. We don't care about values in this array.\n    It is up to `lessFn` to compare them. The array should be sorted in a compatible way with `lessFn`.\n  - `lessFn` \u0026mdash; function that takes three argument and returns a truthy value if the first argument\n    (a value from array) is less than our value, whatever it is. The second value is its index,\n    and the third is the `sortedArray`.\n    - The function interface is modeled on the callback function of array methods.\n  - `l` \u0026mdash; left index. This index is inclusive. Defaults to 0.\n  - `r` \u0026mdash; right index. This index is exclusive. Defaults to `sortedArray.length`.\n\nThe function return an index, where we can safely insert the searched value with `splice()`:\n\n- if we used `\u003c` operator as the comparison function, the index will point to the first value that is greater or equal than the searched value.\n- if we used `\u003c=` operator as the comparison function, the index will point to the first value that is greater than the searched value.\n\nThat's all Folks!\n\n## Q \u0026 A\n\n**Is it fast?**\n\nYes.\n\nThe only reasonable way to make it faster is to take its code and inline `lessFn()`. The other idea is\nto inline `binarySearch()` itself in your code. That's about all.\n\n**What if I want to take into account the index of the searched value?**\n\nThat's why `lessFn(value, index, array)` has extra arguments.\n\n**What if the array uses a custom comparator for sorting, while this binary search uses a `less` function?**\n\nSimple:\n\n```js\nlet compareFn; // some complex function defined elsewhere\nsortedArray.sort(compareFn);\n\nlet value; // some search value defined elsewhere\n\nconst lessFn = x =\u003e compareFn(x, value) \u003c 0,\n  index = binarySearch(sortedArray, lessFn);\n```\n\n**Why doesn't it use a comparator function for searching?**\n\nWe don't need to compare values in the array for equality. A simple `less` function is enough.\nIn many cases it is easier to implement just a `less` function.\n\nFor example (two argument version for simplicity):\n\n```js\nconst stringLessFn = (a, b) =\u003e a \u003c b;\n\n// comparator #1 (two comparisons)\nconst stringCompareFn1 = (a, b) =\u003e (a \u003c b ? -1 : a \u003e b ? 1 : 0);\n\n// comparator #2: smarter (a method call)\nconst stringCompareFn2 = (a, b) =\u003e a.localeCompare(b);\n```\n\n**I still have questions!**\n\nLook at the code of `index.js` and `tests/` for more details. Go to the GitHub repository and ask.\n\n## License\n\nThis project is licensed under the BSD-3-Clause license.\n\n## Release history\n\n- 1.0.9 _Updated dev deps_\n- 1.0.8 _Updated dev deps_\n- 1.0.7 _Updated dev deps_\n- 1.0.6 _Updated dev deps_\n- 1.0.5 _Updated dev deps_\n- 1.0.4 _Updated dev deps_\n- 1.0.3 _Added a reference to the TS types_\n- 1.0.2 _Improved docs_\n- 1.0.1 _Added TS typings_\n- 1.0.0 _Initial release_\n","funding_links":["https://github.com/sponsors/uhop","https://buymeacoffee.com/uhop"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuhop%2Fnano-binary-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuhop%2Fnano-binary-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuhop%2Fnano-binary-search/lists"}