@augment-vir/node 31.0.1 → 31.1.1

package/src/docker/containers/run-command.ts

@@ -0,0 +1,51 @@
+import {check} from '@augment-vir/assert';
+import {runShellCommand} from '../../augments/terminal/shell.js';
+import {DockerEnvMap, makeEnvFlags} from './docker-command-inputs.js';
+
+/**
+ * Parameters for `docker.container.runCommand`.
+ *
+ * @category Node : Docker : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type RunDockerContainerCommandParams = {
+    /** Creates an interactive shell connection. */
+    tty?: boolean | undefined;
+    containerNameOrId: string;
+    command: string;
+    envMapping?: DockerEnvMap | undefined;
+    executionEnv?: Record<string, string> | undefined;
+    dockerFlags?: ReadonlyArray<string> | undefined;
+};
+
+export async function runContainerCommand({
+    tty,
+    containerNameOrId,
+    command,
+    envMapping,
+    executionEnv,
+    dockerFlags = [],
+}: RunDockerContainerCommandParams) {
+    const envFlags = makeEnvFlags(envMapping);
+    /** Can't test tty in automated tests. */
+    /* node:coverage ignore next 1 */
+    const ttyFlag = tty ? '-it' : '';
+
+    const fullCommand = [
+        'docker',
+        'exec',
+        ttyFlag,
+        envFlags,
+        ...dockerFlags,
+        containerNameOrId,
+        command,
+    ]
+        .filter(check.isTruthy)
+        .join(' ');
+
+    return await runShellCommand(fullCommand, {
+        env: executionEnv,
+        rejectOnError: true,
+    });
+}

package/src/docker/containers/run-container.mock.ts

@@ -0,0 +1,17 @@
+import {docker} from '../../augments/docker.js';
+import {RunDockerContainerParams} from './run-container.js';
+
+export async function runMockLongLivingContainer(
+    containerName: string,
+    args: Partial<RunDockerContainerParams> = {},
+) {
+    await docker.container.run({
+        containerName: containerName,
+        detach: true,
+        imageName: 'alpine:3.20.2',
+        dockerFlags: ['-i', '-t'],
+        command: 'sh',
+        platform: 'amd64',
+        ...args,
+    });
+}

package/src/docker/containers/run-container.ts

@@ -0,0 +1,92 @@
+import {check} from '@augment-vir/assert';
+import {runShellCommand} from '../../augments/terminal/shell.js';
+import {updateImage} from '../docker-image.js';
+import {waitUntilContainerRunning} from './container-status.js';
+import {
+    DockerEnvMap,
+    DockerPortMap,
+    DockerVolumeMap,
+    makeEnvFlags,
+    makePortMapFlags,
+    makeVolumeFlags,
+} from './docker-command-inputs.js';
+import {killContainer} from './kill-container.js';
+
+/**
+ * Parameters for `docker.container.run`.
+ *
+ * @category Node : Docker : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type RunDockerContainerParams = {
+    imageName: string;
+    detach: boolean;
+    command?: string;
+    containerName: string;
+    volumeMapping?: ReadonlyArray<DockerVolumeMap> | undefined;
+    portMapping?: ReadonlyArray<DockerPortMap> | undefined;
+    envMapping?: DockerEnvMap | undefined;
+    executionEnv?: Record<string, string>;
+    removeWhenDone?: boolean;
+    dockerFlags?: ReadonlyArray<string>;
+    useCurrentUser?: boolean;
+    platform?: string;
+};
+
+export async function runContainer({
+    containerName,
+    imageName,
+    detach,
+    command,
+    portMapping,
+    volumeMapping,
+    envMapping,
+    executionEnv,
+    removeWhenDone,
+    useCurrentUser,
+    dockerFlags = [],
+    platform,
+}: RunDockerContainerParams) {
+    try {
+        const portMapFlags = makePortMapFlags(portMapping);
+        const envFlags = makeEnvFlags(envMapping);
+        const detachFlag = detach ? '-d' : '';
+        const volumeMapFlags = makeVolumeFlags(volumeMapping);
+        const rmFlag = removeWhenDone ? '--rm' : '';
+        const userFlag = useCurrentUser ? '--user "$(id -u)":"$(id -g)"' : '';
+
+        await updateImage(imageName, platform);
+
+        const fullCommand = [
+            'docker',
+            'run',
+            portMapFlags,
+            userFlag,
+            volumeMapFlags,
+            envFlags,
+            rmFlag,
+            detachFlag,
+            `--name='${containerName}'`,
+            ...dockerFlags,
+            imageName,
+            command,
+        ]
+            .filter(check.isTruthy)
+            .join(' ');
+
+        await runShellCommand(fullCommand, {
+            env: executionEnv,
+            rejectOnError: true,
+        });
+
+        if (removeWhenDone) {
+            await killContainer(containerName);
+        } else if (detach) {
+            await waitUntilContainerRunning(containerName);
+        }
+    } catch (error) {
+        await killContainer(containerName);
+        throw error;
+    }
+}

package/src/docker/containers/try-or-kill-container.ts

@@ -0,0 +1,18 @@
+import {type MaybePromise} from '@augment-vir/core';
+import {killContainer} from './kill-container.js';
+
+/**
+ * Runs a callback (which presumably runs a command within the given `containerName`) and kills the
+ * given `containerName` container if the callback fails.
+ */
+export async function tryOrKillContainer<T>(
+    containerNameOrId: string,
+    callback: (containerNameOrId: string) => MaybePromise<T>,
+): Promise<Awaited<T>> {
+    try {
+        return await callback(containerNameOrId);
+    } catch (error) {
+        await killContainer(containerNameOrId);
+        throw error;
+    }
+}

package/src/docker/docker-image.ts

@@ -0,0 +1,56 @@
+import {wrapString} from '@augment-vir/common';
+import {ensureError} from '@augment-vir/core';
+import {runShellCommand} from '../augments/terminal/shell.js';
+
+export async function updateImage(
+    /** @example 'alpine:3.20.2' */
+    imageName: string,
+    platform?: string,
+) {
+    if (await isImageInLocalRegistry(imageName)) {
+        /** If image already exists then we don't need to update it. */
+        return;
+    }
+
+    const command = [
+        'docker',
+        'pull',
+        ...(platform ? ['--platform', platform] : []),
+        wrapString({value: imageName, wrapper: "'"}),
+    ].join(' ');
+
+    await runShellCommand(command, {
+        rejectOnError: true,
+    });
+}
+
+export async function isImageInLocalRegistry(
+    /** @example 'alpine:3.20.2' */
+    imageName: string,
+): Promise<boolean> {
+    const output = await runShellCommand(`docker inspect '${imageName}'`);
+
+    return output.exitCode === 0;
+}
+
+export async function removeImageFromLocalRegistry(
+    /** @example 'alpine:3.20.2' */
+    imageName: string,
+) {
+    try {
+        await runShellCommand(`docker image rm '${imageName}'`, {
+            rejectOnError: true,
+        });
+    } catch (caught) {
+        const error = ensureError(caught);
+
+        if (error.message.includes('No such image:')) {
+            /** Ignore the case where the image has already been deleted. */
+            return;
+        }
+
+        /** An edge case that I don't know how to intentionally trigger. */
+        /* node:coverage ignore next 2 */
+        throw error;
+    }
+}

package/src/docker/docker-startup.ts

@@ -0,0 +1,49 @@
+import {waitUntil} from '@augment-vir/assert';
+import {currentOperatingSystem, OperatingSystem} from '../augments/os/operating-system.js';
+import {runShellCommand} from '../augments/terminal/shell.js';
+
+export async function isDockerRunning() {
+    const output = await runShellCommand('docker info');
+
+    return output.exitCode === 0;
+}
+
+const startDockerCommands: Record<OperatingSystem, string> = {
+    /**
+     * Officially supported for the following distros:
+     *
+     * - [Ubuntu](https://docs.docker.com/desktop/install/ubuntu/#launch-docker-desktop)
+     * - [Debian](https://docs.docker.com/desktop/install/debian/#launch-docker-desktop)
+     * - [Fedora](https://docs.docker.com/desktop/install/fedora/#launch-docker-desktop)
+     * - [Arch](https://docs.docker.com/desktop/install/archlinux/#launch-docker-desktop)
+     */
+    [OperatingSystem.Linux]: 'systemctl --user start docker-desktop',
+    [OperatingSystem.Mac]: 'open -a Docker',
+    [OperatingSystem.Windows]: String.raw`/c/Program\ Files/Docker/Docker/Docker\ Desktop.exe`,
+};
+
+export async function startDocker() {
+    const command = startDockerCommands[currentOperatingSystem];
+
+    /* node:coverage disable */
+    if (await isDockerRunning()) {
+        /** Docker is already running. Nothing to do. */
+        return;
+    }
+
+    await waitUntil.isTrue(
+        async () => {
+            await runShellCommand(command, {rejectOnError: true});
+            return isDockerRunning();
+        },
+        {
+            interval: {
+                seconds: 1,
+            },
+            timeout: {
+                minutes: 1,
+            },
+        },
+        'Failed to start Docker.',
+    );
+}

package/src/docker/run-docker-test.mock.ts

@@ -0,0 +1,26 @@
+import {type MaybePromise} from '@augment-vir/common';
+import {isOperatingSystem, OperatingSystem} from '../augments/os/operating-system.js';
+
+export function dockerTest(callback: () => MaybePromise<void>) {
+    if (!isOperatingSystem(OperatingSystem.Linux) && process.env.CI) {
+        /**
+         * We cannot test Docker on macOS GitHub Actions runners.
+         *
+         * @see
+         * - https://github.com/actions/runner-images/issues/8104
+         * - https://github.com/douglascamata/setup-docker-macos-action?tab=readme-ov-file#arm64-processors-m1-m2-m3-series-used-on-macos-14-images-are-unsupported
+         * - https://github.com/actions/runner-images/issues/2150
+         * - https://github.com/actions/runner/issues/1456
+         */
+        /**
+         * We cannot test Docker on Windows GitHub Actions runners because Docker cannot run in
+         * Linux container mode on Windows GitHub Actions runners.
+         *
+         * @see
+         * - https://github.com/orgs/community/discussions/25491#discussioncomment-3248089
+         */
+        return () => {};
+    }
+
+    return callback;
+}

package/src/file-paths.mock.ts

@@ -0,0 +1,29 @@
+import {dirname, join} from 'node:path';
+
+export const monoRepoDirPath = dirname(dirname(dirname(import.meta.dirname)));
+export const notCommittedDirPath = join(monoRepoDirPath, '.not-committed');
+
+export const nodePackageDir = dirname(import.meta.dirname);
+
+export const testFilesDir = join(nodePackageDir, 'test-files');
+const longRunningFileDir = join(testFilesDir, 'long-running-test-file');
+export const dirContentsTestDir = join(testFilesDir, 'dir-contents-test');
+export const longRunningFilePath = join(longRunningFileDir, 'long-running-file.ts');
+export const longRunningFileWithStderr = join(
+    longRunningFileDir,
+    'long-running-file-with-stderr.ts',
+);
+export const workspaceQueryDir = join(testFilesDir, 'workspace-query');
+export const workspaceQueryPackageJsonPath = join(workspaceQueryDir, 'package.json');
+export const tempWorkspaceQueryFile = join(workspaceQueryDir, 'temp-workspace-query-output.ts');
+
+export const recursiveFileReadDir = join(testFilesDir, 'recursive-reading');
+
+export const invalidPackageDirPath = join(testFilesDir, 'invalid-package');
+
+export const testPrismaSchemaPath = join(testFilesDir, 'schema.prisma');
+export const testPrismaSchema2Path = join(testFilesDir, 'schema2.prisma');
+export const testInvalidPrismaSchemaPath = join(testFilesDir, 'invalid-schema.prisma');
+export const testSqliteDbPath = join(notCommittedDirPath, 'dev.db');
+export const generatedPrismaClientDirPath = join(nodePackageDir, 'node_modules', '.prisma');
+export const testPrismaMigrationsDirPath = join(testFilesDir, 'migrations');

package/src/index.ts

@@ -0,0 +1,19 @@
+export * from './augments/docker.js';
+export * from './augments/fs/dir-contents.js';
+export * from './augments/fs/download.js';
+export * from './augments/fs/json.js';
+export * from './augments/fs/read-dir.js';
+export * from './augments/fs/read-file.js';
+export * from './augments/fs/symlink.js';
+export * from './augments/fs/write.js';
+export * from './augments/npm/query-workspace.js';
+export * from './augments/npm/read-package-json.js';
+export * from './augments/os/operating-system.js';
+export * from './augments/path/ancestor.js';
+export * from './augments/path/os-path.js';
+export * from './augments/path/root.js';
+export * from './augments/prisma.js';
+export * from './augments/terminal/question.js';
+export * from './augments/terminal/relevant-args.js';
+export * from './augments/terminal/run-cli-script.js';
+export * from './augments/terminal/shell.js';

package/src/prisma/disable-ci-env.mock.ts

@@ -0,0 +1,88 @@
+// cspell:disable
+
+import {arrayToObject, type MaybePromise} from '@augment-vir/common';
+
+/**
+ * These are all the env flags that Prisma reads for determining if it's being executed within a CI
+ * environment. This list was retrieved from
+ * https://github.com/prisma/prisma/blob/075d31287c90b757fd9bd8d9b36032e6349fa671/packages/internals/src/utils/isCi.ts.
+ */
+const prismaCiFlags = [
+    'CI',
+    'CONTINUOUS_INTEGRATION',
+    'BUILD_NUMBER',
+    'RUN_ID',
+    'AGOLA_GIT_REF',
+    'AC_APPCIRCLE',
+    'APPVEYOR',
+    'CODEBUILD',
+    'TF_BUILD',
+    'bamboo_planKey',
+    'BITBUCKET_COMMIT',
+    'BITRISE_IO',
+    'BUDDY_WORKSPACE_ID',
+    'BUILDKITE',
+    'CIRCLECI',
+    'CIRRUS_CI',
+    'CF_BUILD_ID',
+    'CM_BUILD_ID',
+    'CI_NAME',
+    'DRONE',
+    'DSARI',
+    'EARTHLY_CI',
+    'EAS_BUILD',
+    'GERRIT_PROJECT',
+    'GITEA_ACTIONS',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'GOCD',
+    'BUILDER_OUTPUT',
+    'HARNESS_BUILD_ID',
+    'JENKINS_URL',
+    'BUILD_ID',
+    'LAYERCI',
+    'MAGNUM',
+    'NETLIFY',
+    'NEVERCODE',
+    'PROW_JOB_ID',
+    'RELEASE_BUILD_ID',
+    'RENDER',
+    'SAILCI',
+    'HUDSON',
+    'JENKINS_URL',
+    'BUILD_ID',
+    'SCREWDRIVER',
+    'SEMAPHORE',
+    'SOURCEHUT',
+    'STRIDER',
+    'TASK_ID',
+    'RUN_ID',
+    'TEAMCITY_VERSION',
+    'TRAVIS',
+    'VELA',
+    'NOW_BUILDER',
+    'APPCENTER_BUILD_ID',
+    'CI_XCODE_PROJECT',
+    'XCS',
+];
+
+export function testWithNonCiEnv(callback: () => MaybePromise<void>) {
+    return async () => {
+        const usedKeys = prismaCiFlags.filter((ciFlag) => ciFlag in process.env);
+
+        /** For already non-CI environments. */
+        /* node:coverage ignore next 6 */
+        const originalEnvValues = arrayToObject(usedKeys, (key) => {
+            return {
+                key,
+                value: process.env[key],
+            };
+        });
+
+        usedKeys.forEach((key) => delete process.env[key]);
+
+        await callback();
+
+        usedKeys.forEach((key) => (process.env[key] = originalEnvValues[key]));
+    };
+}

package/src/prisma/model-data.ts

@@ -0,0 +1,213 @@
+import {assert, check} from '@augment-vir/assert';
+import {
+    AnyObject,
+    arrayToObject,
+    awaitedForEach,
+    BasePrismaClient,
+    ensureErrorAndPrependMessage,
+    filterMap,
+    getObjectTypedEntries,
+    getObjectTypedValues,
+    mergeDefinedProperties,
+    omitObjectKeys,
+    PrismaAllModelsCreate,
+    prismaModelCreateExclude,
+    prismaModelCreateOmitId,
+    type PartialWithUndefined,
+    type PrismaAllBasicModels,
+    type PrismaModelName,
+} from '@augment-vir/common';
+import type {IsAny} from 'type-fest';
+
+/**
+ * Params for {@link addData}. This is similar to {@link PrismaAllModelsCreate} but allows an array of
+ * {@link PrismaAllModelsCreate} for sequential data creation.
+ *
+ * @category Prisma : Node
+ * @category Package : @augment-vir/node
+ * @example
+ *
+ * ```ts
+ * import {PrismaAddModelData} from '@augment-vir/common';
+ * import type {PrismaClient} from '@prisma/client';
+ *
+ * const mockData: PrismaAddModelData<PrismaClient> = [
+ *     {
+ *         user: {
+ *             mockUser1: {
+ *                 first_name: 'one',
+ *                 id: 123,
+ *                 // etc.
+ *             },
+ *             mockUser2: {
+ *                 first_name: 'two',
+ *                 id: 124,
+ *                 authRole: 'user',
+ *                 // etc.
+ *             },
+ *         },
+ *     },
+ *     {
+ *         region: [
+ *             {
+ *                 id: 1,
+ *                 name: 'North America',
+ *                 // etc.
+ *             },
+ *             {
+ *                 id: 2,
+ *                 name: 'Europe',
+ *                 // etc.
+ *             },
+ *         ],
+ *     },
+ * ];
+ * ```
+ *
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type PrismaAddDataData<PrismaClient extends BasePrismaClient> =
+    | Readonly<PrismaAllModelsCreate<PrismaClient>>
+    | ReadonlyArray<Readonly<PrismaAllModelsCreate<PrismaClient>>>;
+
+export async function addData<const PrismaClient extends BasePrismaClient>(
+    prismaClient: Readonly<PrismaClient>,
+    data: IsAny<PrismaClient> extends true ? any : PrismaAddDataData<PrismaClient>,
+): Promise<void> {
+    const dataArray: Record<string, AnyObject>[] = (check.isArray(data) ? data : [data]) as Record<
+        string,
+        AnyObject
+    >[];
+
+    await awaitedForEach(dataArray, async (dataEntry) => {
+        await addModelDataObject(prismaClient, dataEntry);
+    });
+}
+
+async function addModelDataObject(
+    prismaClient: Readonly<BasePrismaClient>,
+    data: Record<string, AnyObject>,
+) {
+    /** Add the mock data to the mock prisma client. */
+    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
+         * already type guarded).
+         */
+        const mockModelInstances: AnyObject[] = Array.isArray(mockData)
+            ? mockData
+            : getObjectTypedValues(mockData);
+
+        const modelApi: AnyObject | undefined = prismaClient[modelName];
+
+        assert.isDefined(modelApi, `No PrismaClient API found for model '${modelName}'`);
+
+        try {
+            const allData = filterMap(
+                mockModelInstances,
+                (entry) => {
+                    return entry;
+                },
+                (mapped, modelEntry) => !modelEntry[prismaModelCreateExclude],
+            );
+
+            await awaitedForEach(allData, async (modelEntry) => {
+                if (modelEntry[prismaModelCreateOmitId]) {
+                    modelEntry = omitObjectKeys<AnyObject, PropertyKey>(modelEntry, ['id']);
+                }
+
+                await modelApi.create({
+                    data: modelEntry,
+                });
+            });
+        } catch (error) {
+            throw ensureErrorAndPrependMessage(
+                error,
+                `Failed to create many '${modelName}' entries.\n\n${JSON.stringify(mockModelInstances, null, 4)}\n\n`,
+            );
+        }
+    });
+}
+
+const prismockKeys = ['getData', 'setData'];
+
+export function getAllPrismaModelNames<const PrismaClient extends BasePrismaClient>(
+    prismaClient: PrismaClient,
+): PrismaModelName<PrismaClient>[] {
+    return Object.keys(prismaClient)
+        .filter(
+            (key) => !key.startsWith('$') && !key.startsWith('_') && !prismockKeys.includes(key),
+        )
+        .sort() as PrismaModelName<PrismaClient>[];
+}
+
+/**
+ * Options for `prisma.client.dumpData`.
+ *
+ * @category Prisma : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type PrismaDataDumpOptions = {
+    /**
+     * The max number of entries to load per model. Set to `0` to remove this limit altogether
+     * (which could be _very_ expensive for your database).
+     *
+     * @default 100
+     */
+    limit: number;
+    /**
+     * Strings to omit from the dumped data. For testability, omitting date or UUID id fields is a
+     * common practice.
+     */
+    omitFields: string[];
+};
+
+const defaultPrismaDumpDataOptions: PrismaDataDumpOptions = {
+    limit: 100,
+    omitFields: [],
+};
+
+export async function dumpData<const PrismaClient extends BasePrismaClient>(
+    prismaClient: PrismaClient,
+    options: Readonly<PartialWithUndefined<PrismaDataDumpOptions>> = {},
+): Promise<PrismaAllBasicModels<PrismaClient>> {
+    const modelNames = getAllPrismaModelNames(prismaClient);
+    const finalOptions = mergeDefinedProperties(defaultPrismaDumpDataOptions, options);
+
+    const data: Partial<Record<PrismaModelName<PrismaClient>, AnyObject[]>> = await arrayToObject(
+        modelNames,
+        async (modelName) => {
+            try {
+                const entries: AnyObject[] = await prismaClient[modelName].findMany(
+                    finalOptions.limit > 0
+                        ? {
+                              take: finalOptions.limit,
+                          }
+                        : {},
+                );
+
+                if (!entries.length) {
+                    return undefined;
+                }
+
+                const filteredEntries = finalOptions.omitFields.length
+                    ? entries.map((entry) => omitObjectKeys(entry, finalOptions.omitFields))
+                    : entries;
+
+                return {
+                    key: modelName,
+                    value: filteredEntries,
+                };
+            } catch (error) {
+                throw ensureErrorAndPrependMessage(
+                    error,
+                    `Failed to read data for model '${modelName}'`,
+                );
+            }
+        },
+    );
+
+    return data as PrismaAllBasicModels<PrismaClient>;
+}