@augment-vir/node 31.0.0 → 31.1.0

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>;
+}

package/src/prisma/prisma-client.ts

@@ -0,0 +1,43 @@
+import {collapseWhiteSpace} from '@augment-vir/common';
+import {existsSync} from 'node:fs';
+import {readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {runPrismaCommand} from './run-prisma-command.js';
+
+export async function generatePrismaClient(
+    schemaFilePath: string,
+    env: Record<string, string> = {},
+) {
+    await runPrismaCommand({command: 'generate'}, schemaFilePath, env);
+}
+
+async function areSchemasEqual(
+    originalSchema: string,
+    generatedClientSchema: string,
+): Promise<boolean> {
+    if (!existsSync(originalSchema)) {
+        throw new Error(`Schema file does not exist: '${originalSchema}'`);
+    } else if (!existsSync(generatedClientSchema)) {
+        return false;
+    }
+
+    const originalSchemaContents: string = String(await readFile(originalSchema));
+    const generatedClientSchemaContents: string = String(await readFile(generatedClientSchema));
+
+    return (
+        collapseWhiteSpace(originalSchemaContents, {keepNewLines: true}) ===
+        collapseWhiteSpace(generatedClientSchemaContents, {keepNewLines: true})
+    );
+}
+
+export async function isGeneratedPrismaClientCurrent({
+    jsClientOutputDir,
+    schemaFilePath,
+}: {
+    schemaFilePath: string;
+    jsClientOutputDir: string;
+}) {
+    const clientSchemaFilePath = join(jsClientOutputDir, 'schema.prisma');
+
+    return areSchemasEqual(schemaFilePath, clientSchemaFilePath);
+}

package/src/prisma/prisma-database.mock.ts

@@ -0,0 +1,31 @@
+import {awaitedForEach, callWithRetries, wait} from '@augment-vir/common';
+import {interpolationSafeWindowsPath} from '../augments/path/os-path.js';
+import {runShellCommand} from '../augments/terminal/shell.js';
+import {
+    generatedPrismaClientDirPath,
+    notCommittedDirPath,
+    testPrismaMigrationsDirPath,
+} from '../file-paths.mock.js';
+
+const pathsToDelete = [
+    generatedPrismaClientDirPath,
+    notCommittedDirPath,
+    testPrismaMigrationsDirPath,
+];
+
+export async function clearTestDatabaseOutputs() {
+    await callWithRetries(10, async () => {
+        await wait({seconds: 1});
+        await awaitedForEach(pathsToDelete, async (pathToDelete) => {
+            /**
+             * This way of deleting files is required for Windows tests running on GitHub Actions.
+             * Otherwise, we get the following error:
+             *
+             *     EPERM: operation not permitted, unlink 'D:\a\augment-vir\augment-vir\packages\node\node_modules\.prisma\query_engine-windows.dll.node'
+             */
+            await runShellCommand(`rm -rf ${interpolationSafeWindowsPath(pathToDelete)}`, {
+                rejectOnError: true,
+            });
+        });
+    });
+}

package/src/prisma/prisma-database.ts

@@ -0,0 +1,35 @@
+import {runPrismaCommand} from './run-prisma-command.js';
+
+export async function getPrismaDiff(
+    schemaFilePath: string,
+    env: Record<string, string> = {},
+): Promise<string> {
+    const command = [
+        'migrate',
+        'diff',
+        `--from-schema-datamodel='${schemaFilePath}'`,
+        `--to-schema-datasource='${schemaFilePath}'`,
+    ].join(' ');
+
+    const results = await runPrismaCommand({command}, undefined, env);
+
+    if (results.stdout.trim() === 'No difference detected.') {
+        return '';
+    } else {
+        return results.stdout.trim();
+    }
+}
+
+export async function doesPrismaDiffExist(
+    schemaFilePath: string,
+    env: Record<string, string> = {},
+): Promise<boolean> {
+    return !!(await getPrismaDiff(schemaFilePath, env));
+}
+
+export async function resetDevPrismaDatabase(
+    schemaFilePath: string,
+    env: Record<string, string> = {},
+) {
+    await runPrismaCommand({command: 'migrate reset --force'}, schemaFilePath, env);
+}

package/src/prisma/prisma-errors.ts

@@ -0,0 +1,45 @@
+/**
+ * An error thrown by the Prisma API that indicates that something is wrong with the given Prisma
+ * schema. See the error message for more details.
+ *
+ * @category Prisma : Node : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export class PrismaSchemaError extends Error {
+    public override readonly name = 'PrismaSchemaError';
+    constructor(message: string) {
+        super(message);
+    }
+}
+
+/**
+ * An error thrown by the Prisma API that indicates that applying migrations in dev failed such that
+ * a new migration is needed. You can do that by prompting user for a new migration name and passing
+ * it to `prisma.migration.create`.
+ *
+ * @category Prisma : Node : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export class PrismaMigrationNeededError extends Error {
+    public override readonly name = 'PrismaMigrationNeededError';
+    constructor(schemaFilePath: string) {
+        super(`A new Prisma migration is needed for '${schemaFilePath}'`);
+    }
+}
+
+/**
+ * An error thrown by the Prisma API that indicates that applying migrations in dev failed such that
+ * the entire database needs to be reset. You can do that by calling `prisma.database.resetDev`.
+ *
+ * @category Prisma : Node : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export class PrismaResetNeededError extends Error {
+    public override readonly name = 'PrismaResetNeededError';
+    constructor(schemaFilePath: string) {
+        super(`A database reset is needed for '${schemaFilePath}'`);
+    }
+}

package/src/prisma/prisma-migrations.ts

@@ -0,0 +1,149 @@
+import {check} from '@augment-vir/assert';
+import {log, safeMatch, toEnsuredNumber} from '@augment-vir/common';
+import terminate from 'terminate';
+import {runShellCommand} from '../augments/terminal/shell.js';
+import {PrismaMigrationNeededError, PrismaResetNeededError} from './prisma-errors.js';
+import {runPrismaCommand, verifyOutput} from './run-prisma-command.js';
+
+/**
+ * Output of `prisma.migration.status`.
+ *
+ * @category Prisma : Node : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type PrismaMigrationStatus = {
+    totalMigrations: number;
+    unappliedMigrations: string[];
+};
+
+export async function applyPrismaMigrationsToProd(
+    schemaFilePath: string,
+    env: Record<string, string> = {},
+) {
+    await runPrismaCommand({command: 'migrate deploy'}, schemaFilePath, env);
+}
+
+enum DbChangeRequired {
+    MigrationNeeded = 'migration-needed',
+    ResetNeeded = 'reset-needed',
+}
+
+export async function applyPrismaMigrationsToDev(
+    schemaFilePath: string,
+    env: Record<string, string> = {},
+) {
+    const command = ['prisma', 'migrate', 'dev', `--schema='${schemaFilePath}'`].join(' ');
+
+    log.faint(`> ${command}`);
+
+    let dbRequirement = undefined as DbChangeRequired | undefined;
+
+    const result = await runShellCommand(command, {
+        env: {
+            ...process.env,
+            ...env,
+        },
+        stdoutCallback(stdout, childProcess) {
+            if (stdout.includes('Enter a name for the new migration')) {
+                if (childProcess.pid) {
+                    terminate(childProcess.pid);
+                }
+                dbRequirement = DbChangeRequired.MigrationNeeded;
+            }
+        },
+        stderrCallback(stderr, childProcess) {
+            if (
+                stderr.includes(
+                    'Prisma Migrate has detected that the environment is non-interactive, which is not supported',
+                )
+            ) {
+                if (childProcess.pid) {
+                    terminate(childProcess.pid);
+                }
+                dbRequirement = DbChangeRequired.ResetNeeded;
+            }
+        },
+    });
+
+    if (dbRequirement === DbChangeRequired.MigrationNeeded) {
+        throw new PrismaMigrationNeededError(schemaFilePath);
+    } else if (dbRequirement === DbChangeRequired.ResetNeeded) {
+        throw new PrismaResetNeededError(schemaFilePath);
+    }
+    verifyOutput(schemaFilePath, result, false);
+}
+
+export async function getMigrationStatus(
+    schemaFilePath: string,
+    env: Record<string, string> = {},
+): Promise<PrismaMigrationStatus> {
+    const output = await runPrismaCommand(
+        {
+            command: 'migrate status',
+            ignoreExitCode: true,
+        },
+        schemaFilePath,
+        env,
+    );
+
+    const listedMigrations: PrismaMigrationStatus = {
+        totalMigrations: 0,
+        unappliedMigrations: [],
+    };
+
+    let foundNotAppliedMigrations = false;
+
+    output.stdout.split('\n').some((rawLine) => {
+        const line = rawLine.trim();
+        if (foundNotAppliedMigrations) {
+            if (line) {
+                listedMigrations.unappliedMigrations.push(line);
+            } else {
+                /** We're done parsing. */
+                return true;
+            }
+        } else if (line.endsWith('not yet been applied:')) {
+            foundNotAppliedMigrations = true;
+        } else {
+            const [, countMatch] = safeMatch(line, /^([\d,]+) migrations? found in/);
+
+            if (countMatch) {
+                listedMigrations.totalMigrations = toEnsuredNumber(countMatch);
+            }
+        }
+
+        /** Still need to keep parsing. */
+        return false;
+    });
+
+    return listedMigrations;
+}
+
+export async function createPrismaMigration(
+    {
+        migrationName,
+        createOnly = false,
+    }: {
+        migrationName: string;
+        /**
+         * Set this to `true` to create a new migration without applying it to the database.
+         *
+         * @default false
+         */
+        createOnly?: boolean | undefined;
+    },
+    schemaFilePath: string,
+    env: Record<string, string> = {},
+) {
+    const command = [
+        'migrate',
+        'dev',
+        `--name='${migrationName}'`,
+        createOnly ? '--create-only' : '',
+    ]
+        .filter(check.isTruthy)
+        .join(' ');
+
+    await runPrismaCommand({command}, schemaFilePath, env);
+}

package/src/prisma/run-prisma-command.ts

@@ -0,0 +1,59 @@
+import {log} from '@augment-vir/common';
+import {interpolationSafeWindowsPath} from '../augments/path/os-path.js';
+import {runShellCommand, type ShellOutput} from '../augments/terminal/shell.js';
+import {PrismaSchemaError} from './prisma-errors.js';
+
+const prismaCommandsThatSupportNoHints = ['generate'];
+
+export async function runPrismaCommand(
+    {
+        command,
+        ignoreExitCode = false,
+    }: {
+        command: string;
+        ignoreExitCode?: boolean | undefined;
+    },
+    /** Set to `undefined` to omit the `--schema` flag. */
+    schemaFilePath: string | undefined,
+    env: Record<string, string> | undefined = {},
+) {
+    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(' ');
+
+    log.faint(`> ${fullCommand}`);
+
+    const result = await runShellCommand(interpolationSafeWindowsPath(fullCommand), {
+        env: {
+            ...process.env,
+            ...env,
+        },
+    });
+
+    return verifyOutput(schemaFilePath || '', result, ignoreExitCode);
+}
+
+export function verifyOutput(
+    schemaFilePath: string,
+    shellOutput: Readonly<ShellOutput>,
+    ignoreExitCode: boolean,
+) {
+    if (shellOutput.stderr.includes('Validation Error Count')) {
+        throw new PrismaSchemaError(
+            `Invalid schema file at '${schemaFilePath}':\n\n${shellOutput.stderr}`,
+        );
+    } else if (shellOutput.stderr.includes('does not exist at')) {
+        throw new PrismaSchemaError(`Database does not exist: ${shellOutput.stderr}`);
+    } else if (shellOutput.exitCode === 0 || ignoreExitCode) {
+        return shellOutput;
+    } else {
+        throw new Error(shellOutput.stdout + shellOutput.stderr);
+    }
+}