fs-utils-sync v1.0.3

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 install -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

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

</details>

<details>
<summary><code>getPathElement</code></summary>

Reads the content of a given path and returns the stats. If the path doesn't exist, it returns `null`
```typescript
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

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

</details>

<details>
<summary><code>deleteDirectory</code></summary>

Deletes the directory located in the given path.
```typescript
import { isDirectory, deleteDirectory } from 'fs-utils-sync';

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

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

</details>

<details>
<summary><code>copyDirectory</code></summary>

It copies a directory (and sub directories) from `srcPath` to `destPath`. Keep in mind the `destPath` is completely overridden.
```typescript
import { isDirectory, copyDirectory } from 'fs-utils-sync';

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

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

</details>

<details>
<summary><code>readDirectory</code></summary>

Reads the contents of a directory based on the provided options and returns them.
```typescript
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'
// ]

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

</details>


### File Actions

<details>
<summary><code>isFile</code></summary>

Verifies if a given path exists and is a file.
```typescript
import { isFile } from 'fs-utils-sync';

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

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

</details>

<details>
<summary><code>writeTextFile</code></summary>

Writes a text file on a given path.
```typescript
import { writeTextFile } from 'fs-utils-sync';

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

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

</details>

<details>
<summary><code>writeBufferFile</code></summary>

Writes a Buffer file on a given path. If an object is provided, it will be stringified.
```typescript
import { Buffer } from 'node:buffer';
import { writeBufferFile } from 'fs-utils-sync';

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

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

</details>

<details>
<summary><code>readTextFile</code></summary>

Reads a text file and returns its contents.
```typescript
import { readTextFile } from 'fs-utils-sync';

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

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

</details>

<details>
<summary><code>readBufferFile</code></summary>

Reads a Buffer file and returns its contents.
```typescript
import { readBufferFile } from 'fs-utils-sync';

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

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

</details>

<details>
<summary><code>deleteFile</code></summary>

Deletes the file located at the provided `path`.
```typescript
import { isFile, deleteFile } from 'fs-utils-sync';

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

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

</details>





<br/>

## Types

<details>
<summary><code>IPathElement</code></summary>

The most relevant information regarding a path element, extracted by making use of the `lstat` function.
```typescript
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;
}

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[];

};

</details>

<details>
<summary><code>IDirectoryPathElements</code></summary>

The output emitted when retrieving all the path elements within a directory.
```typescript
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

Deployment

Install dependencies:

npm install

Build the library:

npm start

Publish to npm:

npm publish