@augment-vir/node 31.0.0 → 31.1.0

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

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