# get-unused-path

> Reliably get an unused path you can write to.

Latest version **2.0.3** (published 2025-10-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install get-unused-path
pnpm add get-unused-path
yarn add get-unused-path
bun add get-unused-path
```

## Health

**Score 60/100 (C)** — status: stable.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.3 |
| Published | 2025-10-26 |
| First published | 2019-10-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 6.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | fabiospampinato |
| Keywords | get, unused, path |

## Links

- npm: https://www.npmjs.com/package/get-unused-path
- Repository: https://github.com/fabiospampinato/get-unused-path
- Homepage: https://github.com/fabiospampinato/get-unused-path#readme
- Issues: https://github.com/fabiospampinato/get-unused-path/issues
- npm.io page: https://npm.io/package/get-unused-path

## Dependencies (1)

- [sanitize-basename](https://npm.io/package/sanitize-basename.md) ^2.0.2

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 2.0.3 (latest) — 2025-10-26
- 2.0.2 — 2025-10-26
- 2.0.1 — 2024-04-04
- 2.0.0 — 2022-11-07
- 1.4.2 — 2020-12-06
- 1.4.1 — 2020-11-25
- 1.4.0 — 2020-01-21
- 1.3.0 — 2020-01-14
- 1.2.0 — 2020-01-14
- 1.1.0 — 2019-10-10
- 1.0.0 — 2019-10-09

## README

# Get Unused Path

Reliably get an unused path you can write to.

## Features

- It attempts to find an unused file path (e.g. `/x/foo.txt`), incrementing the file name until an unused file path is found (e.g. `/x/foo (2).txt`).
- It's roboust against race conditions since it returns a "disposer" alongside each file path returned, until you call it the same file path won't be returned again.
- It throws after a configurable amount of attempts, avoiding any potential endless loops.
- The incrementer function is configurable.

## Install

```sh
npm install get-unused-path
```

## Usage

The following interface is provided:

```ts
type Disposer = () => void;

type Incrementer = ( name: string, ext: string, attempt: number ) => string;

type Options = {
  fileName: string, // Initial file name
  folderPath?: string, // Folder path where to look for unused path
  incrementer?: Incrementer, // Function that increments the file name during each attempt
  maxAttempts?: number // Maximum number of attempts to make before throwing
};

type Result = {
  dispose: Disposer,
  folderPath: string,
  filePath: string,
  fileName: string
};

function getUnusedPath ( options: Options ): Promise<Result>;
```

You can use the library like so:

```ts
import fs from 'node:fs';
import getUnusedPath from 'get-unused-path';

// Let's get an unused path

const result = await getUnusedPath ({
  fileName: 'foo.txt',
  folderPath: '/x/y/z',
  // incrementer: ( name, ext, attempt ) => attempt > 1 ? `${name}-${attempt}${ext}` : `${name}${ext}`,
  // maxTries: 1_000
});

result.dispose; // => () => void
result.folderPath; // => '/x/y/z'
result.filePath; // => '/x/y/z/foo (3).txt'
result.fileName; // => 'foo (3).txt'

// Let's now write to that path

await fs.promises.writeFile ( result.filePath, '...' );

// Let's now release our lock on this file name
// We have used the file path by now, so we need to dispose of our "lock" on it, allowing it to be returned again in the future, potentially

result.dispose ();
```

## Related

- [unused-path](https://github.com/fabiospampinato/unused-path): Reliably get an unused path and copy/move/write to it.
- [copy-unused-path](https://github.com/fabiospampinato/copy-unused-path): Reliably copy to an unused path.
- [move-unused-path](https://github.com/fabiospampinato/move-unused-path): Reliably move to an unused path.
- [write-unused-path](https://github.com/fabiospampinato/write-unused-path): Reliably write to an unused path.

## License

MIT © Fabio Spampinato

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