Interface PathNice<T>

Get (when 0 args) or set (when 1 arg) the directory name of the path.

If the argument is a function, it should accept a string of the old dirname and return a string as the new dirname.

Example

$ path('/usr/local/bin').dirname().raw
'/usr/local'         // on POSIX

$ path('C:\\Users\\fuu').dirname().raw
'C:\\Users'          // on Windows

$ path('./src/index.ts').dirname('./dist').raw
'dist/index.ts'      // on POSIX
'dist\\index.ts'     // on Windows

$ path('path-nice/dist/types.ts').dirname(old => old.replace(/dist/g, 'build')).raw
'path-nice/build/types.ts'   // on POSIX
'path-nice\\build\\types.ts' // on Windows

Get (when 0 args), set (when arg is a string or a function) or remove (when arg is null) the extension of the path, from the last '.' to end of string in the last portion of the path.

When getting the filename, if there is no '.' in the last portion of the path or the first character of it is '.', then it returns an empty string.

When setting the filename, it will only modifiy the path string and will not actually rename the file.

Example

$ path('./src/index.js').ext()
'.js'

$ path('./LICENSE').ext()
''

$ path('.bashrc').ext()
''

$ path('./src/index.js').ext('.ts').raw
'./src/index.ts'     // on POSIX
'./src\\index.ts'    // on Windows

$ path('./public/help.htm').ext(
      ext => ext === '.htm' ? '.html' : ext
  ).raw
'./public/help.html' // on POSIX
'./public\\help.html'// on Windows

$ path('./README.md').ext(null).raw
'./README'           // on POSIX
'.\\README'          // on Windows

Get (when 0 args) or set (when 1 arg) the filename of the path.

When getting the filename, technically, it will firstly convert the path to an absolute path, then return its last portion. Therefore, for relative paths ". /", this method can also get the file name. If the path is root directory, it returns ''.

When setting the filename, it will only modifiy the path string and will not actually rename the file. If the argument is a function, it should accept a string of the old filename and return a string as the new filename.

Example

$ path('./src/index.js').filename()
'index.js'

$ path('/home/fuu///').filename()
'fuu'                    // on POSIX

$ path('/home/fuu/bar.txt').filename('foo.md').raw
'/home/fuu/foo.md'       // on POSIX

$ path('C:\\Users\\fuu\\\\\\').filename()
'fuu'                    // on Windows

$ path('C:\\Users\\fuu\\bar.txt').filename('foo.md').raw
'C:\\Users\\fuu\\foo.md' // on Windows

$ path('./data/storage.json').filename(n => 'old.' + n).raw
'data/old.storage.json'  // on POSIX
'data\\old.storage.json' // on Windows

Determine whether path is an absolute path. An absolute path will always resolve to the same location, regardless of the working directory.

Example

// on POSIX
path('/foo/bar').isAbsolute();    // true
path('/baz/..').isAbsolute();     // true
path('qux/').isAbsolute();        // false
path('.').isAbsolute();           // false
// on Windows
path('//server').isAbsolute();    // true
path('\\\\server').isAbsolute();  // true
path('C:/foo/..').isAbsolute();   // true
path('C:\\foo\\..').isAbsolute(); // true
path('bar\\baz').isAbsolute();    // false
path('bar/baz').isAbsolute();     // false
path('.').isAbsolute();           // false

Join this path with all arguments together and normalize the resulting path.

Example

$ path('../data').join('settings.json').raw
'../data/settings.json'      // on POSIX
'..\\data\\settings.json'    // on Windows

$ path('/home').join('fuu', 'data.json').raw
'/home/fuu/data.json'        // on POSIX

$ path('C:\\Users').join('fuu', 'data.json').raw
'C:\\Users\\fuu\\data.json'  // on Windows

Return an object whose properties represent significant elements of the path.

Example

// on POSIX
┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┐              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘
$ const result = path('/home/fuu/data.json').parse()
$ result.root()
'/'
$ result.dir()
'/home/fuu'
$ result.base()
'data.json'
$ result.ext()
'.json'
$ result.name()
'data'
$ result.dir('/root').ext('.txt').format().raw
'/root/data.txt'

// on Windows
┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┐              ├──────┬─────┤
│ root │              │ name │ ext │
" C:\      path\dir   \ file  .txt "
└──────┴──────────────┴──────┴─────┘
$ const result = path('C:\\Users\\fuu\\data.json').parse()
$ result.root()
'C:\\'
$ result.dir()
'C:\\Users\\fuu'
$ result.base()
'data.json'
$ result.ext()
'.json'
$ result.name()
'data'
$ result.dir('D:\\path-nice').ext('.txt').format().raw
'D:\\path-nice\\data.txt'

Add a postfix to the end of the path.

This will only modifiy the path string and will not actually rename the file.

Example

$ path('user/data/').postfix('-1').raw
'user/data-1'        // on POSIX
'user\\data-1'       // on Windows

$ path('./content.txt').postfix('.json').raw
'./content.txt.json' // on POSIX
'.\\content.txt.json' // on Windows

Add a postfix to the filename, but before the extension. If the extension not exists, directly add to the end.

This will only modifiy the path string and will not actually rename the file.

Example

$ path('path-nice/tsconfig.json').postfixBeforeExt('.base').raw
'path-nice/tsconfig.base.json'   // on POSIX
'path-nice\\tsconfig.base.json'  // on Windows

Add a prefix to the filename, i.e. add the prefix after dirname, before filename.

This will only modifiy the path string and will not actually rename the file.

Example

$ path('data/January').prefixFilename('2021-').raw
'data/2021-January'  // on POSIX
'data\\2021-January' // on Windows

Asynchronously computes the canonical pathname by resolving ., .., and symbolic links.

Get (when 0 args) or set (when 1 arg) the path segment separator.

When get, return 'none' if there is no separator in the path, or 'hybrid' if there are both '/' and '\' separators.

Example

$ path('/home/fuu/data.json').separator()
'/'

$ path('C:\\Windows\\System32').separator()
'\\'

$ path('index.js').separator()
'none'

$ path('C:\\Windows/System32').separator()
'hybrid'

$ path('/home/fuu/data.json').separator('\\').raw
'\\home\\fuu\\data.json'

$ path('C:\\Windows\\System32').separator('/').raw
'C:/Windows/System32'

Resolve the path to an absolute path, if it isn't now.

Example

$ path('./src/index.ts').toAbsolute().raw // on POSIX,
                                          // suppose cwd is '/path-nice'
'/path-nice/src/index.ts'

$ path('./src/index.ts').toAbsolute().raw // on Windows,
                                          // suppose cwd is 'D:\\path-nice'
'D:\\path-nice\\src\\index.ts'

$ path('./src/index.ts').toAbsolute('/work').raw     // on POSIX
'/work/src/index.ts'

$ path('./src/index.ts').toAbsolute('D:\\work').raw  // on Windows
'D:\\work\\src\\index.ts'

Solve the relative path by comparing with {relativeTo}. At times we have two absolute paths, and we need to derive the relative path from one to the other. This is actually the reverse transform of path.resolve.

The default value of relativeTo is current working directory.

Example

$ path('./src/index.ts').toAbsolute().toRelative('./')
'src/index.ts'       // on POSIX
'src\\index.ts'      // on Windows

$ path('/data/orandea/impl/bbb').toRelative('/data/orandea/test/aaa').raw
'../../impl/bbb'     // on POSIX

$ path('C:\\orandea\\impl\\bbb').toRelative('C:\\orandea\\test\\aaa').raw
'..\\..\\impl\\bbb'  // on Windows

Asynchronously append data to a file, creating the file if it does not yet exist.

Roughly same as fs.createReadStream(), but no need to specify the path.

See fs.createReadStream(path[, options]) for full document.

Roughly same as fs.createWriteStream(), but no need to specify the path.

See fs.createWriteStream(path[, options]) for full document.

Roughly same as fs.promise.open(), but no need to specify the path.

Opens a FileHandle.

Refer to the POSIX open(2) documentation for more detail.

Some characters (< > : " / \ | ? *) are reserved under Windows as documented by Naming Files, Paths, and Namespaces. Under NTFS, if the filename contains a colon, Node.js will open a file system stream, as described by this MSDN page.

Similar to .writeFile(), except that if the parent directory does not exist, it will be created automatically.

Similar to .writeJSON(), except that if the parent directory does not exist, it will be created automatically.

Roughly same as fs.promises.readFile(), but no need to specify the path.

Asynchronously reads the entire contents of a file.

If no encoding is specified (using options.encoding), the data is returned as a object. Otherwise, the data will be a string.

If options is a string, then it specifies the encoding.

• options.encoding Default: null
• options.flag See support of file system flags. Default: 'r'
• options.signal allows aborting an in-progress readFile

It is possible to abort an ongoing readFile using an AbortSignal. If a request is aborted the promise returned is rejected with an AbortError:

import path from 'path-nice';

try {
  const controller = new AbortController();
  const { signal } = controller;
  const promise = path(filename).readFile({ signal });

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an AbortError
  console.error(err);
}

Aborting an ongoing request does not abort individual operating system requests but rather the internal buffering fs.readFile performs.

Similar to .readFile(), but guaranteed to return a string, use UTF-8 by default.

Asynchronously reads the entire contents of a file.

Asynchronously reads a JSON file and then parses it into an object.

If options is a string, then it specifies the encoding.

• options.encoding Default: 'utf8'
• options.flag See support of file system flags. Default: 'r'

Execute the given function with the original content of the file as input, and the returned string will become the new content of the file.

Asynchronously update the json object of the file.

Roughly same as fs.promises.writeFile(), but no need to specify the path.

Asynchronously writes data to a file, replacing the file if it already exists.

It is unsafe to call fsPromises.writeFile() multiple times on the same file without waiting for the Promise to be resolved (or rejected).

Asynchronously writes an object to a JSON file.

Similar to fs.promises.cp(), except that the default value of options.recursive is true.

Asynchronously copies a file or directory to dest, including subdirectories and files when copying a directory.

Returns

destination path wrapped in Promise

Asynchronously removes a file or directory. The directory can have contents. If the path does not exist, silently does nothing.

Returns

original path wrapped in Promise

Asynchronously ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted.

Returns

original path wrapped in Promise

Asynchronously moves a file or directory to dest, even across devices, including subdirectories and files when moving a directory.

Returns

destination path wrapped in Promise

Asynchronously removes a file or directory. The directory can have contents. If the path does not exist, silently does nothing.

Returns

original path wrapped in Promise

Asynchronous rename(2) - Change the name or location of a file or directory.

Returns

destination path wrapped in Promise

Asynchronously ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted.

Returns

original path wrapped in Promise

Asynchronously ensures that the directory exists. If the directory structure does not exist, it is created.

Returns

original path wrapped in Promise

Asynchronously ensures that the file exists. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is NOT MODIFIED.

Returns

original path wrapped in Promise

Note: It is recommended to use isFile(), isDir(), etc to indicate the type of file you want to check.

Asynchronously check whether the path exists.

Asynchronously check whether the path exists and is a directory.

Asynchronously check whether the path exists and is an empty directory.

Note: if the path is inaccessible or not a directory, it also returns false.

Asynchronously check whether the path exists and is a file.

Asynchronously check whether the path exists and is a symbolic link.

Asynchronously list all directories and files under the folder, return a Promise that resolves to an object { dirs: PathNiceArr; files: PathNiceArr }.

• dirs: subdirectories, not including the current folder
• files: files and others (e.g. device, FIFO, socket, etc). If followLinks is false, it also contains links.

The paths wrapped in the returned PathNice object are all absolute paths, so they can be used directly for .readFile(), .writeFile(), .copy(), .move(), etc. Use .toRelative(dir) to get the relative path.

Example

const { dirs, files } = await path('./').ls();

await Promise.all(
  files
    .filter(f => f.ext() === '.json')
    .map(async f => {
      await f.updateJSON(json => { json.timestamp = Date.now() });
      await f.copy(f.dirname('../backup'));
    })
);

await dirs.remove();

Roughly same as fs.promises.readdir(), but no need to specify the path.

Reads the contents of a directory.

The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the filenames. If the encoding is set to 'buffer', the filenames returned will be passed as objects.

If options.withFileTypes is set to true, the resolved array will contain <fs.Dirent> objects.

Example

try {
  const files = await path('path/to/dir').readdir();
  for (const file of files)
    console.log(file);
} catch (err) {
  console.error(err);
}

Roughly same as fs.watchFile(), but no need to specify the path.

Stop watching for changes on filename. If listener is specified, only that particular listener is removed. Otherwise, all listeners are removed, effectively stopping watching of filename.

Calling .unwatchFile() with a filename that is not being watched is a no-op, not an error.

Watch for changes on the path, which can be either a file or a directory.

The second argument is optional. If options is provided as a string, it specifies the encoding. Otherwise options should be passed as an object.

The listener callback gets two arguments (eventType, filename). eventType is either 'rename' or 'change', and filename is the name of the file which triggered the event.

On most platforms, 'rename' is emitted whenever a filename appears or disappears in the directory.

The listener callback is attached to the 'change' event fired by fs.FSWatcher, but it is not the same thing as the 'change' value ofeventType.

If a signal is passed, aborting the corresponding AbortController will close the returned fs.FSWatcher.

Note: Using .watch() or .watchWithChokidar() is more efficient than this method.

Roughly same as fs.watchFile(), but no need to specify the path.

Refer to https://nodejs.org/api/fs.html#fswatchfilefilename-options-listener

Watch file changes with chokidar for a more friendly and powerful API.

This method is equivalent to calling chokidar.watch(path, options), where path is populated with the current path and the options accepted by this method are passed to it.

See https://github.com/paulmillr/chokidar#api for full documents.

⚠️ Note: chokidar can only use the original node:fs module. Calling this method will result in an error if you are using a path-nice generated via bindFS() that is bound to another fs implementation. If you are sure your operation makes sense, enable options.forceEvenDifferentFS to ignore this error.

Asynchronous chmod(2) - Change permissions of a file.

Asynchronous chown(2) - Change ownership of a file.

Asynchronously gets the file mode.

Asynchronously gets the uid and gid of the file owner.

Asynchronously gets the file size.

Asynchronous lchown(2) - Change ownership of a file. Does not dereference symbolic links.

Asynchronous lstat(2) - Get file status. Does not dereference symbolic links.

Asynchronous stat(2) - Get file status.

Synchronously append data to a file, creating the file if it does not yet exist.

Roughly same as fs.openSync(), but no need to specify the path.

Returns an integer representing the file descriptor.

For detailed information, see the documentation fs.open().

Similar to .writeFileSync(), except that if the parent directory does not exist, it will be created automatically.

Similar to .writeJSONSync(), except that if the parent directory does not exist, it will be created automatically.

Roughly same as fs.readFileSync(), but no need to specify the path.

Synchronously reads the entire contents of a file.

If no encoding is specified (using options.encoding), the data is returned as a object. Otherwise, the data will be a string.

If options is a string, then it specifies the encoding.

• options.encoding Default: null
• options.flag See support of file system flags. Default: 'r'

Similar to .readFileSync(), but guaranteed to return a string, use UTF-8 by default.

Synchronously reads the entire contents of a file.

Synchronously reads a JSON file and then parses it into an object.

If options is a string, then it specifies the encoding.

• options.encoding Default: 'utf8'
• options.flag See support of file system flags. Default: 'r'

Execute the given function with the original content of the file as input, and the returned string will become the new content of the file.

Synchronously update the json object of the file.

Roughly same as fs.writeFileSync(), but no need to specify the path.

Synchronously writes data to a file, replacing the file if it already exists.

Synchronously writes an object to a JSON file.

Similar to fs.cpSync(), except that the default value of options.recursive is true.

Synchronously copies a file or directory to dest, including subdirectories and files when copying a directory.

Returns

destination path wrapped in PathNice

Synchronously removes a file or directory. The directory can have contents. If the path does not exist, silently does nothing.

Returns

original path wrapped in Promise

Synchronously ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted.

Returns

original path wrapped in PathNice

Synchronously moves a file or directory to dest, even across devices, including subdirectories and files when moving a directory.

Returns

destination path wrapped in PathNice

Synchronously removes a file or directory. The directory can have contents. If the path does not exist, silently does nothing.

Returns