Wondering what’s next for npm?Check out our public roadmap! »

    TypeScript icon, indicating that this package has built-in type declarations

    1.4.2 • Public • Published

    Get Unused Path

    Reliably get an unused path you can write to.


    • 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.


    npm install --save get-unused-path


    The following interface is provided:

    type Disposer = () => void;
    type Incrementer = ( name: string, ext: string, attempt: number ) => string;
    type Options = {
      maxAttempts?: number, // Maximum number of attempts to make before throwing
      countFilesystemAttemptsOnly?: boolean, // Whether to count as attempts only checks that hit the filesystem, ignoring quick checks performed by the library when it knows already that a path is used because it hasn't been disposed of yet
      disposeDelay?: number, // Milliseconds to delay disposals by
      incrementer?: Incrementer, // Function that increments the file name during each attempt
      folderPath?: string, // Folder path where to look for unused path
      fileName: string // Initial file name
    type Result = {
      dispose: Disposer,
      folderPath: string,
      filePath: string,
      fileName: string
    function getUnusedPath ( options: Options ): Promise<Result>;

    You can use the library like so:

    import * as fs from 'fs';
    import getUnusedPath from 'get-unused-path';
    async function example () {
      const {disposer, folderPath, filePath, fileName} = await getUnusedPath ({
        folderPath: '/x/y/z',
        fileName: 'foo.txt',
        // maxTries: 1000,
        // incrementer: ( name, ext, attempt ) => attempt > 1 ? `${name}-${attempt}${ext}` : `${name}${ext}`
      console.log ( disposer ); // => Function
      console.log ( folderPath ); // => '/x/y/z'
      console.log ( filePath ); // => '/x/y/z/foo (3).txt'
      console.log ( fileName ); // => 'foo (3).txt'
      await fs.promises.writeFile ( filePath, '...' );
      disposer (); // We would have used the file path by now, so we can dispose of our "lock" on it, allowing it to be returned again in the future
    example ();



    MIT © Fabio Spampinato


    npm i get-unused-path

    DownloadsWeekly Downloads






    Unpacked Size

    21.2 kB

    Total Files


    Last publish


    • avatar