{"id":19050526,"url":"https://github.com/blakek/js-sorted-array","last_synced_at":"2026-06-29T14:32:17.415Z","repository":{"id":77618517,"uuid":"320462472","full_name":"blakek/js-sorted-array","owner":"blakek","description":"🔢 more efficient array functions for sorted arrays (e.g. binary search)","archived":false,"fork":false,"pushed_at":"2020-12-11T19:11:39.000Z","size":88,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-12T14:24:15.074Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blakek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2020-12-11T04:01:07.000Z","updated_at":"2020-12-11T19:11:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"d9d88ce6-a05d-4475-8da4-ea3d0eb84f2b","html_url":"https://github.com/blakek/js-sorted-array","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/blakek/js-sorted-array","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fjs-sorted-array","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fjs-sorted-array/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fjs-sorted-array/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fjs-sorted-array/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blakek","download_url":"https://codeload.github.com/blakek/js-sorted-array/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fjs-sorted-array/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34931587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-08T23:15:13.696Z","updated_at":"2026-06-29T14:32:17.388Z","avatar_url":"https://github.com/blakek.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @blakek/sorted-array\n\n\u003e 🔢 more efficient array functions for sorted arrays (e.g. binary search)\n\nIf you enjoy JavaScript, you probably like the [Array functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array). This just some more efficient helpers if the array is guaranteed to be sorted.\n\n## Install\n\nUsing [Yarn]:\n\n```bash\n$ yarn add @blakek/sorted-array\n```\n\n…or using [npm]:\n\n```bash\n$ npm i --save @blakek/sorted-array\n```\n\n## API\n\n```js\nimport {\n  binarySearch,\n  indexOf,\n  includes,\n  insert,\n  remove\n} from '@blakek/sorted-array';\n```\n\n## API\n\n### `binarySearch`\n\n```ts\nfunction binarySearch\u003cT\u003e(\n  array: T[],\n  item: T,\n  comparatorFn?: Comparator\u003cT | number\u003e\n): BinarySearchResult;\n```\n\nThis is used to implement most of the other functionality.\n\n- `array` - an array of any type to search\n- `item` - the item to value to search for\n- `comparatorFn` - a function that indicates which value is greater or if two values are equal. It's a similar to [Array.sort()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).\n\nIt returns a `BinarySearchResult`, which is a tuple:\n\n```ts\ntype BinarySearchResult = [found: boolean, finalIndex: number];\n```\n\n- `found` - if the value was found (the `comparatorFn` returned `0` for two values)\n- `finalIndex` - If found, is the index of the found value. If not, this is the index where the item would be inserted.\n\n### `type Comparator`\n\n```ts\ntype Comparator\u003cT\u003e = (a: T, b: T) =\u003e number;\n```\n\nThis is not exported, but is the type for the `comparatorFn` argument used.\n\n### `indexOf`\n\n```ts\nfunction indexOf\u003cT\u003e(\n  array: T[],\n  item: T,\n  comparatorFn?: Comparator\u003cT | number\u003e\n): number;\n```\n\nReturns the index of a matching value.\n\nExample:\n\n```js\nimport { indexOf } from '@blakek/sorted-array';\n\nindexOf([1, 5, 7, 9, 10], 1); //» 0\nindexOf([1, 5, 7, 9, 10], 9); //» 3\nindexOf([1, 5, 7, 9, 10], 2); //» -1\n\n// Custom comparator function\nindexOf(\n  [{ value: 1 }, { value: 3 }],\n  { value: 3 },\n  (a, b) =\u003e a.value - b.value\n); //» 1\n```\n\n### `includes`\n\n```ts\nfunction includes\u003cT\u003e(\n  array: T[],\n  item: T,\n  comparatorFn?: Comparator\u003cT | number\u003e\n): boolean;\n```\n\nReturns if an array includes a matching value.\n\nExample:\n\n```js\nimport { includes } from '@blakek/sorted-array';\n\nincludes([1, 5, 7, 9, 10], 1); //» true\nincludes([1, 5, 7, 9, 10], 9); //» true\nincludes([1, 5, 7, 9, 10], 2); //» false\n\n// Custom comparator function\nincludes(\n  [{ value: 1 }, { value: 3 }],\n  { value: 3 },\n  (a, b) =\u003e a.value - b.value\n); //» true\n```\n\n### `insert`\n\n```ts\nfunction insert\u003cT\u003e(\n  array: T[],\n  item: T,\n  comparatorFn?: Comparator\u003cT | number\u003e\n): T[];\n```\n\nAdds an element to the sorted array. Note, this mutates the array.\n\nExample:\n\n```js\nimport { insert } from '@blakek/sorted-array';\n\nconst array = [];\ninsert(array, 3); //» [ 3 ]\ninsert(array, 10); //» [ 3, 10 ]\ninsert(array, 1); //» [ 1, 3, 10 ]\n\n// Custom comparator function\nfunction comparator(a, b) {\n  if (a.username \u003e b.username) return 1;\n  if (a.username \u003c b.username) return -1;\n  return a.lastSeen - b.lastSeen;\n}\n\nconst seenTimes = [{ username: 'blakek', lastSeen: 1607658574048 }];\n\ninsert(seenTimes, { username: 'adash', lastSeen: 1607658574000 }, comparator);\n//» [\n//»   { username: 'adash', lastSeen: 1607658574000 },\n//»   { username: 'blakek', lastSeen: 1607658574048 }\n//» ]\n```\n\n### `remove`\n\n```ts\nfunction remove\u003cT\u003e(\n  array: T[],\n  item: T,\n  comparatorFn?: Comparator\u003cT | number\u003e\n): T[];\n```\n\nRemoves an element to the sorted array. Note, this mutates the array.\n\nExample:\n\n```js\nimport { remove } from '@blakek/sorted-array';\n\nconst array = [1, 3, 10];\nremove(array, 3); //» [ 1, 10 ]\nremove(array, 10); //» [ 1 ]\nremove(array, 1); //» []\n\n// Custom comparator function\nfunction comparator(a, b) {\n  if (a.username \u003e b.username) return 1;\n  if (a.username \u003c b.username) return -1;\n  return a.lastSeen - b.lastSeen;\n}\n\nconst seenTimes = [\n  { username: 'adash', lastSeen: 1607658574000 },\n  { username: 'blakek', lastSeen: 1607658574048 }\n];\n\nremove(seenTimes, { username: 'adash' }, comparator);\n//» [ { username: 'blakek', lastSeen: 1607658574048 } ]\n```\n\n## Contributing\n\n[Node.js] and [Yarn] are required to work with this project.\n\nTo install all dependencies, run:\n\n```bash\nyarn\n```\n\n### Useful Commands\n\n|                     |                                                 |\n| ------------------- | ----------------------------------------------- |\n| `yarn build`        | Builds the project to `./dist`                  |\n| `yarn format`       | Format the source following the Prettier styles |\n| `yarn test`         | Run project tests                               |\n| `yarn test --watch` | Run project tests, watching for file changes    |\n\n## License\n\nMIT\n\n[node.js]: https://nodejs.org/\n[npm]: https://npmjs.com/\n[yarn]: https://yarnpkg.com/en/docs/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblakek%2Fjs-sorted-array","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblakek%2Fjs-sorted-array","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblakek%2Fjs-sorted-array/lists"}