npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

fs-utils-async

v1.0.1

Published

The fs-utils-async package provides a collection of well-tested, asynchronous file system utility functions. It mirrors fs-utils-sync name for name, promotes consistency and readability across projects by providing a unified approach to common file operat

Readme

Filesystem Utils Async

The fs-utils-async package provides a collection of well-tested, asynchronous file system utility functions built on node:fs/promises. It promotes consistency and readability across projects by providing a unified approach to common file operations, saving you development time and improving code quality.

Its API matches fs-utils-sync name for name: the same functions, parameters, error codes and validation rules, except that every operation returns a promise. isPathWithin is the one exception, because it never touches the filesystem: it stays synchronous in both packages.

Getting Started

Install the package:

npm i -S fs-utils-async

Examples

project
    │
    some-dir/
    │    └───...
    │
    some-file.json
import { pathExists, getPathElement, deleteFile } from 'fs-utils-async';

await pathExists('project'); // true
await pathExists('project/some-dir'); // true
await pathExists('project/some-other-dir'); // false
await pathExists('project/some-file.json'); // true
await pathExists('project/other-file.json'); // false

await getPathElement('project/other-file.json'); // null
await getPathElement('project/some-file.json');
// {
//    path: 'project/some-file.json',
//    baseName: 'some-file.json',
//    extName: '.json',
//    isFile: true,
//    isDirectory: false,
//    isSymbolicLink: false,
//    size: 8647,
//    creation: 1715264137289,
// }

await deleteFile('project/some-file.json');
await getPathElement('project/some-file.json'); // null

API Reference

General Actions

Checks if a path exists (file or directory).

import { pathExists } from 'fs-utils-async';

await pathExists('some-existent-dir'); // true
await pathExists('some-non-existent-file.json'); // false

Reads the content of a given path and returns the stats. If the path doesn't exist, it resolves to null

import { getPathElement } from 'fs-utils-async';

await getPathElement('project/some-file.json');
// {
//    path: 'project/some-file.json',
//    baseName: 'some-file.json',
//    extName: '.json',
//    isFile: true,
//    isDirectory: false,
//    isSymbolicLink: false,
//    size: 8647,
//    creation: 1715264137289,
// }

Checks if a target path is the root path itself or is nested inside it. It is synchronous, because the check is lexical: both paths are resolved without touching the filesystem, and symbolic links aren't followed. Sibling paths that share a prefix aren't nested, and neither is a path on another drive on Windows.

import { isPathWithin } from 'fs-utils-async';

isPathWithin('/data/app', '/data/app'); // true
isPathWithin('/data/app', '/data/app/logs/today.log'); // true
isPathWithin('/data/app', '/data/app/../secrets'); // false
isPathWithin('/data/app', '/data/application'); // false

Directory Actions

Verifies if a given path exists and is a directory.

import { isDirectory } from 'fs-utils-async';

await isDirectory('some-existent-dir'); // true
await isDirectory('some-non-existent-dir'); // false
await isDirectory('some-existent-file.json'); // false

Deletes the directory located in the given path.

import { isDirectory, deleteDirectory } from 'fs-utils-async';

await isDirectory('some-existent-dir'); // true
await deleteDirectory('some-existent-dir');
await isDirectory('some-existent-dir'); // false

Creates a directory at a given path.

import { isDirectory, createDirectory } from 'fs-utils-async';

await isDirectory('some-dir'); // false
await createDirectory('some-dir');
await isDirectory('some-dir'); // true

It copies a directory (and sub directories) from srcPath to destPath. Keep in mind the destPath is completely overridden.

import { isDirectory, copyDirectory } from 'fs-utils-async';

await isDirectory('some-dir'); // true
await isDirectory('my-copy'); // false
await copyDirectory('some-dir', 'my-copy');
await isDirectory('my-copy'); // true

Creates a symlink for the target directory at path.

import { createDirectorySymLink } from 'fs-utils-async';

await createDirectorySymLink('some-dir', 'some-dir-symlink');

Reads the contents of a directory based on the provided options and returns them.

import { readDirectory } from 'fs-utils-async';

await readDirectory('some-dir', true);
// [
//   'some-dir/file-01.txt',
//   'some-dir/file-02.json',
//   'some-dir/inner',
//   'some-dir/inner/inner-01.txt'
// ]

Retrieves all the path elements in the given directory based on the provided options. IMPORTANT: if the includeExts option is provided, make sure to lowercase all extensions (e.g '.json').

import { getDirectoryElements } from 'fs-utils-async';

await getDirectoryElements('fs-test-dir');
// {
//   directories: [
//     {
//       path: 'fs-test-dir/another-dir',
//       baseName: 'another-dir',
//       extName: '',
//       isFile: false,
//       isDirectory: true,
//       isSymbolicLink: false,
//       size: 4096,
//       creation: 1733515026497
//     },
//     {
//       path: 'fs-test-dir/some-dir',
//       baseName: 'some-dir',
//       extName: '',
//       isFile: false,
//       isDirectory: true,
//       isSymbolicLink: false,
//       size: 4096,
//       creation: 1733515026497
//     }
//   ],
//   files: [
//     {
//       path: 'fs-test-dir/aafile.json',
//       baseName: 'aafile.json',
//       extName: '.json',
//       isFile: true,
//       isDirectory: false,
//       isSymbolicLink: false,
//       size: 18,
//       creation: 1733515026497
//     },
//     {
//       path: 'fs-test-dir/afile.txt',
//       baseName: 'afile.txt',
//       extName: '.txt',
//       isFile: true,
//       isDirectory: false,
//       isSymbolicLink: false,
//       size: 12,
//       creation: 1733515026497
//     }
//   ],
//   symbolicLinks: [
//     {
//       path: 'fs-test-dir/aafile-sl.json',
//       baseName: 'aafile-sl.json',
//       extName: '.json',
//       isFile: false,
//       isDirectory: false,
//       isSymbolicLink: true,
//       size: 23,
//       creation: 1733515026497
//     },
//     {
//       path: 'fs-test-dir/some-dir-sl',
//       baseName: 'some-dir-sl',
//       extName: '',
//       isFile: false,
//       isDirectory: false,
//       isSymbolicLink: true,
//       size: 20,
//       creation: 1733515026497
//     }
//   ]
// }

File Actions

Verifies if a given path exists and is a file.

import { isFile } from 'fs-utils-async';

await isFile('existent-file.json'); // true
await isFile('non-existent-file.json'); // false

Creates the base directory for a file in case it doesn't exist and then it writes the file.

import { writeFile } from 'fs-utils-async';

await writeFile('test-file.txt', 'Hello World!', { encoding: 'utf-8' });

Writes a text file on a given path.

import { writeTextFile } from 'fs-utils-async';

await writeTextFile('test-file.txt', 'Hello World!');

Writes a JSON file on a given path. If an object is provided, it will be stringified.

import { writeJSONFile } from 'fs-utils-async';

await writeJSONFile('test-file.json', { id: 1, nickname: 'test-user' });

Writes a Buffer file on a given path. If an object is provided, it will be stringified.

import { Buffer } from 'node:buffer';
import { writeBufferFile } from 'fs-utils-async';

await writeBufferFile('test-file', Buffer.from('Hello World!'));

Reads and returns the contents of a file.

import { readFile } from 'fs-utils-async';

await readFile('test-file.txt', { encoding: 'utf-8' }); // 'Hello World!'

Reads a text file and returns its contents.

import { readTextFile } from 'fs-utils-async';

await readTextFile('test-file.txt'); // 'Hello World!'

Reads a text file, parses and returns its contents.

import { readJSONFile } from 'fs-utils-async';

await readJSONFile<IUser>('test-file.json'); // { id: 1, nickname: 'test-user' }

Reads a Buffer file and returns its contents.

import { readBufferFile } from 'fs-utils-async';

await readBufferFile('test-file'); // <Buffer 48 65 6c 6c 6f 20 57 6f 72 6c 64 21>

Copies a file from srcPath to destPath, replacing the destination if it exists.

import { isFile, copyFile } from 'fs-utils-async';

await isFile('file-a.json'); // true
await isFile('file-b.json'); // false
await copyFile('file-a.json', 'file-b.json');
await isFile('file-b.json'); // true

Deletes the file located at the provided path.

import { isFile, deleteFile } from 'fs-utils-async';

await isFile('file-a.json'); // true
await deleteFile('file-a.json');
await isFile('file-a.json'); // false

Creates a symlink for a given file.

import { createFileSymLink } from 'fs-utils-async';

await createFileSymLink('test-file.txt', 'test-file-symlink.txt');

Writes a file atomically, so readers see either the previous content or the complete new content, never a partial write. The data goes to a temporary file in the same directory, which is flushed to disk and renamed over the path. On POSIX, the directory is flushed as well. Missing parent directories are created, also when several calls write into the same new directory at once.

Permissions: an explicit mode wins. Without one, a replaced file keeps its permission bits, and a new file gets the platform default, as with writeFile. The temporary file is never readable more widely than the final mode. The owner of a replaced file isn't preserved.

Failures: when writing fails before the rename, the temporary file is removed, the destination is left untouched and the original error is rethrown. If flushing the directory fails after the rename, the promise rejects even though the destination already holds the new content.

import { writeFileAtomic } from 'fs-utils-async';

await writeFileAtomic('project/state.json', JSON.stringify({ step: 2 }));
await writeFileAtomic('project/.env.local', 'API_KEY=example', 0o600);

Reads a regular file of at most maxBytes bytes and returns its content as a Buffer. It reads at most maxBytes + 1 bytes, even when the file grows while it is being read, and a named pipe at the path can't make it block.

It never follows a symbolic link in the path's final component. Symbolic links in parent directories are followed, so code that must stay inside a directory should combine it with isPathWithin and its own checks of the parent directories. On Windows, which has no O_NOFOLLOW, the link check runs just before opening, so a link swapped in between isn't detected.

It throws NOT_A_FILE when the path doesn't exist, its final component is a symbolic link, or it isn't a regular file, and FILE_TOO_LARGE when the file holds more than maxBytes bytes.

import { readBoundedFile } from 'fs-utils-async';

(await readBoundedFile('project/state.json', 1024 * 1024)).toString('utf-8');
// '{"step":2}'

Types

The most relevant information regarding a path element, extracted by making use of the lstat function.

interface IPathElement {
  // the relative path of the el
  path: string;

  // the base name of the el
  baseName: string;

  // the ext of the el (e.g '.json'). If the el has no ext, it will be an empty string ('')
  extName: string;

  // true if the el is a file
  isFile: boolean;

  // true if the el is a directory
  isDirectory: boolean;

  // true if the el is a symbolic link
  isSymbolicLink: boolean; // when this property is true, isFile & isDirectory are false

  // the size in bytes of the el
  size: number;

  // the date in which the el was created (in milliseconds)
  creation: number;
}

When querying the path elements from within a directory, a series of filters and sorting options can be provided.

import { ISortDirection } from 'web-utils-kit';

type IDirectoryElementsKeySort = 'baseName' | 'size' | 'creation';

type IDirectoryElementsOptions = {
  // the key that will be used to sort the elements. Defaults to 'baseName'
  sortByKey: IDirectoryElementsKeySort;

  // the sort order that will be applied to the elements. Defaults to 'asc'
  sortOrder: ISortDirection;

  // the list of file extensions that will be included. Defaults to [] (includes all exts)
  includeExts: string[];
};

The output emitted when retrieving all the path elements within a directory.

type IDirectoryPathElements = {
  directories: IPathElement[];
  files: IPathElement[];
  symbolicLinks: IPathElement[];
};

Built With

  • TypeScript
  • node:fs/promises

Running the Tests

# unit and integration tests
npm run test

# tests, type checking, linting and formatting
npm run verify

# unit tests
npm run test:unit

# integration tests
npm run test:integration

License

MIT