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.

License

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

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

  • 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

  • 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

  • Typescript implementation: async (path: string|Array<string>, mode?: number|string)
  • Usage example: let [res, err] = await fs.chmod('file.txt', '755');

• fs.chown

  • 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

  • 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

  • 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

  • Typescript implementation: async (path: string|Array<string>, mode?: number|string)
  • Usage example: ``

• fs.lchown

  • 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

  • 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

  • Typescript implementation: async (path: string|Array<string>, options?: object)
  • Usage example: let [res, err] = await fs.lstat('symlinkToFile.txt');

• fs.lutimes

  • 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

  • Typescript implementation: async (path: string|Array<string>, options?: number|string)
  • Usage example: let [res, err] = await fs.mkdir('./my-new-folder');

• fs.mkdtemp

  • Typescript implementation: async (prefix: string, encoding?: Encoding)
  • Usage example: let [res, err] = await fs.mkdtemp('temp-');

• fs.open

  • 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

  • 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

  • Typescript implementation: async (path: string|Array<string>, options?: Encoding)
  • Usage example: let [res, err] = await fs.readFile('file.txt', 'utf8');

• fs.readdir

  • Typescript implementation: async (path: string|Array<string>, options?: object)
  • Usage example: let [res, err] = await fs.readdir('./my-directory');

• fs.readlink

  • Typescript implementation: async (path: string|Array<string>, options?: object|string)
  • Usage example: let [res, err] = await fs.readlink('symlinkToFile.txt');

• fs.realpath

  • Typescript implementation: async (path: string|Array<string>, options?: object)
  • Usage example: let [res, err] = await fs.realpath('./my-folder/../' );

• fs.rename

  • 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

  • Typescript implementation: async (path: string|Array<string>, options?: object)
  • Usage example: let [res, err] = await fs.rm('file.txt' );

• fs.rmdir

  • Typescript implementation: async (path: string|Array<string>, options?: object)
  • Usage example: let [res, err] = await fs.rmdir('./my-folder');

• fs.stat

  • Typescript implementation: async (path: string|Array<string>, options?: object)
  • Usage example: let [res, err] = await fs.stat('file.txt');

• fs.symlink

  • 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

  • Typescript implementation: async (path: string|Array<string>, len:number)
  • Usage example: let [res, err] = await fs.truncate('file.txt', 760);

• fs.unlink

  • Typescript implementation: async (path: string|Array<string>)
  • Usage example: let [res, err] = await fs.unlink('file-symlink.txt');

• fs.utimes

  • 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

  • Typescript implementation: async (filename: string|Array<string>, options?: object|string)
  • Usage example: let [res, err] = await fs.watch('file.txt', (ev, file) => { console.log("Watcher: " + file); });

• fs.writeFile

  • 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

• fs.__dirname

  • The equivalent to node’s __dirname usable within ES6 Module Syntax. Returns the directory name of the current module.
  • Implementation: path.dirname(fileURLToPath(import.meta.url));

• fs.__filename

  • The equivalent to node’s __filename usable within ES6 Module Syntax. Returns the filename of the code which is executed.
  • 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));