@augment-vir/node 30.0.0 → 30.0.2

package/README.md

@@ -1,13 +1,10 @@
 # @augment-vir/node
 
-## Prisma flows
+A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.
 
--   deploy to production
-    -   `prisma.migration.applyProd`
--   update dev environment
-    -   apply migrations: `prisma.migration.applyDev`
-        -   if throws `PrismaMigrationNeededError`, prompt user for a new migration name
-            -   pass migration name to `prisma.migration.create`
-        -   if throws `PrismaResetNeededError`, reset the database with `prisma.database.resetDev`
-    -   generate client: `prisma.client.isCurrent`
-        -   if `false`, run `prisma.client.generate`
+-   Includes a custom Prisma API built on its CLI: [`prisma`](https://electrovir.github.io/augment-vir/variables/prisma.html).
+-   Includes a custom Docker API built on its CLI: [`docker`](https://electrovir.github.io/augment-vir/variables/docker.html).
+-   Includes an easy to use shell script runner: [`runShellCommand`](https://electrovir.github.io/augment-vir/functions/runShellCommand.html).
+-   and much more!
+
+See all the docs under `Node : *`, or `* : Node`, or `Package: @augment-vir/node` here: https://electrovir.github.io/augment-vir

package/dist/augments/docker.d.ts

@@ -8,37 +8,84 @@ import { runContainer } from '../docker/containers/run-container.js';
 import { tryOrKillContainer } from '../docker/containers/try-or-kill-container.js';
 import { isImageInLocalRegistry, removeImageFromLocalRegistry, updateImage } from '../docker/docker-image.js';
 import { isDockerRunning, startDocker } from '../docker/docker-startup.js';
-export { DockerContainerStatusEnum, type DockerContainerInfo, type DockerContainerInfoState, } from '../docker/containers/container-info.js';
+export { type DockerContainerInfo, type DockerContainerInfoState, } from '../docker/containers/container-info.js';
 export { DockerContainerStatus, exitedDockerContainerStatuses, } from '../docker/containers/container-status.js';
 export { type CopyToDockerContainerParams } from '../docker/containers/copy-to-container.js';
 export { type DockerEnvMap, type DockerPortMap, type DockerVolumeMap, type DockerVolumeMappingType, } from '../docker/containers/docker-command-inputs.js';
 export { type RunDockerContainerCommandParams } from '../docker/containers/run-command.js';
 export { type RunDockerContainerParams } from '../docker/containers/run-container.js';
-/** Centralized Docker API from `@augment-vir/node`. */
+/**
+ * Centralized Docker API from `@augment-vir/node`.
+ *
+ * @category Node : Docker
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare const docker: {
+    /** Detects if the Docker service is running. */
     isRunning: typeof isDockerRunning;
+    /**
+     * Tries to start Docker based ont he current operating system's supported commands. The success
+     * of this operation is heavily dependent on how you have Docker setup on your system.
+     */
     start: typeof startDocker;
     image: {
+        /** Downloads an image if it is missing from the local registry. */
         update: typeof updateImage;
+        /** Removes an image from the local registry. */
         remove: typeof removeImageFromLocalRegistry;
+        /** Detects if an image exists in the local registry. */
         exists: typeof isImageInLocalRegistry;
     };
     container: {
+        /**
+         * Get the current status of a container. If the container does not exist at all, the status
+         * will be {@link DockerContainerStatus.Removed}.
+         */
         getStatus: typeof getContainerStatus;
+        /** Wait until a container is running and responsive. */
         waitUntilRunning: typeof waitUntilContainerRunning;
+        /**
+         * Wait until a container has a status that can be classified as "exited".
+         *
+         * @see {@link exitedDockerContainerStatuses}
+         */
         waitUntilExited: typeof waitUntilContainerExited;
+        /** Wait until a container is completely removed. */
         waitUntilRemoved: typeof waitUntilContainerRemoved;
+        /**
+         * Runs a callback (which presumably will run a command within the given `containerName`)
+         * and kills the container if the callback fails.
+         */
         tryOrKill: typeof tryOrKillContainer;
+        /** Run a container that isn't already running. */
         run: typeof runContainer;
+        /** Kill a container. */
         kill: typeof killContainer;
+        /** Copy a file or directory to a container. */
         copyTo: typeof copyToContainer;
+        /** Run a command on a container that is already running. */
         runCommand: typeof runContainerCommand;
+        /** Run `docker inspect` on a container and return its output. */
         getInfo: typeof getContainerInfo;
+        /** Get a container's logs. */
         getLogs: typeof getContainerLogs;
     };
     util: {
+        /**
+         * Manually create a string of volume mapping flags. This is automatically done already
+         * inside the run container methods.
+         */
         makeVolumeFlags: typeof makeVolumeFlags;
+        /**
+         * Manually create a string of port mapping flags. This is automatically done already inside
+         * the run container methods.
+         */
         makePortMapFlags: typeof makePortMapFlags;
+        /**
+         * Manually create a string of env mapping flags. This is automatically done already inside
+         * the run container methods.
+         */
         makeEnvFlags: typeof makeEnvFlags;
     };
 };

package/dist/augments/docker.js

@@ -8,33 +8,79 @@ import { runContainer } from '../docker/containers/run-container.js';
 import { tryOrKillContainer } from '../docker/containers/try-or-kill-container.js';
 import { isImageInLocalRegistry, removeImageFromLocalRegistry, updateImage, } from '../docker/docker-image.js';
 import { isDockerRunning, startDocker } from '../docker/docker-startup.js';
-export { DockerContainerStatusEnum, } from '../docker/containers/container-info.js';
 export { DockerContainerStatus, exitedDockerContainerStatuses, } from '../docker/containers/container-status.js';
-/** Centralized Docker API from `@augment-vir/node`. */
+/**
+ * Centralized Docker API from `@augment-vir/node`.
+ *
+ * @category Node : Docker
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export const docker = {
+    /** Detects if the Docker service is running. */
     isRunning: isDockerRunning,
+    /**
+     * Tries to start Docker based ont he current operating system's supported commands. The success
+     * of this operation is heavily dependent on how you have Docker setup on your system.
+     */
     start: startDocker,
     image: {
+        /** Downloads an image if it is missing from the local registry. */
         update: updateImage,
+        /** Removes an image from the local registry. */
         remove: removeImageFromLocalRegistry,
+        /** Detects if an image exists in the local registry. */
         exists: isImageInLocalRegistry,
     },
     container: {
+        /**
+         * Get the current status of a container. If the container does not exist at all, the status
+         * will be {@link DockerContainerStatus.Removed}.
+         */
         getStatus: getContainerStatus,
+        /** Wait until a container is running and responsive. */
         waitUntilRunning: waitUntilContainerRunning,
+        /**
+         * Wait until a container has a status that can be classified as "exited".
+         *
+         * @see {@link exitedDockerContainerStatuses}
+         */
         waitUntilExited: waitUntilContainerExited,
+        /** Wait until a container is completely removed. */
         waitUntilRemoved: waitUntilContainerRemoved,
+        /**
+         * Runs a callback (which presumably will run a command within the given `containerName`)
+         * and kills the container if the callback fails.
+         */
         tryOrKill: tryOrKillContainer,
+        /** Run a container that isn't already running. */
         run: runContainer,
+        /** Kill a container. */
         kill: killContainer,
+        /** Copy a file or directory to a container. */
         copyTo: copyToContainer,
+        /** Run a command on a container that is already running. */
         runCommand: runContainerCommand,
+        /** Run `docker inspect` on a container and return its output. */
         getInfo: getContainerInfo,
+        /** Get a container's logs. */
         getLogs: getContainerLogs,
     },
     util: {
+        /**
+         * Manually create a string of volume mapping flags. This is automatically done already
+         * inside the run container methods.
+         */
         makeVolumeFlags,
+        /**
+         * Manually create a string of port mapping flags. This is automatically done already inside
+         * the run container methods.
+         */
         makePortMapFlags,
+        /**
+         * Manually create a string of env mapping flags. This is automatically done already inside
+         * the run container methods.
+         */
         makeEnvFlags,
     },
 };

package/dist/augments/fs/download.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Download a file.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function downloadFile({ url, writePath }: {
+    url: string;
+    writePath: string;
+}): Promise<void>;

package/dist/augments/{download.js → fs/download.js}

@@ -3,6 +3,13 @@ import { mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { Readable } from 'node:stream';
 import { finished } from 'node:stream/promises';
+/**
+ * Download a file.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export async function downloadFile({ url, writePath }) {
     const response = await fetch(url);
     if (!response.ok) {

package/dist/augments/fs/json.d.ts

@@ -1,8 +1,50 @@
 import { JsonCompatibleArray, JsonCompatibleObject, type JsonCompatibleValue } from '@augment-vir/common';
 import type { PartialWithUndefined } from '@augment-vir/core';
+/**
+ * Read a file and also parse its contents as JSON.
+ *
+ * @category Node : File
+ * @category JSON : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ *  - {@link writeJsonFile}
+ *  - {@link appendJsonFile}
+ */
 export declare function readJsonFile(path: string): Promise<JsonCompatibleValue | undefined>;
+/**
+ * Options for {@link writeJsonFile}.
+ *
+ * @category Node : File
+ * @category JSON : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export type WriteJsonOptions = PartialWithUndefined<{
     includeTrailingNewLine: boolean;
 }>;
+/**
+ * Write to a file and stringify `data` as JSON before doing so.
+ *
+ * @category Node : File
+ * @category JSON : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ *  - {@link readJsonFile}
+ *  - {@link appendJsonFile}
+ */
 export declare function writeJsonFile(path: string, data: JsonCompatibleValue, options?: WriteJsonOptions): Promise<void>;
+/**
+ * Append the given `newData` to the contents of the existing JSON file. If the file does not yet
+ * exist, `newData` is written as its only JSON contents.
+ *
+ * @category Node : File
+ * @category JSON : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ *  - {@link readJsonFile}
+ *  - {@link writeJsonFile}
+ */
 export declare function appendJsonFile(path: string, newData: JsonCompatibleObject | JsonCompatibleArray, options?: WriteJsonOptions): Promise<void>;

package/dist/augments/fs/json.js

@@ -2,6 +2,17 @@ import { appendJson, } from '@augment-vir/common';
 import { mkdir, readFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { writeFileAndDir } from './write.js';
+/**
+ * Read a file and also parse its contents as JSON.
+ *
+ * @category Node : File
+ * @category JSON : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ *  - {@link writeJsonFile}
+ *  - {@link appendJsonFile}
+ */
 export async function readJsonFile(path) {
     try {
         const contents = (await readFile(path)).toString();
@@ -11,11 +22,34 @@ export async function readJsonFile(path) {
         return undefined;
     }
 }
+/**
+ * Write to a file and stringify `data` as JSON before doing so.
+ *
+ * @category Node : File
+ * @category JSON : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ *  - {@link readJsonFile}
+ *  - {@link appendJsonFile}
+ */
 export async function writeJsonFile(path, data, options = {}) {
     await mkdir(dirname(path), { recursive: true });
     const trailingNewLine = options.includeTrailingNewLine ? '\n' : '';
     await writeFileAndDir(path, JSON.stringify(data, null, 4) + trailingNewLine);
 }
+/**
+ * Append the given `newData` to the contents of the existing JSON file. If the file does not yet
+ * exist, `newData` is written as its only JSON contents.
+ *
+ * @category Node : File
+ * @category JSON : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ *  - {@link readJsonFile}
+ *  - {@link writeJsonFile}
+ */
 export async function appendJsonFile(path, newData, options = {}) {
     const fileJson = await readJsonFile(path);
     await writeJsonFile(path, appendJson(fileJson, newData), options);

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

@@ -1,12 +1,20 @@
 import type { RequireExactlyOne } from 'type-fest';
 /**
  * Gets all files within a directory and its subdirectories, recursively. Returns an array of paths
- * relative to the input directory path.
+ * relative to the given input path.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export declare function readDirRecursive(dirPath: string): Promise<string[]>;
 /**
- * Reads all files within a directory and then filters them by the given extension or extensions.
- * Returns that filtered list.
+ * Reads all files within a single directory and filters them by the given extension or extensions.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @returns That filtered list of paths.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export declare function readDirFilesByExtension({ dirPath, extension, extensions, }: {
     dirPath: string;

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

@@ -15,14 +15,22 @@ async function internalReadDirPathsRecursive(dirPath, basePath) {
 }
 /**
  * Gets all files within a directory and its subdirectories, recursively. Returns an array of paths
- * relative to the input directory path.
+ * relative to the given input path.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export async function readDirRecursive(dirPath) {
     return await internalReadDirPathsRecursive(dirPath, dirPath);
 }
 /**
- * Reads all files within a directory and then filters them by the given extension or extensions.
- * Returns that filtered list.
+ * Reads all files within a single directory and filters them by the given extension or extensions.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @returns That filtered list of paths.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export async function readDirFilesByExtension({ dirPath, extension, extensions, }) {
     const extensionsToCheck = extensions || [extension];

package/dist/augments/fs/read-file.d.ts

@@ -1 +1,9 @@
+/**
+ * Reads a file if it exists, or just return `undefined`.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @returns The file contents as a string if the file exists, otherwise `undefined`.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare function readFileIfExists(path: string): Promise<string | undefined>;

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

@@ -1,5 +1,13 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+/**
+ * Reads a file if it exists, or just return `undefined`.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @returns The file contents as a string if the file exists, otherwise `undefined`.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export async function readFileIfExists(path) {
     if (existsSync(path)) {
         return (await readFile(path)).toString();

package/dist/augments/fs/symlink.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Creates a symlink.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare function createSymlink({ linkTo, symlinkPath, }: {
     /**
      * Path that the symlink will link to. If relative, it will be linked relative to the symlink

package/dist/augments/fs/symlink.js

@@ -1,5 +1,12 @@
 import { existsSync } from 'node:fs';
 import { lstat, readlink, stat, symlink } from 'node:fs/promises';
+/**
+ * Creates a symlink.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export async function createSymlink({ linkTo, symlinkPath, }) {
     if (existsSync(symlinkPath)) {
         if (!(await lstat(symlinkPath)).isSymbolicLink()) {

package/dist/augments/fs/write.d.ts

@@ -1,5 +1,9 @@
 /**
  * Writes to the given file path and always ensures that the path's parent directories are all
  * created.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export declare function writeFileAndDir(path: string, contents: string | NodeJS.ArrayBufferView): Promise<void>;

package/dist/augments/fs/write.js

@@ -3,6 +3,10 @@ import { dirname } from 'node:path';
 /**
  * Writes to the given file path and always ensures that the path's parent directories are all
  * created.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export async function writeFileAndDir(path, contents) {
     await mkdir(dirname(path), { recursive: true });

package/dist/augments/npm/query-workspace.d.ts

@@ -1,5 +1,12 @@
 import type { UnknownObject } from '@augment-vir/core';
 import type { PackageJson } from 'type-fest';
+/**
+ * An npm workspace object. This is the return type for {@link queryNpmWorkspace}.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export type NpmWorkspace = PackageJson & {
     _id: string;
     deduped: boolean;
@@ -15,4 +22,11 @@ export type NpmWorkspace = PackageJson & {
     resolved: null;
     to: string[];
 };
+/**
+ * Get a list of all NPM workspaces in the given mono-repo directory using npm's CLI.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare function queryNpmWorkspace(cwd: string): Promise<NpmWorkspace[]>;

package/dist/augments/npm/query-workspace.js

@@ -1,4 +1,11 @@
-import { runShellCommand } from '../shell.js';
+import { runShellCommand } from '../terminal/shell.js';
+/**
+ * Get a list of all NPM workspaces in the given mono-repo directory using npm's CLI.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export async function queryNpmWorkspace(cwd) {
     const queryOutput = await runShellCommand('npm query .workspace', {
         cwd,

package/dist/augments/npm/read-package-json.d.ts

@@ -1,2 +1,11 @@
 import { PackageJson } from 'type-fest';
+/**
+ * Read the `package.json` file contained within the given directory.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws `TypeError` if the given directory has no `package.json` or the `package.json` is
+ *   invalid.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare function readPackageJson(dirPath: string): Promise<PackageJson>;

package/dist/augments/npm/read-package-json.js

@@ -1,6 +1,15 @@
 import { check } from '@augment-vir/assert';
 import { join } from 'node:path';
 import { readJsonFile } from '../fs/json.js';
+/**
+ * Read the `package.json` file contained within the given directory.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws `TypeError` if the given directory has no `package.json` or the `package.json` is
+ *   invalid.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export async function readPackageJson(dirPath) {
     const packageJsonPath = join(dirPath, 'package.json');
     const packageJson = (await readJsonFile(packageJsonPath));

package/dist/augments/os/operating-system.d.ts

@@ -1,6 +1,39 @@
+/**
+ * The three major operating system types.
+ *
+ * @category Node : OS
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare enum OperatingSystem {
     Linux = "linux",
     Mac = "mac",
     Windows = "windows"
 }
+/**
+ * The current operating system type, as deduced from
+ * [`process.platform`](https://nodejs.org/api/process.html#processplatform).
+ *
+ * @category Node : OS
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare const currentOperatingSystem: OperatingSystem;
+/**
+ * Checks if the current operating system is the requested one.
+ *
+ * @category Node : OS
+ * @category Package : @augment-vir/node
+ * @example
+ *
+ * ```ts
+ * import {isOperatingSystem, OperatingSystem} from '@augment-vir/node';
+ *
+ * if (isOperatingSystem(OperatingSystem.Mac)) {
+ *     // do something
+ * }
+ * ```
+ *
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function isOperatingSystem(operatingSystem: OperatingSystem): boolean;

package/dist/augments/os/operating-system.js

@@ -1,10 +1,45 @@
+/**
+ * The three major operating system types.
+ *
+ * @category Node : OS
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export var OperatingSystem;
 (function (OperatingSystem) {
     OperatingSystem["Linux"] = "linux";
     OperatingSystem["Mac"] = "mac";
     OperatingSystem["Windows"] = "windows";
 })(OperatingSystem || (OperatingSystem = {}));
+/**
+ * The current operating system type, as deduced from
+ * [`process.platform`](https://nodejs.org/api/process.html#processplatform).
+ *
+ * @category Node : OS
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export const currentOperatingSystem = getOperatingSystem();
+/**
+ * Checks if the current operating system is the requested one.
+ *
+ * @category Node : OS
+ * @category Package : @augment-vir/node
+ * @example
+ *
+ * ```ts
+ * import {isOperatingSystem, OperatingSystem} from '@augment-vir/node';
+ *
+ * if (isOperatingSystem(OperatingSystem.Mac)) {
+ *     // do something
+ * }
+ * ```
+ *
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function isOperatingSystem(operatingSystem) {
+    return currentOperatingSystem === operatingSystem;
+}
 function getOperatingSystem() {
     /** We can't test all of these on a single system. */
     /* node:coverage ignore next 7 */

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

@@ -2,4 +2,23 @@ import type { MaybePromise } from '@augment-vir/common';
 export declare function findAncestor(currentPath: string, callback: (path: string) => Promise<boolean>): Promise<string | undefined>;
 export declare function findAncestor(currentPath: string, callback: (path: string) => boolean): string | undefined;
 export declare function findAncestor(currentPath: string, callback: (path: string) => MaybePromise<boolean>): MaybePromise<string | undefined>;
+/**
+ * Join a list of paths to the given `parentDirPath`. This is particularly useful for getting full
+ * paths from the output of
+ * [`readdir`](https://nodejs.org/api/fs.html#fspromisesreaddirpath-options).
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @example
+ *
+ * ```ts
+ * import {readdir} from 'node:fs/promises';
+ * import {join} from 'node:path';
+ *
+ * const parentDir = join('my', 'path');
+ * const dirs = joinFilesToDir(parentDir, await readdir(parentDir));
+ * ```
+ *
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare function joinFilesToDir(parentDirPath: string, childNames: ReadonlyArray<string>): Array<string>;