Filesystem Utils Sync

The fs-utils-sync package provides a collection of well-tested, synchronous file system utility functions. It promotes consistency and readability across projects by providing a unified approach to common file operations, saving you development time and improving code quality.

Getting Started

Install the package:

npm i -S fs-utils-sync

Examples

project
    │
    some-dir/
    │    └───...
    │
    some-file.json

import { pathExist, getPathElement, deleteFile } from 'fs-utils-sync';

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

getPathElement('project/other-file.json'); // null
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,
// }

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

API Reference

General Actions

Checks if a path exists (file or directory).

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

pathExists('some-existent-dir'); // true
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 returns null

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

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,
// }

Directory Actions

Verifies if a given path exists and is a directory.

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

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

Deletes the directory located in the given path.

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

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

Creates a directory at a given path.

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

isDirectory('some-dir'); // false
createDirectory('some-dir');
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-sync';

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

Creates a symlink for the target directory at path.

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

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-sync';

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-sync';

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-sync';

isFile('existent-file.json'); // true
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-sync';

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

Writes a text file on a given path.

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

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-sync';

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-sync';

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

Reads and returns the contents of a file.

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

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

Reads a text file and returns its contents.

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

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

Reads a text file, parses and returns its contents.

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

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

Reads a Buffer file and returns its contents.

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

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-sync';

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

Deletes the file located at the provided path.

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

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

Creates a symlink for a given file.

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

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

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

Running the Tests

# unit tests
npm run test:unit

# integration tests
npm run test:integration

License

MIT