Skip to content

Reliably get an unused path you can write to.

License

Notifications You must be signed in to change notification settings

fabiospampinato/get-unused-path

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

npm install --save get-unused-path

Usage

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 ();

Related

License

MIT © Fabio Spampinato