@augment-vir/node 30.6.2 → 30.8.0

package/dist/augments/fs/dir-contents.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Nested contents read from a file system directory.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type DirContents = {
+    [Path in string]: string | DirContents;
+};
+/**
+ * Read all contents within a directory and store them in an object. Optionally recursive.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function readAllDirContents(dir: string, { recursive, excludeList, }: {
+    recursive?: boolean;
+    excludeList?: ReadonlyArray<string | RegExp> | undefined;
+}): Promise<DirContents>;
+/**
+ * Deletes and entire directory and resets it to the given contents.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function resetDirContents(rootDir: string, contents: Readonly<DirContents>): Promise<void>;
+/**
+ * Write {@link DirContents} to 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 writeDirContents(rootDir: string, contents: Readonly<DirContents>): Promise<void>;

package/dist/augments/fs/dir-contents.js

@@ -0,0 +1,77 @@
+import { check } from '@augment-vir/assert';
+import { getObjectTypedEntries } from '@augment-vir/common';
+import { readdir, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeFileAndDir } from './write.js';
+/**
+ * Read all contents within a directory and store them in an object. Optionally recursive.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function readAllDirContents(dir, { recursive = false, excludeList, }) {
+    const fileNames = (await readdir(dir)).sort();
+    const allFileContents = await Promise.all(fileNames.map(async (fileName) => {
+        const filePath = join(dir, fileName);
+        if (excludeList?.some((excludeItem) => {
+            if (check.isString(excludeItem)) {
+                return filePath.includes(excludeItem);
+            }
+            else {
+                return filePath.match(excludeItem);
+            }
+        })) {
+            return undefined;
+        }
+        const isFile = (await stat(filePath)).isFile();
+        const contents = isFile
+            ? (await readFile(filePath)).toString()
+            : recursive
+                ? await readAllDirContents(filePath, { recursive, excludeList })
+                : undefined;
+        if (check.isObject(contents) && !Object.keys(contents).length) {
+            return undefined;
+        }
+        return contents;
+    }));
+    return fileNames.reduce((accum, fileName, index) => {
+        if (allFileContents[index] != undefined) {
+            const fileContents = allFileContents[index];
+            accum[fileName] = fileContents;
+        }
+        return accum;
+    }, {});
+}
+/**
+ * Deletes and entire directory and resets it to the given contents.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function resetDirContents(rootDir, contents) {
+    await rm(rootDir, {
+        force: true,
+        recursive: true,
+    });
+    await writeDirContents(rootDir, contents);
+}
+/**
+ * Write {@link DirContents} to 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 writeDirContents(rootDir, contents) {
+    await Promise.all(getObjectTypedEntries(contents).map(async ([relativePath, content,]) => {
+        const fullPath = join(rootDir, relativePath);
+        if (check.isString(content)) {
+            await writeFileAndDir(fullPath, content);
+        }
+        else {
+            await writeDirContents(fullPath, content);
+        }
+    }));
+}

package/dist/augments/terminal/relevant-args.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Input for extractRelevantArgs.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type RelevantArgsInput = {
+    /** Raw arguments passed to the CLI. Typically this will simply be process.argv. */
+    rawArgs: ReadonlyArray<string>;
+    /**
+     * Executable bin name for your script. This should be the "bin" name in your package.json, or
+     * simply your package name if you have no custom bin name defined.
+     *
+     * See https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin for details on the bin
+     * field of package.json
+     */
+    binName: string | undefined;
+    /**
+     * The name or path of your script file that will be executed via the CLI. This should almost
+     * always simply be __filename in CJS or `import.meta.filename` in ESM.
+     */
+    fileName: string;
+    /**
+     * If set to true, this function with throw an error if the given file or bin name was not found
+     * in the given arguments list.
+     */
+    errorIfNotFound?: boolean | undefined;
+};
+/**
+ * Trims arguments list to remove all arguments that take place before the script's file name or
+ * executable bin name.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @example
+ *
+ * ```ts
+ * extractRelevantArgs({
+ *     rawArgs: [
+ *         'npx',
+ *         'ts-node',
+ *         './my-script.ts',
+ *         'arg1',
+ *         '--arg2',
+ *     ], // typically will be process.argv
+ *     binName: 'my-script', // should be your package.json "bin" property name, can be undefined
+ *     fileName: 'my-script.ts', // should be __filename from the script that will be executed
+ * });
+ * // will output ['arg1', '--arg2']
+ * ```
+ *
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function extractRelevantArgs({ rawArgs, binName, fileName, errorIfNotFound, }: Readonly<RelevantArgsInput>): string[];

package/dist/augments/terminal/relevant-args.js

@@ -0,0 +1,49 @@
+import { basename } from 'node:path';
+/**
+ * Trims arguments list to remove all arguments that take place before the script's file name or
+ * executable bin name.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @example
+ *
+ * ```ts
+ * extractRelevantArgs({
+ *     rawArgs: [
+ *         'npx',
+ *         'ts-node',
+ *         './my-script.ts',
+ *         'arg1',
+ *         '--arg2',
+ *     ], // typically will be process.argv
+ *     binName: 'my-script', // should be your package.json "bin" property name, can be undefined
+ *     fileName: 'my-script.ts', // should be __filename from the script that will be executed
+ * });
+ * // will output ['arg1', '--arg2']
+ * ```
+ *
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function extractRelevantArgs({ rawArgs, binName, fileName, errorIfNotFound, }) {
+    const baseFileName = basename(fileName);
+    if (!baseFileName) {
+        throw new Error(`Given file name produced no base file name (with path.basename()): '${fileName}'`);
+    }
+    const lastIrrelevantArgIndex = rawArgs.findIndex((arg) => {
+        const baseArgName = basename(arg);
+        const matchesFileName = baseArgName === baseFileName;
+        const matchesBinName = binName ? baseArgName === binName : false;
+        return matchesFileName || matchesBinName;
+    });
+    if (lastIrrelevantArgIndex === -1) {
+        if (errorIfNotFound) {
+            throw new Error('Failed to find position of file or bin name in provided args list.');
+        }
+        else {
+            return [...rawArgs];
+        }
+    }
+    else {
+        return rawArgs.slice(lastIrrelevantArgIndex + 1);
+    }
+}

package/dist/augments/terminal/run-cli-script.d.ts

@@ -0,0 +1,22 @@
+/** This file cannot be tested because it calls `process.exit`. */
+/**
+ * A map of file extensions to their known runners for {@link runCliScript}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare const ExtensionToRunner: Record<string, string>;
+/**
+ * Runs a script path as if it had been run directly, as much as possible.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function runCliScript(path: string, 
+/**
+ * This should be the bin name of the package that is calling this function. Set to `undefined`
+ * if there isn't one.
+ */
+binName: string | undefined): Promise<void>;

package/dist/augments/terminal/run-cli-script.js

@@ -0,0 +1,49 @@
+/* node:coverage disable */
+/** This file cannot be tested because it calls `process.exit`. */
+import { extname } from 'node:path';
+import { extractRelevantArgs } from './relevant-args.js';
+import { runShellCommand } from './shell.js';
+/**
+ * A map of file extensions to their known runners for {@link runCliScript}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export const ExtensionToRunner = {
+    '.ts': 'tsx',
+    '.js': 'node',
+    '.sh': 'bash',
+};
+/**
+ * Runs a script path as if it had been run directly, as much as possible.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function runCliScript(path, 
+/**
+ * This should be the bin name of the package that is calling this function. Set to `undefined`
+ * if there isn't one.
+ */
+binName) {
+    const args = extractRelevantArgs({
+        rawArgs: process.argv,
+        binName,
+        fileName: import.meta.filename,
+    });
+    const extension = extname(path);
+    const runner = ExtensionToRunner[extension];
+    if (!runner) {
+        throw new Error("No runner configured for file extension '${extension}' in '${path}'");
+    }
+    const results = await runShellCommand([
+        runner,
+        path,
+        ...args,
+    ].join(' '), {
+        hookUpToConsole: true,
+    });
+    process.exit(results.exitCode || 0);
+}

package/dist/file-paths.mock.d.ts

@@ -2,6 +2,7 @@ export declare const monoRepoDirPath: string;
 export declare const notCommittedDirPath: string;
 export declare const nodePackageDir: string;
 export declare const testFilesDir: string;
+export declare const dirContentsTestDir: string;
 export declare const longRunningFilePath: string;
 export declare const longRunningFileWithStderr: string;
 export declare const workspaceQueryDir: string;

package/dist/file-paths.mock.js

@@ -4,6 +4,7 @@ export const notCommittedDirPath = join(monoRepoDirPath, '.not-committed');
 export const nodePackageDir = dirname(import.meta.dirname);
 export const testFilesDir = join(nodePackageDir, 'test-files');
 const longRunningFileDir = join(testFilesDir, 'long-running-test-file');
+export const dirContentsTestDir = join(testFilesDir, 'dir-contents-test');
 export const longRunningFilePath = join(longRunningFileDir, 'long-running-file.ts');
 export const longRunningFileWithStderr = join(longRunningFileDir, 'long-running-file-with-stderr.ts');
 export const workspaceQueryDir = join(testFilesDir, 'workspace-query');

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './augments/docker.js';
+export * from './augments/fs/dir-contents.js';
 export * from './augments/fs/download.js';
 export * from './augments/fs/json.js';
 export * from './augments/fs/read-dir.js';
@@ -13,4 +14,6 @@ export * from './augments/path/os-path.js';
 export * from './augments/path/root.js';
 export * from './augments/prisma.js';
 export * from './augments/terminal/question.js';
+export * from './augments/terminal/relevant-args.js';
+export * from './augments/terminal/run-cli-script.js';
 export * from './augments/terminal/shell.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './augments/docker.js';
+export * from './augments/fs/dir-contents.js';
 export * from './augments/fs/download.js';
 export * from './augments/fs/json.js';
 export * from './augments/fs/read-dir.js';
@@ -13,4 +14,6 @@ export * from './augments/path/os-path.js';
 export * from './augments/path/root.js';
 export * from './augments/prisma.js';
 export * from './augments/terminal/question.js';
+export * from './augments/terminal/relevant-args.js';
+export * from './augments/terminal/run-cli-script.js';
 export * from './augments/terminal/shell.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "30.6.2",
+    "version": "30.8.0",
     "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
     "keywords": [
         "augment",
@@ -37,16 +37,16 @@
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^30.6.2",
-        "@augment-vir/common": "^30.6.2",
-        "@date-vir/duration": "^6.0.1",
+        "@augment-vir/assert": "^30.8.0",
+        "@augment-vir/common": "^30.8.0",
+        "@date-vir/duration": "^7.0.1",
         "ansi-styles": "^6.2.1",
         "terminate": "^2.8.0",
         "type-fest": "^4.26.1",
         "typed-event-target": "^4.0.2"
     },
     "devDependencies": {
-        "@augment-vir/test": "^30.6.2",
+        "@augment-vir/test": "^30.8.0",
         "@prisma/client": "^5.22.0",
         "@types/node": "^22.9.0",
         "@web/dev-server-esbuild": "^1.0.3",