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.

!Node.js Version

Install

``sh
npm install async-file-tried
`

Import:

`javascript
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:

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

... instead of:

`javascript
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.:

`javascript
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)

$3

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

Typescript implementation:
`typescript
async (path: string|Array, mode?: number|string)
`

Usage example:
`javascript
let [res, err] = await fs.access('file.txt', fs.constants.R_OK);
`

---

$3

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

Typescript implementation:
`typescript
async (path: string|Array, data: any, options?: { encoding?: Encoding; mode?: number|string; flag?: Flags; })
`

Usage example:
`javascript
let [res, err] = await fs.appendFile('file.txt', 'foo');
`

---

$3

Changes the permissions of a file or directory.

Typescript implementation:
`typescript
async (path: string|Array, mode?: number|string)
`

Usage example:
`javascript
let [res, err] = await fs.chmod('file.txt', '755');
`

---

$3

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

Typescript implementation:
`typescript
async (path: string|Array, uid: number, gid: number)
`

Usage example:
`javascript
let [res, err] = await fs.chown('file.txt', 1541, 999);
`

---

$3

Copies a file from one location to another.

Typescript implementation:
`typescript
async (srcPath: string|Array, destPath: string|Array, flags?: number)
`

Usage example:
`javascript
let [res, err] = await fs.copyFile('file.txt', 'file-copy.txt');
`

---

$3

Recursively copies files and directories from one location to another.

Typescript implementation:
`typescript
async (srcPath: string|Array, destPath: string|Array)
`

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

---

$3

Changes the permissions of a symbolic link.

Typescript implementation:
`typescript
async (path: string|Array, mode?: number|string)
`

Usage example:
`javascript
let [res, err] = await fs.lchmod('symlink.txt', '755');
`

---

$3

Changes the ownership of a symbolic link.

Typescript implementation:
`typescript
async (path: string|Array, uid: number, gid: number)
`

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

---

$3

Creates a new hard link to an existing file.

Typescript implementation:
`typescript
async (existingPath: string|Array, newPath: string|Array)
`

Usage example:
`javascript
let [res, err] = await fs.link('file.txt', 'file-hard-link.txt');
`

---

$3

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

Typescript implementation:
`typescript
async (path: string|Array, options?: object)
`

Usage example:
`javascript
let [res, err] = await fs.lstat('symlinkToFile.txt');
`

---

$3

Changes the access and modification times of a symbolic link.

Typescript implementation:
`typescript
async (path: string|Array, atime: Date|number, mtime: Date|number)
`

Usage example:
`javascript
let [res, err] = await fs.lutimes('file.txt', new Date(), new Date());
`

---

$3

Creates a new directory at the specified path.

Typescript implementation:
`typescript
async (path: string|Array, options?: number|string)
`

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

---

$3

Creates a uniquely named temporary directory.

Typescript implementation:
`typescript
async (prefix: string, encoding?: Encoding)
`

Usage example:
`javascript
let [res, err] = await fs.mkdtemp('temp-');
`

---

$3

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

Typescript implementation:
`typescript
async (path: string|Array, flags?: Flags, mode?: number|string)
`

Usage example:
`javascript
let [res, err] = await fs.open('file.txt', 'r');
`

---

$3

Opens a directory for reading and returns a directory handle.

Typescript implementation:
`typescript
async (path: string|Array, flags?: Flags, mode?: number|string)
`

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

---

$3

Reads the contents of a file into memory.

Typescript implementation:
`typescript
async (path: string|Array, options?: Encoding)
`

Usage example:
`javascript
let [res, err] = await fs.readFile('file.txt', 'utf8');
`

---

$3

Reads the contents of a directory.

Typescript implementation:
`typescript
async (path: string|Array, options?: object)
`

Usage example:
`javascript
let [res, err] = await fs.readdir('./my-directory');
`

---

$3

Reads the value of a symbolic link.

Typescript implementation:
`typescript
async (path: string|Array, options?: object|string)
`

Usage example:
`javascript
let [res, err] = await fs.readlink('symlinkToFile.txt');
`

---

$3

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

Typescript implementation:
`typescript
async (path: string|Array, options?: object)
`

Usage example:
`javascript
let [res, err] = await fs.realpath('./my-folder/../');
`

---

$3

Renames or moves a file or directory.

Typescript implementation:
`typescript
async (oldPath: string|Array, newPath: string|Array)
`

Usage example:
`javascript
let [res, err] = await fs.rename('old.txt', 'new.txt');
`

---

$3

Removes files or directories.

Typescript implementation:
`typescript
async (path: string|Array, options?: object)
`

Usage example:
`javascript
let [res, err] = await fs.rm('file.txt');
`

---

$3

Removes a directory.

Typescript implementation:
`typescript
async (path: string|Array, options?: object)
`

Usage example:
`javascript
let [res, err] = await fs.rmdir('./my-folder');
`

---

$3

Retrieves information about a file or directory.

Typescript implementation:
`typescript
async (path: string|Array, options?: object)
`

Usage example:
`javascript
let [res, err] = await fs.stat('file.txt');
`

---

$3

Creates a symbolic link to a target file or directory.

Typescript implementation:
`typescript
async (target: string|Array, path: string|Array, type?: string)
`

Usage example:
`javascript
let [res, err] = await fs.symlink('file.txt', 'file-symlink.txt', 'file');
`

---

$3

Truncates a file to a specified length.

Typescript implementation:
`typescript
async (path: string|Array, len: number)
`

Usage example:
`javascript
let [res, err] = await fs.truncate('file.txt', 760);
`

---

$3

Removes (deletes) a file.

Typescript implementation:
`typescript
async (path: string|Array)
`

Usage example:
`javascript
let [res, err] = await fs.unlink('file-symlink.txt');
`

---

$3

Changes the access and modification times of a file.

Typescript implementation:
`typescript
async (path: string|Array, atime: number|string|Date, mtime: number|string|Date)
`

Usage example:
`javascript
let [res, err] = await fs.utimes('file.txt', new Date(), new Date());
`

---

$3

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

Typescript implementation:
`typescript
async (filename: string|Array, options?: BufferEncoding | "buffer")
`

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

---

$3

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

Typescript implementation:
`typescript
async (path: string|Array, data: any, options?: Encoding)
`

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

---

$3

$3

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

---

$3

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

Implementation:
`javascript
path.dirname(fileURLToPath(import.meta.url));
`

---

$3

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

Implementation:
`javascript
fileURLToPath(import.meta.url);
`

---




$3

---

$3


Checks if a file or directory exists, returns boolean.
Typescript implementation:
`typescript
async (path: string|Array)
`
Usage example:
`javascript
let res = await fs.exists('file.txt');
`

---

$3

Checks if a directory exists, creates it if not.
Typescript implementation:
`typescript
async (dir: string|Array)
`
Usage example:
`javascript
let res = await fs.ensureDir('./my-dir');
`

---

$3

Reads a JSON file and returns it as parsed Javascript object.
Typescript implementation:
`typescript
async (path: string|Array, options?: Encoding)
`
Usage example:
`javascript
let [res, err] = await fs.readJson('my.json');
`

---

$3

Expects a Javascript object, will stringify it and write it out as JSON.
Typescript implementation:
`typescript
async (path: string|Array, data: Object, options?: Encoding)
`
Usage example:
`javascript
let [res, err] = await fs.writeJson('my.json', { key : "value" });
`

---

$3

Reads a text file as UTF8.
Typescript implementation:
`typescript
async (path: string|Array)
`
Usage example:
`javascript
let [res, err] = await fs.readTextFile('file.txt');
`

---

$3

Writes out a String as UTF8.
Typescript implementation:
`typescript
async (path: string|Array, data: string)
`
Usage example:
`javascript
let [res, err] = await fs.writeTextFile('file.txt', 'Hello world!');
`

---

$3

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.

$3

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:
`typescript
asyncHandler = async (func: Function)
`
Usage example:
`javascript
let [res, err] = await fs.asyncHandler(() => await myCustomFunction(someParam));
`
---

Run tests

`sh
npm test
``

License

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