@augment-vir/node 31.0.0 → 31.1.0

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

@@ -65,7 +65,7 @@ export async function resetDirContents(rootDir, contents) {
  * @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,]) => {
+    await Promise.all(getObjectTypedEntries(contents).map(async ([relativePath, content]) => {
         const fullPath = join(rootDir, relativePath);
         if (check.isString(content)) {
             await writeFileAndDir(fullPath, content);

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

@@ -37,13 +37,7 @@ export type RelevantArgsInput = {
  *
  * ```ts
  * extractRelevantArgs({
- *     rawArgs: [
- *         'npx',
- *         'ts-node',
- *         './my-script.ts',
- *         'arg1',
- *         '--arg2',
- *     ], // typically will be process.argv
+ *     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
  * });

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

@@ -9,13 +9,7 @@ import { basename } from 'node:path';
  *
  * ```ts
  * extractRelevantArgs({
- *     rawArgs: [
- *         'npx',
- *         'ts-node',
- *         './my-script.ts',
- *         'arg1',
- *         '--arg2',
- *     ], // typically will be process.argv
+ *     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
  * });

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

@@ -41,11 +41,7 @@ binName) {
     if (!runner) {
         throw new Error("No runner configured for file extension '${extension}' in '${path}'");
     }
-    const results = await runShellCommand(interpolationSafeWindowsPath([
-        runner,
-        path,
-        ...args,
-    ].join(' ')), {
+    const results = await runShellCommand(interpolationSafeWindowsPath([runner, path, ...args].join(' ')), {
         hookUpToConsole: true,
     });
     process.exit(results.exitCode || 0);

package/dist/augments/terminal/shell.js

@@ -169,10 +169,7 @@ export async function runShellCommand(command, options = {}) {
             }
             /* node:coverage enable */
             shellTarget.destroy();
-            const rejectionErrorMessage = combineErrors([
-                new Error(stderr),
-                ...errors,
-            ]);
+            const rejectionErrorMessage = combineErrors([new Error(stderr), ...errors]);
             /** Reject now because the "done" listener won't get fired after killing the process. */
             reject(rejectionErrorMessage);
         });

package/dist/docker/containers/docker-command-inputs.js

@@ -37,7 +37,7 @@ export function makeEnvFlags(envMapping) {
     if (!envMapping) {
         return '';
     }
-    const flags = Object.entries(envMapping).map(([key, { value, allowInterpolation },]) => {
+    const flags = Object.entries(envMapping).map(([key, { value, allowInterpolation }]) => {
         const quote = allowInterpolation ? '"' : "'";
         return `-e ${key}=${wrapString({ value, wrapper: quote })}`;
     });

package/dist/docker/containers/run-container.mock.js

@@ -4,10 +4,7 @@ export async function runMockLongLivingContainer(containerName, args = {}) {
         containerName: containerName,
         detach: true,
         imageName: 'alpine:3.20.2',
-        dockerFlags: [
-            '-i',
-            '-t',
-        ],
+        dockerFlags: ['-i', '-t'],
         command: 'sh',
         platform: 'amd64',
         ...args,

package/dist/docker/docker-image.js

@@ -11,12 +11,7 @@ imageName, platform) {
     const command = [
         'docker',
         'pull',
-        ...(platform
-            ? [
-                '--platform',
-                platform,
-            ]
-            : []),
+        ...(platform ? ['--platform', platform] : []),
         wrapString({ value: imageName, wrapper: "'" }),
     ].join(' ');
     await runShellCommand(command, {

package/dist/prisma/model-data.js

@@ -8,7 +8,7 @@ export async function addData(prismaClient, data) {
 }
 async function addModelDataObject(prismaClient, data) {
     /** Add the mock data to the mock prisma client. */
-    await awaitedForEach(getObjectTypedEntries(data), async ([modelName, mockData,]) => {
+    await awaitedForEach(getObjectTypedEntries(data), async ([modelName, mockData]) => {
         /**
          * This type is dumbed down to just `AnyObject[]` because the union of all possible
          * model data is just way too big (and not helpful as the inputs to this function are
@@ -37,10 +37,7 @@ async function addModelDataObject(prismaClient, data) {
         }
     });
 }
-const prismockKeys = [
-    'getData',
-    'setData',
-];
+const prismockKeys = ['getData', 'setData'];
 export function getAllPrismaModelNames(prismaClient) {
     return Object.keys(prismaClient)
         .filter((key) => !key.startsWith('$') && !key.startsWith('_') && !prismockKeys.includes(key))

package/dist/prisma/prisma-migrations.js

@@ -13,12 +13,7 @@ var DbChangeRequired;
     DbChangeRequired["ResetNeeded"] = "reset-needed";
 })(DbChangeRequired || (DbChangeRequired = {}));
 export async function applyPrismaMigrationsToDev(schemaFilePath, env = {}) {
-    const command = [
-        'prisma',
-        'migrate',
-        'dev',
-        `--schema='${schemaFilePath}'`,
-    ].join(' ');
+    const command = ['prisma', 'migrate', 'dev', `--schema='${schemaFilePath}'`].join(' ');
     log.faint(`> ${command}`);
     let dbRequirement = undefined;
     const result = await runShellCommand(command, {
@@ -76,7 +71,7 @@ export async function getMigrationStatus(schemaFilePath, env = {}) {
             foundNotAppliedMigrations = true;
         }
         else {
-            const [, countMatch,] = safeMatch(line, /^([\d,]+) migrations? found in/);
+            const [, countMatch] = safeMatch(line, /^([\d,]+) migrations? found in/);
             if (countMatch) {
                 listedMigrations.totalMigrations = toEnsuredNumber(countMatch);
             }

package/dist/prisma/run-prisma-command.js

@@ -2,28 +2,16 @@ import { log } from '@augment-vir/common';
 import { interpolationSafeWindowsPath } from '../augments/path/os-path.js';
 import { runShellCommand } from '../augments/terminal/shell.js';
 import { PrismaSchemaError } from './prisma-errors.js';
-const prismaCommandsThatSupportNoHints = [
-    'generate',
-];
+const prismaCommandsThatSupportNoHints = ['generate'];
 export async function runPrismaCommand({ command, ignoreExitCode = false, }, 
 /** Set to `undefined` to omit the `--schema` flag. */
 schemaFilePath, env = {}) {
-    const schemaFileArgs = schemaFilePath
-        ? [
-            '--schema',
-            schemaFilePath,
-        ]
-        : [];
+    const schemaFileArgs = schemaFilePath ? ['--schema', schemaFilePath] : [];
     /** Disable Prisma's in-CLI ads. */
     const noHintsArg = prismaCommandsThatSupportNoHints.some((commandName) => command.startsWith(commandName))
         ? '--no-hints'
         : '';
-    const fullCommand = [
-        'prisma',
-        command,
-        ...schemaFileArgs,
-        noHintsArg,
-    ].join(' ');
+    const fullCommand = ['prisma', command, ...schemaFileArgs, noHintsArg].join(' ');
     log.faint(`> ${fullCommand}`);
     const result = await runShellCommand(interpolationSafeWindowsPath(fullCommand), {
         env: {

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.0",
+    "version": "31.1.0",
     "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.0",
-        "@augment-vir/common": "^31.0.0",
+        "@augment-vir/assert": "^31.1.0",
+        "@augment-vir/common": "^31.1.0",
         "@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.0",
+        "@augment-vir/test": "^31.1.0",
         "@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);
+}