# dichotomid

> Dichotomid helps you find the first free id of something, efficiently.

Latest version **1.0.0** (published 2025-03-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install dichotomid
pnpm add dichotomid
yarn add dichotomid
bun add dichotomid
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2025-03-15 |
| First published | 2022-08-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 4.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Gautier Ben Aïm <https://github.com/GauBen> |
| Maintainers | gauben |
| Keywords | binary search, first available, first free, optimized |

## Links

- npm: https://www.npmjs.com/package/dichotomid
- Repository: https://github.com/GauBen/packages
- Homepage: https://github.com/GauBen/packages/tree/main/packages/dichotomid
- Issues: https://github.com/GauBen/packages/issues
- npm.io page: https://npm.io/package/dichotomid

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2025-03-15
- 0.0.3 — 2022-08-11
- 0.0.2 — 2022-08-10
- 0.0.1 — 2022-08-10

## README

# dichotomid

**Dichotomid helps you find the first free id of something, efficiently.**

Imagine you have a directory with files named `file1`, `file2`, `file3`, ... and you want to find the first free `fileN`:

```js
// 🐌 Naive implementation, do not do this 🐌
let i = 1;
while (fs.existsSync(`file${i}`)) {
  i++;
}
console.log(`file${i} is the first free`);
```

This implementation works, but **can be mathematically optimized**, and that's what dichotomid is for:

```js
// 🐎 Optimized implementation 🐎
import { dichotomid } from "dichotomid";
let i = dichotomid((i) => fs.existsSync(`file${i}`));
console.log(`file${i} is the first free`);
```

Dichotomid relies on binary search to find the first free id in the least amount of tests. Indeed, if `file1` to `file999` are all taken, it would take 1000 `existsSync` calls to figure it out naively. **Dichotomid will find the value in 30 call.**

```js
import { dichotomid } from "dichotomid";

let op = 0;
let validator = (n) => {
  op++;
  return n >= 1000; // The first free id is 1000
};

let id = dichotomid(validator);
console.log(op); // 30
```

## Usage

Three functions are made available: `dichotomid` (default export), `dichotomidSync` and `dichotomidAsync`.

`dichotomid` works for both synchronous and asynchronous validators. It returns a `number` if the validator is synchronous, or a `Promise<number>` if the validator is asynchronous.

## Notes

- `dichotomid` has a fail safe if the value offered to the validator exceeds `MAX_SAFE_INTEGER`.
- The library has 100% test coverage.
- Ids are expected to be contiguous. If they are not, the algorithm you want is the naive loop at the top.

---
_Source: https://npm.io/package/dichotomid · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._