feat: support fs.exists async function

.github/workflows/nodejs.yml

@@ -11,7 +11,6 @@ jobs:
     name: Node.js
     uses: node-modules/github-actions/.github/workflows/node-test.yml@master
     with:
-      os: 'ubuntu-latest'
       version: '16, 18, 20, 22, 23'
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

README.md

@@ -5,6 +5,7 @@
 [![Test coverage][codecov-image]][codecov-url]
 [![npm download][download-image]][download-url]
 [![Node.js Version](https://img.shields.io/node/v/utility.svg?style=flat)](https://nodejs.org/en/download/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
 
 [npm-image]: https://img.shields.io/npm/v/utility.svg?style=flat-square
 [npm-url]: https://npmjs.org/package/utility

src/fs.ts

@@ -0,0 +1,17 @@
+import { Stats } from 'node:fs';
+import { stat } from 'node:fs/promises';
+
+/**
+ * Check if a file exists.
+ * Returns the file stats if it exists, or `false` if it doesn't.
+ */
+export async function exists(file: string): Promise<Stats | false> {
+  try {
+    return await stat(file);
+  } catch (err: any) {
+    if (err.code === 'ENOENT') {
+      return false;
+    }
+    throw err;
+  }
+}

src/index.ts

@@ -9,3 +9,4 @@ export * from './string.js';
 export * from './optimize.js';
 export * from './object.js';
 export * from './timeout.js';
+export * from './fs.js';

test/fs.test.ts

@@ -0,0 +1,54 @@
+import { strict as assert } from 'node:assert';
+import path from 'node:path';
+import { Stats } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import * as utility from '../src/index.js';
+import { exists } from '../src/index.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+describe('test/fs.test.ts', () => {
+  describe('exists()', () => {
+    it('should work', async () => {
+      let stats = await exists(__filename);
+      assert(stats instanceof Stats);
+      assert(stats.size > 0, 'stats.size > 0');
+      assert.equal(stats.isFile(), true);
+      assert.equal(stats.isDirectory(), false);
+
+      stats = await utility.exists(__dirname);
+      assert(stats instanceof Stats);
+      // assert(stats.size > 0, 'stats.size > 0');
+      assert.equal(stats.isDirectory(), true);
+      assert.equal(stats.isFile(), false);
+      assert.equal(await exists(__dirname + '/nonexistent'), false);
+    });
+
+    it('should throw error on Linux', async () => {
+      if (process.platform !== 'linux') {
+        return;
+      }
+      await assert.rejects(async () => {
+        await exists('/root/../../../../../etc/passwd');
+      }, (err: any) => {
+        // Error: EACCES: permission denied, stat '/root/../../../../../etc/passwd'
+        assert.equal(err.code, 'EACCES');
+        return true;
+      });
+    });
+
+    it.skip('should throw error on win32', async () => {
+      if (process.platform !== 'win32') {
+        return;
+      }
+      await assert.rejects(async () => {
+        await exists('C:\\Windows\\System32\\drivers\\etc\\hosts');
+      }, (err: any) => {
+        // Error: EACCES: permission denied, stat 'C:\Windows\System32\drivers\etc\hosts'
+        assert.equal(err.code, 'EPERM');
+        return true;
+      });
+    });
+  });
+});