@augment-vir/node 31.0.1 → 31.1.1

package/src/augments/os/operating-system.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 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 const currentOperatingSystem: OperatingSystem = 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: OperatingSystem): boolean {
+    return currentOperatingSystem === operatingSystem;
+}
+
+function getOperatingSystem(): OperatingSystem {
+    /** We can't test all of these on a single system. */
+    /* node:coverage ignore next 7 */
+    if (process.platform === 'win32') {
+        return OperatingSystem.Windows;
+    } else if (process.platform === 'darwin') {
+        return OperatingSystem.Mac;
+    } else {
+        return OperatingSystem.Linux;
+    }
+}

package/src/augments/path/ancestor.ts

@@ -0,0 +1,78 @@
+import {check} from '@augment-vir/assert';
+import {type MaybePromise} from '@augment-vir/common';
+import {dirname, join} from 'node:path';
+import {systemRootPath} from './root.js';
+
+export function findAncestor(
+    currentPath: string,
+    callback: (path: string) => Promise<boolean>,
+): Promise<string | undefined>;
+export function findAncestor(
+    currentPath: string,
+    callback: (path: string) => boolean,
+): string | undefined;
+export function findAncestor(
+    currentPath: string,
+    callback: (path: string) => MaybePromise<boolean>,
+): MaybePromise<string | undefined>;
+/**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the way
+ * up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function findAncestor(
+    currentPath: string,
+    callback: (path: string) => MaybePromise<boolean>,
+): MaybePromise<string | undefined> {
+    if (currentPath === systemRootPath) {
+        return undefined;
+    }
+
+    const result = callback(currentPath);
+
+    if (check.isPromise(result)) {
+        return new Promise<string | undefined>(async (resolve) => {
+            const awaitedResult = await result;
+
+            if (awaitedResult) {
+                resolve(currentPath);
+            } else {
+                resolve(await findAncestor(dirname(currentPath), callback));
+            }
+        });
+    } else if (result) {
+        return currentPath;
+    } else {
+        return findAncestor(dirname(currentPath), callback);
+    }
+}
+
+/**
+ * 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 function joinFilesToDir(
+    parentDirPath: string,
+    childNames: ReadonlyArray<string>,
+): Array<string> {
+    return childNames.map((childName) => join(parentDirPath, childName));
+}

package/src/augments/path/os-path.ts

@@ -0,0 +1,45 @@
+import {sep} from 'node:path';
+
+/**
+ * Convert a given path to a windows path if the current system doesn't use `/`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function replaceWithWindowsPathIfNeeded(input: string): string {
+    /** No single system will test all of these lines so we must ignore them all. */
+    /* node:coverage ignore next 5 */
+    if (sep === '/') {
+        return input;
+    } else {
+        return input.replace(/\//g, sep);
+    }
+}
+
+/**
+ * Convert a Windows path to a posix path.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function toPosixPath(maybeWindowsPath: string): string {
+    return maybeWindowsPath
+        .replace(/^(.+?):\\+/, (match, captureGroup) => {
+            return `/${captureGroup.toLowerCase()}/`;
+        })
+        .replace(/\\+/g, '/');
+}
+
+/**
+ * Use this to interpolate paths into bash commands. If the given path is not a Windows path, the
+ * path structure will not be modified.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function interpolationSafeWindowsPath(input: string): string {
+    return input.replace(/\\/g, '\\\\\\\\');
+}

package/src/augments/path/root.ts

@@ -0,0 +1,14 @@
+import {parse} from 'node:path';
+
+function getSystemRootPath() {
+    return parse(process.cwd()).root;
+}
+
+/**
+ * The root path of the system containing the cwd.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export const systemRootPath = getSystemRootPath();

package/src/augments/prisma.ts

@@ -0,0 +1,174 @@
+import {addData, dumpData, getAllPrismaModelNames} from '../prisma/model-data.js';
+import {generatePrismaClient, isGeneratedPrismaClientCurrent} from '../prisma/prisma-client.js';
+import {
+    doesPrismaDiffExist,
+    getPrismaDiff,
+    resetDevPrismaDatabase,
+} from '../prisma/prisma-database.js';
+import {
+    applyPrismaMigrationsToDev,
+    applyPrismaMigrationsToProd,
+    createPrismaMigration,
+    getMigrationStatus,
+} from '../prisma/prisma-migrations.js';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type {PrismaMigrationNeededError, PrismaResetNeededError} from '../prisma/prisma-errors.js';
+
+export type {
+    PrismaAddDataData as PrismaAddModelData,
+    PrismaDataDumpOptions,
+} from '../prisma/model-data.js';
+export * from '../prisma/prisma-errors.js';
+export type {PrismaMigrationStatus} from '../prisma/prisma-migrations.js';
+
+/**
+ * Centralized Prisma API from `@augment-vir/node`.
+ *
+ * ## Prisma flows
+ *
+ * - Deploy to production
+ *
+ *   - {@link prisma.migration.applyProd}
+ * - Update dev environment
+ *
+ *   - Apply migrations: {@link prisma.migration.applyDev}
+ *
+ *       - If throws {@link PrismaMigrationNeededError}, prompt user for a new migration name and pass it to
+ *               {@link prisma.migration.create}
+ *       - If throws {@link PrismaResetNeededError}, reset the database with {@link prisma.database.resetDev}
+ *   - Generate client: `prisma.client.isCurrent`
+ *
+ *       - If `false`, run {@link prisma.client.generate}
+ *
+ * @category Prisma : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export const prisma = {
+    migration: {
+        /**
+         * Get current migration status.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-status
+         */
+        status: getMigrationStatus,
+        /**
+         * Creates a new migration.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-dev
+         */
+        create: createPrismaMigration,
+        /**
+         * Apply all migrations. Meant for a production environment.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-deploy
+         */
+        applyProd: applyPrismaMigrationsToProd,
+        /**
+         * Apply all migrations. Meant for a development environment, with less protections than
+         * {@link prisma.migration.applyProd}.
+         *
+         * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs
+         *   to input a name.
+         * @throws `PrismaResetNeededError` when there's a migration mismatch with the database and
+         *   it needs to be reset.
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-dev
+         */
+        applyDev: applyPrismaMigrationsToDev,
+    },
+    database: {
+        /**
+         * Force resets a dev database to match the current Prisma schema and migrations.
+         *
+         * **This will destroy all data. Do not use in production.**
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-reset
+         */
+        resetDev: resetDevPrismaDatabase,
+        /**
+         * Uses {@link prisma.database.diff} to detect if there are any differences between the
+         * current database and the Prisma schema that should control it.
+         */
+        hasDiff: doesPrismaDiffExist,
+        /**
+         * Gets a string list of all differences between the current database and the Prisma schema
+         * that should control it.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-diff
+         */
+        diff: getPrismaDiff,
+    },
+    client: {
+        /**
+         * Runs Prisma generators included in the given Prisma schema (which usually includes the
+         * Prisma JS client). This will work even if the database doesn't exist yet.
+         *
+         * @example
+         *
+         * ```ts
+         * import {prisma} from '@augment-vir/node';
+         *
+         * prisma.client.generate('../../prisma/schema.prisma');
+         * ```
+         */
+        generate: generatePrismaClient,
+        /**
+         * Detects if the current generated Prisma JS Client was generated from the current Prisma
+         * schema.
+         */
+        isCurrent: isGeneratedPrismaClientCurrent,
+        /**
+         * Adds a collection of create data to a database through a `PrismaClient` instance. This is
+         * particularly useful for setting up mocks in a mock PrismaClient.
+         *
+         * @example
+         *
+         * ```ts
+         * import {addPrismaModelData} from '@augment-vir/common';
+         * import {PrismaClient} from '@prisma/client';
+         *
+         * await addPrismaModelData(new 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.
+         *             },
+         *         ],
+         *     },
+         * ]);
+         * ```
+         */
+        addData: addData,
+        /**
+         * Dump data from the current database through a `PrismaClient` instance.
+         *
+         * @see {@link PrismaDataDumpOptions}
+         */
+        dumpData: dumpData,
+        /** List all model names in the given Prisma client. */
+        listModelNames: getAllPrismaModelNames,
+    },
+};

package/src/augments/terminal/question.ts

@@ -0,0 +1,142 @@
+import {log} from '@augment-vir/common';
+import {convertDuration, type AnyDuration} from '@date-vir/duration';
+import {createInterface} from 'node:readline';
+
+/** Can't test requiring user input. */
+/* node:coverage disable */
+
+/**
+ * Options for {@link askQuestion}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type AskQuestionOptions = {
+    timeout: AnyDuration;
+    hideUserInput: boolean;
+};
+
+const defaultAskQuestionOptions: AskQuestionOptions = {
+    timeout: {seconds: 60},
+    hideUserInput: false,
+};
+
+/**
+ * Asks the user a question in their terminal and then waits for them to type something in response.
+ * The response is accepted once the user inputs a new line.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ *  - {@link askQuestionUntilConditionMet}: ask a question on loop until the user provides a valid response.
+ */
+export async function askQuestion(
+    questionToAsk: string,
+    {
+        hideUserInput = defaultAskQuestionOptions.hideUserInput,
+        timeout = defaultAskQuestionOptions.timeout,
+    }: Partial<AskQuestionOptions> = defaultAskQuestionOptions,
+): Promise<string> {
+    const cliInterface = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    if (hideUserInput) {
+        let promptWritten = false;
+        /** _writeToOutput is not in the types OR in the Node.js documentation but is a thing. */
+        (cliInterface as unknown as {_writeToOutput: (prompt: string) => void})._writeToOutput = (
+            prompt,
+        ) => {
+            if (!promptWritten) {
+                (
+                    cliInterface as unknown as {output: {write: (output: string) => void}}
+                ).output.write(prompt);
+                promptWritten = true;
+            }
+        };
+    }
+
+    // handle killing the process
+    cliInterface.on('SIGINT', () => {
+        cliInterface.close();
+        process.stdout.write('\n');
+        process.kill(process.pid, 'SIGINT');
+    });
+
+    return new Promise((resolve, reject) => {
+        const timeoutMs = convertDuration(timeout, {milliseconds: true}).milliseconds;
+
+        const timeoutId = timeoutMs
+            ? setTimeout(() => {
+                  cliInterface.close();
+                  reject(
+                      new Error(
+                          `Took too long to respond (over "${Math.floor(timeoutMs / 1000)}" seconds)`,
+                      ),
+                  );
+              }, timeoutMs)
+            : undefined;
+
+        process.stdout.write(questionToAsk + '\n');
+        cliInterface.question('', (response) => {
+            if (timeoutId != undefined) {
+                clearTimeout(timeoutId);
+            }
+            cliInterface.close();
+            resolve(response);
+        });
+    });
+}
+
+/**
+ * Options for {@link askQuestionUntilConditionMet}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type QuestionUntilConditionMetOptions = {
+    questionToAsk: string;
+    /** Callback to call with the user's response to verify if their response is valid. */
+    verifyResponseCallback: (response: string) => boolean | Promise<boolean>;
+    invalidInputMessage: string;
+    tryCountMax?: number;
+} & Partial<AskQuestionOptions>;
+
+/**
+ * Asks the user a question in their terminal and then waits for them to type something in response.
+ * The response is submitted once the user inputs a new line. If the response fails validation, the
+ * question is presented again.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ *  - {@link askQuestion}: ask a question and accept any response.
+ */
+export async function askQuestionUntilConditionMet({
+    questionToAsk,
+    verifyResponseCallback,
+    invalidInputMessage,
+    tryCountMax = 5,
+    ...options
+}: QuestionUntilConditionMetOptions): Promise<string> {
+    let wasConditionMet = false;
+    let retryCount = 0;
+    let response = '';
+    while (!wasConditionMet && retryCount <= tryCountMax) {
+        response = (await askQuestion(questionToAsk, options)).trim();
+        wasConditionMet = await verifyResponseCallback(response);
+        if (!wasConditionMet) {
+            log.error(invalidInputMessage);
+        }
+        retryCount++;
+    }
+    if (retryCount > tryCountMax) {
+        throw new Error(`Max input attempts (${tryCountMax}) exceeded.`);
+    }
+    return response;
+}

package/src/augments/terminal/relevant-args.ts

@@ -0,0 +1,81 @@
+import {basename} from 'node:path';
+
+/**
+ * Input for extractRelevantArgs.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type RelevantArgsInput = {
+    /** Raw arguments passed to the CLI. Typically this will simply be process.argv. */
+    rawArgs: ReadonlyArray<string>;
+    /**
+     * Executable bin name for your script. This should be the "bin" name in your package.json, or
+     * simply your package name if you have no custom bin name defined.
+     *
+     * See https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin for details on the bin
+     * field of package.json
+     */
+    binName: string | undefined;
+    /**
+     * The name or path of your script file that will be executed via the CLI. This should almost
+     * always simply be __filename in CJS or `import.meta.filename` in ESM.
+     */
+    fileName: string;
+    /**
+     * If set to true, this function with throw an error if the given file or bin name was not found
+     * in the given arguments list.
+     */
+    errorIfNotFound?: boolean | undefined;
+};
+
+/**
+ * Trims arguments list to remove all arguments that take place before the script's file name or
+ * executable bin name.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @example
+ *
+ * ```ts
+ * extractRelevantArgs({
+ *     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
+ * });
+ * // will output ['arg1', '--arg2']
+ * ```
+ *
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function extractRelevantArgs({
+    rawArgs,
+    binName,
+    fileName,
+    errorIfNotFound,
+}: Readonly<RelevantArgsInput>): string[] {
+    const baseFileName = basename(fileName);
+
+    if (!baseFileName) {
+        throw new Error(
+            `Given file name produced no base file name (with path.basename()): '${fileName}'`,
+        );
+    }
+
+    const lastIrrelevantArgIndex = rawArgs.findIndex((arg) => {
+        const baseArgName = basename(arg);
+        const matchesFileName = baseArgName === baseFileName;
+        const matchesBinName = binName ? baseArgName === binName : false;
+        return matchesFileName || matchesBinName;
+    });
+    if (lastIrrelevantArgIndex === -1) {
+        if (errorIfNotFound) {
+            throw new Error('Failed to find position of file or bin name in provided args list.');
+        } else {
+            return [...rawArgs];
+        }
+    } else {
+        return rawArgs.slice(lastIrrelevantArgIndex + 1);
+    }
+}

package/src/augments/terminal/run-cli-script.ts

@@ -0,0 +1,60 @@
+/* node:coverage disable */
+/** This file cannot be tested because it calls `process.exit`. */
+
+import {extname} from 'node:path';
+import {interpolationSafeWindowsPath} from '../path/os-path.js';
+import {extractRelevantArgs} from './relevant-args.js';
+import {runShellCommand} from './shell.js';
+
+/**
+ * A map of file extensions to their known runners for {@link runCliScript}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export const ExtensionToRunner: Record<string, string> = {
+    '.ts': 'tsx',
+    '.js': 'node',
+    '.sh': 'bash',
+};
+
+/**
+ * Runs a script path as if it had been run directly, as much as possible.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function runCliScript(
+    path: string,
+    /** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
+    cliScriptFilePath: string,
+    /**
+     * This should be the bin name of the package that is calling this function. Set to `undefined`
+     * if there isn't one.
+     */
+    binName: string | undefined,
+) {
+    const args = extractRelevantArgs({
+        rawArgs: process.argv,
+        binName,
+        fileName: cliScriptFilePath,
+    });
+
+    const extension = extname(path);
+
+    const runner = ExtensionToRunner[extension];
+
+    if (!runner) {
+        throw new Error("No runner configured for file extension '${extension}' in '${path}'");
+    }
+
+    const results = await runShellCommand(
+        interpolationSafeWindowsPath([runner, path, ...args].join(' ')),
+        {
+            hookUpToConsole: true,
+        },
+    );
+    process.exit(results.exitCode || 0);
+}