@augment-vir/node 31.73.5 → 32.1.0

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

@@ -1,11 +1,14 @@
 import { readdir, stat } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-async function internalReadDirPathsRecursive(dirPath, basePath) {
+async function internalReadDirPathsRecursive({ dirPath, basePath, }) {
     const dirContents = await readdir(dirPath);
     const recursiveContents = (await Promise.all(dirContents.map(async (fileName) => {
         const filePath = join(dirPath, fileName);
         if ((await stat(filePath)).isDirectory()) {
-            return internalReadDirPathsRecursive(filePath, basePath);
+            return internalReadDirPathsRecursive({
+                dirPath: filePath,
+                basePath,
+            });
         }
         else {
             return relative(basePath, filePath);
@@ -22,7 +25,10 @@ async function internalReadDirPathsRecursive(dirPath, basePath) {
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export async function readDirRecursive(dirPath) {
-    return await internalReadDirPathsRecursive(dirPath, dirPath);
+    return await internalReadDirPathsRecursive({
+        dirPath,
+        basePath: dirPath,
+    });
 }
 /**
  * Reads all files within a single directory and filters them by the given extension or extensions.

package/dist/augments/path/contains.d.ts

@@ -6,11 +6,15 @@ import { type PartialWithUndefined } from '@augment-vir/common';
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export declare function doesPathContain(potentialParentPath: string, potentialChildPath: string, options?: PartialWithUndefined<{
-    /**
-     * Set this to `true` to return `true` if the paths are exactly equal.
-     *
-     * @default false
-     */
-    allowSelf: boolean;
+export declare function doesPathContain({ potentialParentPath, potentialChildPath, options, }: Readonly<{
+    potentialParentPath: string;
+    potentialChildPath: string;
+    options?: PartialWithUndefined<{
+        /**
+         * Set this to `true` to return `true` if the paths are exactly equal.
+         *
+         * @default false
+         */
+        allowSelf: boolean;
+    }>;
 }>): boolean;

package/dist/augments/path/contains.js

@@ -7,7 +7,7 @@ import { isOperatingSystem, OperatingSystem } from '../os/operating-system.js';
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export function doesPathContain(potentialParentPath, potentialChildPath, options = {}) {
+export function doesPathContain({ potentialParentPath, potentialChildPath, options = {}, }) {
     if (!potentialParentPath || !potentialChildPath) {
         return false;
     }

package/dist/augments/path/resolve-import.d.ts

@@ -8,4 +8,7 @@
  * @returns `undefined` if no matches are found.
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export declare function resolveImportPath(importerFilePath: string, importPath: string): string | undefined;
+export declare function resolveImportPath({ importerFilePath, importPath, }: Readonly<{
+    importerFilePath: string;
+    importPath: string;
+}>): string | undefined;

package/dist/augments/path/resolve-import.js

@@ -15,10 +15,14 @@ import { replaceWithWindowsPathIfNeeded } from './os-path.js';
  * @returns `undefined` if no matches are found.
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export function resolveImportPath(importerFilePath, importPath) {
+export function resolveImportPath({ importerFilePath, importPath, }) {
     const foundTsconfig = readTsconfig(importerFilePath);
     const mappedImportPath = foundTsconfig
-        ? mapImportPath(importPath, foundTsconfig.tsconfig, foundTsconfig.path)
+        ? mapImportPath({
+            importPath,
+            tsconfig: foundTsconfig.tsconfig,
+            tsconfigPath: foundTsconfig.path,
+        })
         : importPath;
     if (mappedImportPath.startsWith(sep) || mappedImportPath.startsWith('/')) {
         /** Absolute import */
@@ -56,7 +60,7 @@ function mapFilePath(path) {
     }
     return path;
 }
-function mapImportPath(importPath, tsconfig, tsconfigPath) {
+function mapImportPath({ importPath, tsconfig, tsconfigPath, }) {
     const paths = tsconfig.options.paths;
     if (!paths) {
         return importPath;

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

@@ -16,11 +16,8 @@ export declare const ExtensionToRunner: Record<string, string | {
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export declare function runCliScript(scriptPath: string, 
-/** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
-cliScriptFilePath: 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>;
+export declare function runCliScript({ scriptPath, cliScriptFilePath, binName, }: Readonly<{
+    scriptPath: string;
+    cliScriptFilePath: string;
+    binName: string | undefined;
+}>): Promise<void>;

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

@@ -27,14 +27,7 @@ export const ExtensionToRunner = {
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export async function runCliScript(scriptPath, 
-/** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
-cliScriptFilePath, 
-/**
- * This should be the bin name of the package that is calling this function. Set to `undefined`
- * if there isn't one.
- */
-binName) {
+export async function runCliScript({ scriptPath, cliScriptFilePath, binName, }) {
     const args = extractRelevantArgs({
         rawArgs: process.argv,
         binName,

package/dist/augments/terminal/shell.d.ts

@@ -126,6 +126,20 @@ export declare class ShellTarget extends ListenTarget<ShellStdoutEvent | ShellSt
     readonly childProcess: ChildProcess;
     constructor(childProcess: ChildProcess);
 }
+/**
+ * Options for {@link streamShellCommand}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type StreamShellCommandOptions = PartialWithUndefined<{
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    shell: string;
+    /** Automatically hook up stdout and stderr printing to the caller's console methods. */
+    hookUpToConsole: boolean;
+}>;
 /**
  * Runs a shell command and returns a {@link ShellTarget} instance for directly hooking into shell
  * events. This allows instant reactions to shell events but in a less convenient API compared to
@@ -137,7 +151,7 @@ export declare class ShellTarget extends ListenTarget<ShellStdoutEvent | ShellSt
  * @see
  * - {@link runShellCommand}: a higher level and more succinct way of running a shell command.
  */
-export declare function streamShellCommand(command: string, cwd?: string, shell?: string, env?: NodeJS.ProcessEnv, hookUpToConsole?: boolean): ShellTarget;
+export declare function streamShellCommand(command: string, { cwd, env, shell, hookUpToConsole, }?: StreamShellCommandOptions): ShellTarget;
 /**
  * Options for {@link runShellCommand}.
  *
@@ -145,19 +159,14 @@ export declare function streamShellCommand(command: string, cwd?: string, shell?
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export type RunShellCommandOptions = {
-    cwd?: string | undefined;
-    env?: NodeJS.ProcessEnv | undefined;
-    shell?: string | undefined;
-    /** Automatically hook up stdout and stderr printing to the caller's console methods. */
-    hookUpToConsole?: boolean | undefined;
+export type RunShellCommandOptions = StreamShellCommandOptions & PartialWithUndefined<{
     /** @default false */
-    rejectOnError?: boolean | undefined;
+    rejectOnError: boolean;
     /** Callback to call whenever the shell logs to stdout. */
-    stdoutCallback?: (stdout: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
+    stdoutCallback: (stdout: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
     /** Callback to call whenever the shell logs to stderr. */
-    stderrCallback?: (stderr: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
-};
+    stderrCallback: (stderr: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
+}>;
 /**
  * Runs a shell command and returns its output.
  *

package/dist/augments/terminal/shell.js

@@ -64,7 +64,7 @@ export class ShellTarget extends ListenTarget {
  * @see
  * - {@link runShellCommand}: a higher level and more succinct way of running a shell command.
  */
-export function streamShellCommand(command, cwd, shell = 'bash', env = process.env, hookUpToConsole = false) {
+export function streamShellCommand(command, { cwd, env = process.env, shell = 'bash', hookUpToConsole = false, } = {}) {
     const stdio = hookUpToConsole ? [process.stdin] : undefined;
     const childProcess = spawn(command, {
         shell,
@@ -109,7 +109,9 @@ export function streamShellCommand(command, cwd, shell = 'bash', env = process.e
         const exitCode = inputExitCode ?? undefined;
         const exitSignal = inputExitSignal ?? undefined;
         if ((exitCode !== undefined && exitCode !== 0) || exitSignal !== undefined) {
-            const execException = new Error(`Command failed: ${command}`);
+            const execException = Object.assign(new Error(`Command failed: ${command}`), {
+                cmd: command,
+            });
             if (exitCode != undefined) {
                 execException.code = exitCode;
             }
@@ -117,7 +119,6 @@ export function streamShellCommand(command, cwd, shell = 'bash', env = process.e
             if (exitSignal != undefined) {
                 execException.signal = exitSignal;
             }
-            execException.cmd = command;
             execException.killed = childProcess.killed;
             execException.cwd = cwd;
             shellTarget.dispatch(new ShellErrorEvent({
@@ -147,7 +148,12 @@ export async function runShellCommand(command, options = {}) {
         let stdout = '';
         let stderr = '';
         const errors = [];
-        const shellTarget = streamShellCommand(command, options.cwd, options.shell, options.env, options.hookUpToConsole);
+        const shellTarget = streamShellCommand(command, {
+            cwd: options.cwd,
+            shell: options.shell,
+            env: options.env,
+            hookUpToConsole: options.hookUpToConsole,
+        });
         shellTarget.listen(ShellStdoutEvent, ({ detail: chunk }) => {
             if (options.stdoutCallback) {
                 void options.stdoutCallback(chunk.toString(), shellTarget.childProcess);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "31.73.5",
+    "version": "32.1.0",
     "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
     "keywords": [
         "augment",
@@ -38,9 +38,9 @@
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.73.5",
-        "@augment-vir/common": "^31.73.5",
-        "@date-vir/duration": "^8.5.0",
+        "@augment-vir/assert": "^32.1.0",
+        "@augment-vir/common": "^32.1.0",
+        "@date-vir/duration": "^8.6.1",
         "ansi-styles": "^6.2.3",
         "sanitize-filename": "^1.6.4",
         "terminate": "^2.8.0",
@@ -49,8 +49,8 @@
         "typed-event-target": "^4.3.1"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.73.5",
-        "@types/node": "^25.9.3",
+        "@augment-vir/test": "^32.1.0",
+        "@types/node": "^26.0.1",
         "@web/dev-server-esbuild": "^1.0.5",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-playwright": "^0.11.1",

package/src/augments/fs/read-dir.ts

@@ -2,14 +2,20 @@ import {readdir, stat} from 'node:fs/promises';
 import {join, relative} from 'node:path';
 import {type RequireExactlyOne} from 'type-fest';
 
-async function internalReadDirPathsRecursive(dirPath: string, basePath: string): Promise<string[]> {
+async function internalReadDirPathsRecursive({
+    dirPath,
+    basePath,
+}: Readonly<{dirPath: string; basePath: string}>): Promise<string[]> {
     const dirContents = await readdir(dirPath);
     const recursiveContents: string[] = (
         await Promise.all(
             dirContents.map(async (fileName): Promise<string | ReadonlyArray<string>> => {
                 const filePath = join(dirPath, fileName);
                 if ((await stat(filePath)).isDirectory()) {
-                    return internalReadDirPathsRecursive(filePath, basePath);
+                    return internalReadDirPathsRecursive({
+                        dirPath: filePath,
+                        basePath,
+                    });
                 } else {
                     return relative(basePath, filePath);
                 }
@@ -29,7 +35,10 @@ async function internalReadDirPathsRecursive(dirPath: string, basePath: string):
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export async function readDirRecursive(dirPath: string): Promise<string[]> {
-    return await internalReadDirPathsRecursive(dirPath, dirPath);
+    return await internalReadDirPathsRecursive({
+        dirPath,
+        basePath: dirPath,
+    });
 }
 
 /**

package/src/augments/path/contains.ts

@@ -9,18 +9,22 @@ import {isOperatingSystem, OperatingSystem} from '../os/operating-system.js';
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export function doesPathContain(
-    potentialParentPath: string,
-    potentialChildPath: string,
-    options: PartialWithUndefined<{
+export function doesPathContain({
+    potentialParentPath,
+    potentialChildPath,
+    options = {},
+}: Readonly<{
+    potentialParentPath: string;
+    potentialChildPath: string;
+    options?: PartialWithUndefined<{
         /**
          * Set this to `true` to return `true` if the paths are exactly equal.
          *
          * @default false
          */
         allowSelf: boolean;
-    }> = {},
-): boolean {
+    }>;
+}>): boolean {
     if (!potentialParentPath || !potentialChildPath) {
         return false;
     }

package/src/augments/path/resolve-import.ts

@@ -17,14 +17,18 @@ import {replaceWithWindowsPathIfNeeded} from './os-path.js';
  * @returns `undefined` if no matches are found.
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export function resolveImportPath(
-    importerFilePath: string,
-    importPath: string,
-): string | undefined {
+export function resolveImportPath({
+    importerFilePath,
+    importPath,
+}: Readonly<{importerFilePath: string; importPath: string}>): string | undefined {
     const foundTsconfig = readTsconfig(importerFilePath);
 
     const mappedImportPath = foundTsconfig
-        ? mapImportPath(importPath, foundTsconfig.tsconfig, foundTsconfig.path)
+        ? mapImportPath({
+              importPath,
+              tsconfig: foundTsconfig.tsconfig,
+              tsconfigPath: foundTsconfig.path,
+          })
         : importPath;
 
     if (mappedImportPath.startsWith(sep) || mappedImportPath.startsWith('/')) {
@@ -81,11 +85,11 @@ function mapFilePath(path: string): string {
     return path;
 }
 
-function mapImportPath(
-    importPath: string,
-    tsconfig: ParsedCommandLine,
-    tsconfigPath: string,
-): string {
+function mapImportPath({
+    importPath,
+    tsconfig,
+    tsconfigPath,
+}: Readonly<{importPath: string; tsconfig: ParsedCommandLine; tsconfigPath: string}>): string {
     const paths = tsconfig.options.paths;
     if (!paths) {
         return importPath;

package/src/augments/terminal/run-cli-script.ts

@@ -30,16 +30,11 @@ export const ExtensionToRunner: Record<string, string | {npx: string}> = {
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export async function runCliScript(
-    scriptPath: string,
-    /** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
-    cliScriptFilePath: 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,
-) {
+export async function runCliScript({
+    scriptPath,
+    cliScriptFilePath,
+    binName,
+}: Readonly<{scriptPath: string; cliScriptFilePath: string; binName: string | undefined}>) {
     const args = extractRelevantArgs({
         rawArgs: process.argv,
         binName,

package/src/augments/terminal/shell.ts

@@ -75,6 +75,21 @@ export class ShellTarget extends ListenTarget<
     }
 }
 
+/**
+ * Options for {@link streamShellCommand}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type StreamShellCommandOptions = PartialWithUndefined<{
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    shell: string;
+    /** Automatically hook up stdout and stderr printing to the caller's console methods. */
+    hookUpToConsole: boolean;
+}>;
+
 /**
  * Runs a shell command and returns a {@link ShellTarget} instance for directly hooking into shell
  * events. This allows instant reactions to shell events but in a less convenient API compared to
@@ -88,10 +103,12 @@ export class ShellTarget extends ListenTarget<
  */
 export function streamShellCommand(
     command: string,
-    cwd?: string,
-    shell = 'bash',
-    env: NodeJS.ProcessEnv = process.env,
-    hookUpToConsole = false,
+    {
+        cwd,
+        env = process.env,
+        shell = 'bash',
+        hookUpToConsole = false,
+    }: StreamShellCommandOptions = {},
 ): ShellTarget {
     const stdio = hookUpToConsole ? [process.stdin] : undefined;
 
@@ -147,8 +164,11 @@ export function streamShellCommand(
         const exitSignal: NodeJS.Signals | undefined = inputExitSignal ?? undefined;
 
         if ((exitCode !== undefined && exitCode !== 0) || exitSignal !== undefined) {
-            const execException: ExecException & {cwd?: string | undefined} = new Error(
-                `Command failed: ${command}`,
+            const execException: ExecException & {cwd?: string | undefined} = Object.assign(
+                new Error(`Command failed: ${command}`),
+                {
+                    cmd: command,
+                },
             );
             if (exitCode != undefined) {
                 execException.code = exitCode;
@@ -157,7 +177,6 @@ export function streamShellCommand(
             if (exitSignal != undefined) {
                 execException.signal = exitSignal;
             }
-            execException.cmd = command;
             execException.killed = childProcess.killed;
             execException.cwd = cwd;
             shellTarget.dispatch(
@@ -186,19 +205,21 @@ export function streamShellCommand(
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export type RunShellCommandOptions = {
-    cwd?: string | undefined;
-    env?: NodeJS.ProcessEnv | undefined;
-    shell?: string | undefined;
-    /** Automatically hook up stdout and stderr printing to the caller's console methods. */
-    hookUpToConsole?: boolean | undefined;
-    /** @default false */
-    rejectOnError?: boolean | undefined;
-    /** Callback to call whenever the shell logs to stdout. */
-    stdoutCallback?: (stdout: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
-    /** Callback to call whenever the shell logs to stderr. */
-    stderrCallback?: (stderr: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
-};
+export type RunShellCommandOptions = StreamShellCommandOptions &
+    PartialWithUndefined<{
+        /** @default false */
+        rejectOnError: boolean;
+        /** Callback to call whenever the shell logs to stdout. */
+        stdoutCallback: (
+            stdout: string,
+            childProcess: ChildProcess,
+        ) => MaybePromise<void> | undefined;
+        /** Callback to call whenever the shell logs to stderr. */
+        stderrCallback: (
+            stderr: string,
+            childProcess: ChildProcess,
+        ) => MaybePromise<void> | undefined;
+    }>;
 
 /**
  * Runs a shell command and returns its output.
@@ -218,13 +239,12 @@ export async function runShellCommand(
         let stderr = '';
         const errors: Error[] = [];
 
-        const shellTarget = streamShellCommand(
-            command,
-            options.cwd,
-            options.shell,
-            options.env,
-            options.hookUpToConsole,
-        );
+        const shellTarget = streamShellCommand(command, {
+            cwd: options.cwd,
+            shell: options.shell,
+            env: options.env,
+            hookUpToConsole: options.hookUpToConsole,
+        });
 
         shellTarget.listen(ShellStdoutEvent, ({detail: chunk}) => {
             if (options.stdoutCallback) {