async-file-tried 1.0.0

package/.github/workflows/coveralls.yml

@@ -0,0 +1,26 @@
+name: Test and Coverage
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main  # Adjust the branch name based on your default branch
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run tests and collect coverage
+        run: npm run coverage
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v2
+        with:
+          token: ${{ secrets.FS_TOKEN }}

package/.github/workflows/node.js.yml

@@ -0,0 +1,30 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Node.js CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [16.x, 18.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build --if-present

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Florian Walzel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# 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, more concise code by getting a smoothed response. TypeScript supported.
+
+## License
+
+Copyright (c) 2023 Florian Walzel,
+MIT License
+
+## Install
+
+```sh
+npm install async-file-tried
+```
+
+Import:
+
+```javascript
+import * as 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 all path arguments 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 file string will be composed automatically.
+
+## API
+
+### FS Function List
+
+- [fs.access](https://nodejs.org/api/fs.html#fspromisesaccesspath-mode)
+  + 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](https://nodejs.org/api/fs.html#fspromisesappendfilepath-data-options)
+  + 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](https://nodejs.org/api/fs.html#filehandlechmodmode)
+  + Typescript implementation: `async (path: string|Array<string>, mode?: number|string)`
+  + Usage example: `let [res, err] = await fs.chmod('file.txt', '755');`
+
+- [fs.chown](https://nodejs.org/api/fs.html#filehandlechownuid-gid)
+  + 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](https://nodejs.org/api/fs.html#fspromisescopyfilesrc-dest-mode)
+  + 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](https://nodejs.org/api/fs.html#fspromisescpsrc-dest-options)
+  + 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](https://nodejs.org/api/fs.html#fspromiseslchmodpath-mode)
+  + Typescript implementation: `async (path: string|Array<string>, mode?: number|string)`
+  + Usage example: ``
+
+- [fs.lchown](https://nodejs.org/api/fs.html#fspromiseslchownpath-uid-gid)
+  + 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](https://nodejs.org/api/fs.html#fspromiseslinkexistingpath-newpath)
+  + 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](https://nodejs.org/api/fs.html#fspromiseslstatpath-options)
+   + Typescript implementation: `async (path: string|Array<string>, options?: object)`
+   + Usage example: `let [res, err] = await fs.lstat('symlinkToFile.txt');`
+
+- [fs.lutimes](https://nodejs.org/api/fs.html#fspromiseslutimespath-atime-mtime)
+  + 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](https://nodejs.org/api/fs.html#fspromisesmkdirpath-options)
+  + Typescript implementation: `async (path: string|Array<string>, options?: number|string)`
+  + Usage example: `let [res, err] = await fs.mkdir('./my-new-folder');`
+
+- [fs.mkdtemp](https://nodejs.org/api/fs.html#fspromisesmkdtempprefix-options)
+  + Typescript implementation: `async (prefix: string, encoding?: Encoding)`
+  + Usage example: `let [res, err] = await fs.mkdtemp('temp-');`
+
+- [fs.open](https://nodejs.org/api/fs.html#fspromisesopenpath-flags-mode)
+  + 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](https://nodejs.org/api/fs.html#fspromisesopendirpath-options)
+  + 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](https://nodejs.org/api/fs.html#filehandlereadfileoptions)
+  + Typescript implementation: `async (path: string|Array<string>, options?: Encoding)`
+  + Usage example: `let [res, err] = await fs.readFile('file.txt', 'utf8');`
+
+- [fs.readdir](https://nodejs.org/api/fs.html#filehandlereadfileoptions)
+  + Typescript implementation: `async (path: string|Array<string>, options?: object)`
+  + Usage example: `let [res, err] = await fs.readdir('./my-directory');`
+
+- [fs.readlink](https://nodejs.org/api/fs.html#fspromisesreadlinkpath-options)
+  + Typescript implementation: `async (path: string|Array<string>, options?: object|string)`
+  + Usage example: `let [res, err] = await fs.readlink('symlinkToFile.txt');`
+
+- [fs.realpath](https://nodejs.org/api/fs.html#fspromisesrealpathpath-options)
+  + Typescript implementation: `async (path: string|Array<string>, options?: object)`
+  + Usage example: `let [res, err] = await fs.realpath('./my-folder/../' );`
+
+- [fs.rename](https://nodejs.org/api/fs.html#fspromisesrenameoldpath-newpath)
+  + 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](https://nodejs.org/api/fs.html#fspromisesrenameoldpath-newpath)
+  + Typescript implementation: `async (path: string|Array<string>, options?: object)`
+  + Usage example: `let [res, err] = await fs.rm('file.txt' );`
+
+- [fs.rmdir](https://nodejs.org/api/fs.html#fspromisesrmdirpath-options)
+  + Typescript implementation: `async (path: string|Array<string>, options?: object)`
+  + Usage example: `let [res, err] = await fs.rmdir('./my-folder');`
+
+- [fs.stat](https://nodejs.org/api/fs.html#fspromisesstatpath-options)
+  + Typescript implementation: `async (path: string|Array<string>, options?: object)`
+  + Usage example: `let [res, err] = await fs.stat('file.txt');`
+
+- [fs.symlink](https://nodejs.org/api/fs.html#fspromisessymlinktarget-path-type)
+  + 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](https://nodejs.org/api/fs.html#fspromisestruncatepath-len)
+  + Typescript implementation: `async (path: string|Array<string>, len:number)`
+  + Usage example: `let [res, err] = await fs.truncate('file.txt', 760);`
+
+- [fs.unlink](https://nodejs.org/api/fs.html#fspromisesunlinkpath)
+  + Typescript implementation: `async (path: string|Array<string>)`
+  + Usage example: `let [res, err] = await fs.unlink('file-symlink.txt');`
+
+- [fs.utimes](https://nodejs.org/api/fs.html#fspromisesutimespath-atime-mtime)
+  + 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](https://nodejs.org/api/fs.html#fspromiseswatchfilename-options)
+  + 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](https://nodejs.org/api/fs.html#fspromiseswritefilefile-data-options)
+  + 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](https://nodejs.org/api/fs.html#fspromisesconstants)
+  + The FS [constants](https://nodejs.org/api/fs.html#fs-constants) object
+
+- [fs.__dirname](https://nodejs.org/docs/latest/api/globals.html#__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](https://nodejs.org/docs/latest/api/globals.html#__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.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 and will stringify and write it out.
+  + Typescript implementation: `async (path: string|Array<string>, data: Object, options?: Encoding)`
+  + Usage example: `let [res, err] = await fs.writeJson('./test/static-testfiles/test.json', { key : "value" });`

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/// <reference types="node" />
+import * as fsNormal from 'node:fs';
+import { CopyOptions } from "node:fs";
+/****************************************
+ * Export
+ ****************************************/
+export type Encoding = 'ascii' | 'base64' | 'binary' | 'hex' | 'ucs2' | 'utf16le' | 'utf8';
+export type Flags = 'r' | 'r+' | 'rs' | 'rs+' | 'w' | 'wx' | 'w+' | 'wx+' | 'a' | 'ax' | 'a+' | 'ax+';
+declare const fs: {
+    access: (path: string | Array<string>, mode?: number | string) => Promise<any[]>;
+    appendFile: (path: string | Array<string>, data: any, options?: {
+        encoding?: Encoding;
+        mode?: number | string;
+        flag?: Flags;
+    }) => Promise<any[]>;
+    chmod: (path: string | Array<string>, mode?: number | string) => Promise<any[]>;
+    chown: (path: string | Array<string>, uid: number, gid: number) => Promise<any[]>;
+    copyFile: (srcPath: string | Array<string>, destPath: string | Array<string>, flags?: number) => Promise<any[]>;
+    cp: (srcPath: string | Array<string>, destPath: string | Array<string>, options?: CopyOptions) => Promise<any[]>;
+    lchmod: (path: string | Array<string>, mode?: number | string) => Promise<any[]>;
+    lchown: (path: string | Array<string>, uid: number, gid: number) => Promise<any[]>;
+    link: (existingPath: string | Array<string>, newPath: string | Array<string>) => Promise<any[]>;
+    lstat: (path: string | Array<string>, options?: object) => Promise<any[]>;
+    lutimes: (path: string | Array<string>, atime: Date | number, mtime: Date | number) => Promise<any[]>;
+    mkdir: (path: string | Array<string>, options?: number | string) => Promise<any[]>;
+    mkdtemp: (prefix: string, encoding?: Encoding) => Promise<any[]>;
+    open: (path: string | Array<string>, flags?: Flags, mode?: number | string) => Promise<any[]>;
+    opendir: (path: string | Array<string>, options?: object) => Promise<any[]>;
+    readFile: (path: string | Array<string>, options?: Encoding) => Promise<any[]>;
+    readdir: (path: string | Array<string>, options?: object) => Promise<any[]>;
+    readlink: (path: string | Array<string>, options?: object | string) => Promise<any[]>;
+    realpath: (path: string | Array<string>, options?: object) => Promise<any[]>;
+    rename: (oldPath: string | Array<string>, newPath: string | Array<string>) => Promise<any[]>;
+    rm: (path: string | Array<string>, options?: object) => Promise<any[]>;
+    rmdir: (path: string | Array<string>, options?: object) => Promise<any[]>;
+    stat: (path: string | Array<string>, options?: object) => Promise<any[]>;
+    symlink: (target: string | Array<string>, path: string | Array<string>, type?: string) => Promise<any[]>;
+    truncate: (path: string | Array<string>, len: number) => Promise<any[]>;
+    unlink: (path: string | Array<string>) => Promise<any[]>;
+    utimes: (path: string | Array<string>, atime: number | string | Date, mtime: number | string | Date) => Promise<any[]>;
+    watch: (filename: string | Array<string>, options?: object | string) => Promise<any[]>;
+    writeFile: (path: string | Array<string>, data: any, options?: Encoding) => Promise<any[]>;
+    constants: typeof fsNormal.constants;
+    __dirname: string;
+    __filename: string;
+    asyncHandler: (func: Function) => Promise<any[]>;
+    readJson: (path: string | Array<string>, options?: Encoding) => Promise<any[]>;
+    writeJson: (path: string | Array<string>, data: Object, options?: Encoding) => Promise<any[]>;
+};
+export default fs;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}