@augment-vir/node 31.51.0 → 31.52.0

package/dist/augments/fs/walk-files.d.ts

@@ -0,0 +1,50 @@
+import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { type Dirent, type PathLike } from 'node:fs';
+import { type FileHandle, type readFile } from 'node:fs/promises';
+/**
+ * Output from `readfile`, used in {@link WalkFilesParams}.
+ *
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type ReadFileOutput = Awaited<ReturnType<typeof readFile>>;
+/**
+ * Params for {@link walkFiles}.
+ *
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type WalkFilesParams = {
+    /** The directory to start walking files at. */
+    startDirPath: string;
+    /** Do something with a read file's contents. */
+    handleFileContents: (params: {
+        path: string;
+        contents: ReadFileOutput;
+    }) => MaybePromise<void>;
+} & PartialWithUndefined<{
+    /**
+     * Check if a file should be read or a directory should be traversed.
+     *
+     * If this is not provided, every file will be read and every directory will be traversed.
+     */
+    shouldRead: (params: {
+        path: string;
+        isDir: boolean;
+    }) => MaybePromise<boolean>;
+    /** Optional overrides for the internally used `node:fs/promises' imports. */
+    fs: {
+        readFile: (path: PathLike | FileHandle) => MaybePromise<ReadFileOutput>;
+        readdir: (path: PathLike, options: {
+            withFileTypes: true;
+        }) => MaybePromise<Pick<Dirent, 'name' | 'isDirectory'>[]>;
+    };
+}>;
+/**
+ * Walks files within a directory.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function walkFiles({ handleFileContents, shouldRead, startDirPath, fs, }: Readonly<WalkFilesParams>): Promise<void>;

package/dist/augments/fs/walk-files.js

@@ -0,0 +1,40 @@
+import { awaitedForEach } from '@augment-vir/common';
+import { join } from 'node:path';
+/**
+ * Walks files within a directory.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function walkFiles({ handleFileContents, shouldRead, startDirPath, fs, }) {
+    const { readFile, readdir } = {
+        /* node:coverage ignore next 2: dynamic imports are not branches. */
+        readFile: fs?.readFile || (await import('node:fs/promises')).readFile,
+        readdir: fs?.readdir || (await import('node:fs/promises')).readdir,
+    };
+    const children = await readdir(startDirPath, {
+        withFileTypes: true,
+    });
+    await awaitedForEach(children, async (file) => {
+        const childPath = join(startDirPath, file.name);
+        const isDir = file.isDirectory();
+        const willRead = shouldRead ? await shouldRead({ path: childPath, isDir }) : true;
+        if (!willRead) {
+            return;
+        }
+        if (isDir) {
+            await walkFiles({
+                startDirPath: childPath,
+                shouldRead,
+                handleFileContents,
+            });
+        }
+        else {
+            await handleFileContents({
+                path: childPath,
+                contents: await readFile(childPath),
+            });
+        }
+    });
+}

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './augments/fs/json.js';
 export * from './augments/fs/read-dir.js';
 export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
+export * from './augments/fs/walk-files.js';
 export * from './augments/fs/write.js';
 export * from './augments/npm/find-bin-path.js';
 export * from './augments/npm/npm-deps.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export * from './augments/fs/json.js';
 export * from './augments/fs/read-dir.js';
 export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
+export * from './augments/fs/walk-files.js';
 export * from './augments/fs/write.js';
 export * from './augments/npm/find-bin-path.js';
 export * from './augments/npm/npm-deps.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "31.51.0",
+    "version": "31.52.0",
     "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
     "keywords": [
         "augment",
@@ -38,8 +38,8 @@
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.51.0",
-        "@augment-vir/common": "^31.51.0",
+        "@augment-vir/assert": "^31.52.0",
+        "@augment-vir/common": "^31.52.0",
         "@date-vir/duration": "^8.0.0",
         "ansi-styles": "^6.2.3",
         "sanitize-filename": "^1.6.3",
@@ -49,8 +49,8 @@
         "typed-event-target": "^4.1.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.51.0",
-        "@types/node": "^24.10.0",
+        "@augment-vir/test": "^31.52.0",
+        "@types/node": "^24.10.1",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",

package/src/augments/fs/walk-files.ts

@@ -0,0 +1,88 @@
+import {awaitedForEach, type MaybePromise, type PartialWithUndefined} from '@augment-vir/common';
+import {type Dirent, type PathLike} from 'node:fs';
+import {type FileHandle, type readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+
+/**
+ * Output from `readfile`, used in {@link WalkFilesParams}.
+ *
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type ReadFileOutput = Awaited<ReturnType<typeof readFile>>;
+
+/**
+ * Params for {@link walkFiles}.
+ *
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type WalkFilesParams = {
+    /** The directory to start walking files at. */
+    startDirPath: string;
+    /** Do something with a read file's contents. */
+    handleFileContents: (params: {path: string; contents: ReadFileOutput}) => MaybePromise<void>;
+} & PartialWithUndefined<{
+    /**
+     * Check if a file should be read or a directory should be traversed.
+     *
+     * If this is not provided, every file will be read and every directory will be traversed.
+     */
+    shouldRead: (params: {path: string; isDir: boolean}) => MaybePromise<boolean>;
+    /** Optional overrides for the internally used `node:fs/promises' imports. */
+    fs: {
+        readFile: (path: PathLike | FileHandle) => MaybePromise<ReadFileOutput>;
+        readdir: (
+            path: PathLike,
+            options: {withFileTypes: true},
+        ) => MaybePromise<Pick<Dirent, 'name' | 'isDirectory'>[]>;
+    };
+}>;
+
+/**
+ * Walks files within a directory.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function walkFiles({
+    handleFileContents,
+    shouldRead,
+    startDirPath,
+    fs,
+}: Readonly<WalkFilesParams>): Promise<void> {
+    const {readFile, readdir} = {
+        /* node:coverage ignore next 2: dynamic imports are not branches. */
+        readFile: fs?.readFile || (await import('node:fs/promises')).readFile,
+        readdir: fs?.readdir || (await import('node:fs/promises')).readdir,
+    };
+
+    const children = await readdir(startDirPath, {
+        withFileTypes: true,
+    });
+
+    await awaitedForEach(children, async (file) => {
+        const childPath = join(startDirPath, file.name);
+        const isDir = file.isDirectory();
+
+        const willRead = shouldRead ? await shouldRead({path: childPath, isDir}) : true;
+
+        if (!willRead) {
+            return;
+        }
+
+        if (isDir) {
+            await walkFiles({
+                startDirPath: childPath,
+                shouldRead,
+                handleFileContents,
+            });
+        } else {
+            await handleFileContents({
+                path: childPath,
+                contents: await readFile(childPath),
+            });
+        }
+    });
+}

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './augments/fs/json.js';
 export * from './augments/fs/read-dir.js';
 export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
+export * from './augments/fs/walk-files.js';
 export * from './augments/fs/write.js';
 export * from './augments/npm/find-bin-path.js';
 export * from './augments/npm/npm-deps.js';