@augment-vir/node 31.0.1 → 31.1.1

package/dist/scripts/fix-ts-bin.script.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/fix-ts-bin.script.js

@@ -0,0 +1,48 @@
+/* node:coverage disable */
+/**
+ * To use this script properly, call it directly in your postinstall script. Like this:
+ *
+ * ```json
+ * {
+ *     "scripts": {
+ *         "postinstall": "tsx node_modules/@augment-vir/node/src/scripts/fix-ts-bin.script.ts"
+ *     }
+ * }
+ * ```
+ */
+import { log } from '@augment-vir/common';
+import { interpolationSafeWindowsPath, runShellCommand } from '@augment-vir/node';
+import { rm, writeFile } from 'node:fs/promises';
+import { join, sep } from 'node:path/posix';
+const packagesToFix = [
+    {
+        packageName: 'mono-vir',
+        binName: 'mono-vir',
+        scriptPath: join('mono-vir', 'src', 'cli', 'cli.script.ts'),
+    },
+    {
+        packageName: 'virmator',
+        binName: 'virmator',
+        scriptPath: join('virmator', 'src', 'cli.script.ts'),
+    },
+    {
+        packageName: 'prettier',
+        binName: 'prettier',
+        scriptPath: join('prettier', 'bin', 'prettier.cjs'),
+    },
+];
+function createBinFileContents({ scriptPath }) {
+    return [
+        '#!/bin/bash',
+        '',
+        `npx tsx "$(dirname "$(dirname "$(readlink -f "$0")")")${sep}${scriptPath}" "$@"`,
+    ].join('\n');
+}
+async function fixTsBin(packageToFix) {
+    const binFilePath = join(process.cwd(), 'node_modules', '.bin', packageToFix.binName);
+    await rm(binFilePath, { force: true });
+    await writeFile(binFilePath, createBinFileContents(packageToFix));
+    await runShellCommand(`chmod +x ${interpolationSafeWindowsPath(binFilePath)}`);
+    log.success(`Fixed ${packageToFix.packageName} bin.`);
+}
+await Promise.all(packagesToFix.map(async (packageToFix) => await fixTsBin(packageToFix)));

package/package.json

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

package/src/augments/docker.ts

@@ -0,0 +1,118 @@
+import {getContainerInfo} from '../docker/containers/container-info.js';
+import {
+    getContainerLogs,
+    getContainerStatus,
+    waitUntilContainerExited,
+    waitUntilContainerRemoved,
+    waitUntilContainerRunning,
+} from '../docker/containers/container-status.js';
+import {copyToContainer} from '../docker/containers/copy-to-container.js';
+import {
+    makeEnvFlags,
+    makePortMapFlags,
+    makeVolumeFlags,
+} from '../docker/containers/docker-command-inputs.js';
+import {killContainer} from '../docker/containers/kill-container.js';
+import {runContainerCommand} from '../docker/containers/run-command.js';
+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 {
+    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`.
+ *
+ * @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/src/augments/fs/dir-contents.ts

@@ -0,0 +1,116 @@
+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';
+
+/**
+ * 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 async function readAllDirContents(
+    dir: string,
+    {
+        recursive = false,
+        excludeList,
+    }: {
+        recursive?: boolean;
+        excludeList?: ReadonlyArray<string | RegExp> | undefined;
+    },
+): Promise<DirContents> {
+    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: DirContents, 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: string,
+    contents: Readonly<DirContents>,
+): Promise<void> {
+    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: string,
+    contents: Readonly<DirContents>,
+): Promise<void> {
+    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/src/augments/fs/download.ts

@@ -0,0 +1,31 @@
+import {createWriteStream} from 'node:fs';
+import {mkdir} from 'node:fs/promises';
+import {dirname} from 'node:path';
+import {Readable} from 'node:stream';
+import {finished} from 'node:stream/promises';
+import type {ReadableStream} from 'node:stream/web';
+
+/**
+ * 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}: {url: string; writePath: string}) {
+    const response = await fetch(url);
+
+    if (!response.ok) {
+        throw new Error(`${response.status}: ${response.statusText}`);
+    }
+
+    /** Idk how to actually trigger a response with no body. */
+    /* node:coverage ignore next 3 */
+    if (!response.body) {
+        throw new Error(`Response body is missing from '${url}'.`);
+    }
+
+    await mkdir(dirname(writePath), {recursive: true});
+    const fileStream = createWriteStream(writePath);
+    await finished(Readable.fromWeb(response.body as ReadableStream).pipe(fileStream));
+}

package/src/augments/fs/json.ts

@@ -0,0 +1,87 @@
+import {
+    appendJson,
+    JsonCompatibleArray,
+    JsonCompatibleObject,
+    type JsonCompatibleValue,
+} from '@augment-vir/common';
+import type {PartialWithUndefined} from '@augment-vir/core';
+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: string): Promise<JsonCompatibleValue | undefined> {
+    try {
+        const contents = (await readFile(path)).toString();
+        return JSON.parse(contents);
+    } catch {
+        return 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 async function writeJsonFile(
+    path: string,
+    data: JsonCompatibleValue,
+    options: WriteJsonOptions = {},
+): Promise<void> {
+    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: string,
+    newData: JsonCompatibleObject | JsonCompatibleArray,
+    options: WriteJsonOptions = {},
+): Promise<void> {
+    const fileJson = await readJsonFile(path);
+
+    await writeJsonFile(path, appendJson(fileJson, newData), options);
+}

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

@@ -0,0 +1,60 @@
+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[]> {
+    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);
+                } else {
+                    return relative(basePath, filePath);
+                }
+            }),
+        )
+    ).flat();
+
+    return recursiveContents;
+}
+
+/**
+ * Gets all files within a directory and its subdirectories, recursively. Returns an array of paths
+ * 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: string): Promise<string[]> {
+    return await internalReadDirPathsRecursive(dirPath, dirPath);
+}
+
+/**
+ * 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,
+}: {
+    dirPath: string;
+} & RequireExactlyOne<{
+    extension: string;
+    extensions: ReadonlyArray<string>;
+}>) {
+    const extensionsToCheck: ReadonlyArray<string> = extensions || [extension];
+
+    const fileNames = await readdir(dirPath);
+
+    return fileNames.filter((fileName) =>
+        extensionsToCheck.some((extensionToCheck) => fileName.endsWith(extensionToCheck)),
+    );
+}

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

@@ -0,0 +1,18 @@
+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: string): Promise<string | undefined> {
+    if (existsSync(path)) {
+        return (await readFile(path)).toString();
+    } else {
+        return undefined;
+    }
+}

package/src/augments/fs/symlink.ts

@@ -0,0 +1,37 @@
+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,
+}: {
+    /**
+     * Path that the symlink will link to. If relative, it will be linked relative to the symlink
+     * location.
+     */
+    linkTo: string;
+    /** The location and name the symlink file to be created. */
+    symlinkPath: string;
+}): Promise<void> {
+    if (existsSync(symlinkPath)) {
+        if (!(await lstat(symlinkPath)).isSymbolicLink()) {
+            throw new Error(
+                `Tried to create symlink at '${symlinkPath}' but a non-symlink file already exists in that location.`,
+            );
+        } else if ((await readlink(symlinkPath)) !== linkTo) {
+            throw new Error(
+                `Symlink already exists at '${symlinkPath}' but has a differently link path.`,
+            );
+        }
+    } else {
+        const isDir = (await stat(linkTo)).isDirectory();
+        await symlink(linkTo, symlinkPath, isDir ? 'dir' : 'file');
+    }
+}

package/src/augments/fs/write.ts

@@ -0,0 +1,18 @@
+import {mkdir, writeFile} from 'node:fs/promises';
+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: string,
+    contents: string | NodeJS.ArrayBufferView,
+): Promise<void> {
+    await mkdir(dirname(path), {recursive: true});
+    await writeFile(path, contents);
+}

package/src/augments/npm/query-workspace.ts

@@ -0,0 +1,47 @@
+import type {UnknownObject} from '@augment-vir/core';
+import type {PackageJson} from 'type-fest';
+import {runShellCommand} from '../terminal/shell.js';
+
+/**
+ * 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;
+    dev: boolean;
+    from: string[];
+    inBundle: boolean;
+    location: string;
+    overridden: boolean;
+    path: string;
+    pkgid: string;
+    queryContext: UnknownObject;
+    realpath: string;
+    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 async function queryNpmWorkspace(cwd: string): Promise<NpmWorkspace[]> {
+    const queryOutput = await runShellCommand('npm query .workspace', {
+        cwd,
+        rejectOnError: true,
+    });
+
+    try {
+        return JSON.parse(queryOutput.stdout);
+        /* node:coverage ignore next 3 */
+    } catch {
+        throw new Error(`Failed to read npm workspace data for '${cwd}'`);
+    }
+}

package/src/augments/npm/read-package-json.ts

@@ -0,0 +1,28 @@
+import {check} from '@augment-vir/assert';
+import {join} from 'node:path';
+import {PackageJson} from 'type-fest';
+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: string): Promise<PackageJson> {
+    const packageJsonPath = join(dirPath, 'package.json');
+    const packageJson = (await readJsonFile(packageJsonPath)) as PackageJson | undefined;
+
+    if (!packageJson) {
+        throw new TypeError(`package.json file does not exist in '${dirPath}'`);
+    }
+
+    if (!check.isObject(packageJson)) {
+        throw new TypeError(`Parsing package.json file did not return an object in '${dirPath}'`);
+    }
+
+    return packageJson;
+}