Async-file-tried

async-file-tried is a wrapper around node’s fs/promises that abstracts the try-catch block for you. Write more linear, better readable code by getting a concise response. Dependency free. TypeScript supported.

Install

npm install async-file-tried

Import:

import fs from 'async-file-tried';

Usage

Usually we do not want to make calls against the file system without a proper error handling. But the try-catch block is somewhat unelegant because it moves code blocks in the bracket sub-space and thus disturbs the linearity of our programming. async-file-tried returns a tuple with either the response or the error from a fs call and simplifies error handling.

You can write now:

let [res, err] = await fs.readdir('.');
if (err) console.error(err);
else console.log(res);

... instead of:

try {
    let res = await fs.readdir('.');
    console.log(res);
}
catch (err) {
    console.error(err);
}

Extra: joined paths

async-file-tried also has an in-built path.join() so that you can alternatively pass the path argument as array of sub-elements.

You can write i.e.:

let [res, err] = await fs.appendFile(
  ['fs.__dirname', '..' , 'myfolder', `img_${i}.txt`], 
  'my text');

... and the path string will be composed automatically.

Public Functions (FS Function List)

fs.access

Tests a user's permissions for the file or directory specified by path.

Typescript implementation:

async (path: string|Array<string>, mode?: number|string)

Usage example:

let [res, err] = await fs.access('file.txt', fs.constants.R_OK);

fs.appendFile

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

Typescript implementation:

async (path: string|Array<string>, data: any, options?: { encoding?: Encoding; mode?: number|string; flag?: Flags; })

Usage example:

let [res, err] = await fs.appendFile('file.txt', 'foo');

fs.chmod

Changes the permissions of a file or directory.

Typescript implementation:

async (path: string|Array<string>, mode?: number|string)

Usage example:

let [res, err] = await fs.chmod('file.txt', '755');

fs.chown

Changes the ownership of a file by setting the user ID and group ID.

Typescript implementation:

async (path: string|Array<string>, uid: number, gid: number)

Usage example:

let [res, err] = await fs.chown('file.txt', 1541, 999);

fs.copyFile

Copies a file from one location to another.

Typescript implementation:

async (srcPath: string|Array<string>, destPath: string|Array<string>, flags?: number)

Usage example:

let [res, err] = await fs.copyFile('file.txt', 'file-copy.txt');

fs.cp

Recursively copies files and directories from one location to another.

Typescript implementation:

async (srcPath: string|Array<string>, destPath: string|Array<string>)

Usage example:

let [res, err] = await fs.cp('myfolder', 'myfolder-copy', { recursive: true });

fs.lchmod

Changes the permissions of a symbolic link.

Typescript implementation:

async (path: string|Array<string>, mode?: number|string)

Usage example:

let [res, err] = await fs.lchmod('symlink.txt', '755');

fs.lchown

Changes the ownership of a symbolic link.

Typescript implementation:

async (path: string|Array<string>, uid: number, gid: number)

Usage example:

let [res, err] = await fs.lchown('./test/static-testfiles/symlinkToFile-append.txt', 1200, 1201);

fs.link

Creates a new hard link to an existing file.

Typescript implementation:

async (existingPath: string|Array<string>, newPath: string|Array<string>)

Usage example:

let [res, err] = await fs.link('file.txt', 'file-hard-link.txt');

fs.lstat

Retrieves information about a symbolic link or file without following the link.

Typescript implementation:

async (path: string|Array<string>, options?: object)

Usage example:

let [res, err] = await fs.lstat('symlinkToFile.txt');

fs.lutimes

Changes the access and modification times of a symbolic link.

Typescript implementation:

async (path: string|Array<string>, atime: Date|number, mtime: Date|number)

Usage example:

let [res, err] = await fs.lutimes('file.txt', new Date(), new Date());

fs.mkdir

Creates a new directory at the specified path.

Typescript implementation:

async (path: string|Array<string>, options?: number|string)

Usage example:

let [res, err] = await fs.mkdir('./my-new-folder');

fs.mkdtemp

Creates a uniquely named temporary directory.

Typescript implementation:

async (prefix: string, encoding?: Encoding)

Usage example:

let [res, err] = await fs.mkdtemp('temp-');

fs.open

Opens a file and returns a file handle for reading or writing.

Typescript implementation:

async (path: string|Array<string>, flags?: Flags, mode?: number|string)

Usage example:

let [res, err] = await fs.open('file.txt', 'r');

fs.opendir

Opens a directory for reading and returns a directory handle.

Typescript implementation:

async (path: string|Array<string>, flags?: Flags, mode?: number|string)

Usage example:

let [res, err] = await fs.opendir('./test', { encoding: "utf8", bufferSize: 64 });

fs.readFile

Reads the contents of a file into memory.

Typescript implementation:

async (path: string|Array<string>, options?: Encoding)

Usage example:

let [res, err] = await fs.readFile('file.txt', 'utf8');

fs.readdir

Reads the contents of a directory.

Typescript implementation:

async (path: string|Array<string>, options?: object)

Usage example:

let [res, err] = await fs.readdir('./my-directory');

fs.readlink

Reads the value of a symbolic link.

Typescript implementation:

async (path: string|Array<string>, options?: object|string)

Usage example:

let [res, err] = await fs.readlink('symlinkToFile.txt');

fs.realpath

Resolves a path to its absolute real path, resolving symlinks.

Typescript implementation:

async (path: string|Array<string>, options?: object)

Usage example:

let [res, err] = await fs.realpath('./my-folder/../');

fs.rename

Renames or moves a file or directory.

Typescript implementation:

async (oldPath: string|Array<string>, newPath: string|Array<string>)

Usage example:

let [res, err] = await fs.rename('old.txt', 'new.txt');

fs.rm

Removes files or directories.

Typescript implementation:

async (path: string|Array<string>, options?: object)

Usage example:

let [res, err] = await fs.rm('file.txt');

fs.rmdir

Removes a directory.

Typescript implementation:

async (path: string|Array<string>, options?: object)

Usage example:

let [res, err] = await fs.rmdir('./my-folder');

fs.stat

Retrieves information about a file or directory.

Typescript implementation:

async (path: string|Array<string>, options?: object)

Usage example:

let [res, err] = await fs.stat('file.txt');

fs.symlink

Creates a symbolic link to a target file or directory.

Typescript implementation:

async (target: string|Array<string>, path: string|Array<string>, type?: string)

Usage example:

let [res, err] = await fs.symlink('file.txt', 'file-symlink.txt', 'file');

fs.truncate

Truncates a file to a specified length.

Typescript implementation:

async (path: string|Array<string>, len: number)

Usage example:

let [res, err] = await fs.truncate('file.txt', 760);

fs.unlink

Removes (deletes) a file.

Typescript implementation:

async (path: string|Array<string>)

Usage example:

let [res, err] = await fs.unlink('file-symlink.txt');

fs.utimes

Changes the access and modification times of a file.

Typescript implementation:

async (path: string|Array<string>, atime: number|string|Date, mtime: number|string|Date)

Usage example:

let [res, err] = await fs.utimes('file.txt', new Date(), new Date());

fs.watch

Watches for changes in a file or directory and emits events.

Typescript implementation:

async (filename: string|Array<string>, options?: BufferEncoding | "buffer")

Usage example:

let [res, err] = await fs.watch('file.txt', (ev, file) => {
  console.log("Watcher: " + file);
});

fs.writeFile

Writes data to a file, replacing its contents if it already exists.

Typescript implementation:

async (path: string|Array<string>, data: any, options?: Encoding)

Usage example:

let [res, err] = await fs.writeFile('file.txt', 'my text', 'utf8');

The Constants

fs.constants

The fs.constants object provides commonly used constants for file operations.

fs.__dirname

Equivalent to Node’s __dirname but usable within ES modules. Returns the directory name of the current module.

Implementation:

path.dirname(fileURLToPath(import.meta.url));

fs.__filename

Equivalent to Node’s __filename but usable within ES modules. Returns the absolute filename of the current module.

Implementation:

fileURLToPath(import.meta.url);

Bonus Functions

fs.exists

Checks if a file or directory exists, returns boolean. Typescript implementation:

async (path: string|Array<string>)

Usage example:

let res = await fs.exists('file.txt');

fs.ensureDir

Checks if a directory exists, creates it if not. Typescript implementation:

async (dir: string|Array<string>)

Usage example:

let res = await fs.ensureDir('./my-dir');

fs.readJson

Reads a JSON file and returns it as parsed Javascript object. Typescript implementation:

async (path: string|Array<string>, options?: Encoding)

Usage example:

let [res, err] = await fs.readJson('my.json');

fs.writeJson

Expects a Javascript object, will stringify it and write it out as JSON. Typescript implementation:

async (path: string|Array<string>, data: Object, options?: Encoding)

Usage example:

let [res, err] = await fs.writeJson('my.json', { key : "value" });

fs.readTextFile

Reads a text file as UTF8. Typescript implementation:

async (path: string|Array<string>)

Usage example:

let [res, err] = await fs.readTextFile('file.txt');

fs.writeTextFile

Writes out a String as UTF8. Typescript implementation:

async (path: string|Array<string>, data: string)

Usage example:

let [res, err] = await fs.writeTextFile('file.txt', 'Hello world!');

The Async Handler

This Handler is behind all Async-file-tried functions. You can pass any function (wrapped in an anonymous function) to it, and the Result/ Error will be returned as tuple.

fs.asyncHandler

Takes any asynchronous Function and will internally wrap a try-catch block around it. The Return is given in the tuple pattern [res, err]. Typescript implementation:

asyncHandler = async (func: Function)

Usage example:

let [res, err] = await fs.asyncHandler(() => await myCustomFunction(someParam));

Run tests

npm test

License

Copyright (c) 2023–25 Florian Walzel, MIT License