@augment-vir/node 30.0.0 → 30.0.2

package/dist/augments/path/ancestor.js

@@ -1,6 +1,15 @@
 import { check } from '@augment-vir/assert';
 import { dirname, join } from 'node:path';
 import { systemRootPath } from './root.js';
+/**
+ * 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, callback) {
     if (currentPath === systemRootPath) {
         return undefined;
@@ -24,6 +33,25 @@ export function findAncestor(currentPath, callback) {
         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, childNames) {
     return childNames.map((childName) => join(parentDirPath, childName));
 }

package/dist/augments/path/os-path.d.ts

@@ -1,9 +1,25 @@
-/** Convert a given path to a windows path if the current system doesn't use `/`. */
+/**
+ * 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 declare function replaceWithWindowsPathIfNeeded(input: string): string;
-/** Convert a Windows path to a posix path. */
+/**
+ * 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 declare function toPosixPath(maybeWindowsPath: string): string;
 /**
- * Use this to interpolate paths into bash commands. If the given path is not a window path, the
+ * 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 declare function interpolationSafeWindowsPath(input: string): string;

package/dist/augments/path/os-path.js

@@ -1,5 +1,11 @@
 import { sep } from 'node:path';
-/** Convert a given path to a windows path if the current system doesn't use `/`. */
+/**
+ * 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) {
     if (sep === '/') {
         return input;
@@ -10,7 +16,13 @@ export function replaceWithWindowsPathIfNeeded(input) {
         return input.replace(/\//g, sep);
     }
 }
-/** Convert a Windows path to a posix path. */
+/**
+ * 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) {
     return maybeWindowsPath
         .replace(/^(.+?):\\+/, (match, captureGroup) => {
@@ -19,8 +31,12 @@ export function toPosixPath(maybeWindowsPath) {
         .replace(/\\+/g, '/');
 }
 /**
- * Use this to interpolate paths into bash commands. If the given path is not a window path, the
+ * 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) {
     return input.replace(/\\/g, '\\\\\\\\');

package/dist/augments/path/root.d.ts

@@ -1 +1,8 @@
+/**
+ * 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 declare const systemRootPath: string;

package/dist/augments/path/root.js

@@ -2,4 +2,11 @@ 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/dist/augments/prisma.d.ts

@@ -1,21 +1,157 @@
+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';
-/** Centralized Prisma API from `@augment-vir/node`. */
+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 declare const prisma: {
     migration: {
+        /**
+         * Get current migration status.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-status
+         */
         status: typeof getMigrationStatus;
+        /**
+         * Creates a new migration.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-dev
+         */
         create: typeof createPrismaMigration;
+        /**
+         * Apply all migrations. Meant for a production environment.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-deploy
+         */
         applyProd: typeof 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: typeof 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: typeof 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: typeof 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: typeof 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: typeof generatePrismaClient;
+        /**
+         * Detects if the current generated Prisma JS Client was generated from the current Prisma
+         * schema.
+         */
         isCurrent: typeof 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: typeof addData;
+        /**
+         * Dump data from the current database through a `PrismaClient` instance.
+         *
+         * @see {@link PrismaDataDumpOptions}
+         */
+        dumpData: typeof dumpData;
+        /** List all model names in the given Prisma client. */
+        listModelNames: typeof getAllPrismaModelNames;
     };
 };

package/dist/augments/prisma.js

@@ -1,21 +1,155 @@
+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';
-/** Centralized Prisma API from `@augment-vir/node`. */
+export * from '../prisma/prisma-errors.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/dist/augments/terminal/question.d.ts

@@ -0,0 +1,50 @@
+import { type AnyDuration } from '@date-vir/duration';
+/** Can't test requiring user input. */
+/**
+ * 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;
+};
+/**
+ * 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 declare function askQuestion(questionToAsk: string, { hideUserInput, timeout, }?: Partial<AskQuestionOptions>): Promise<string>;
+/**
+ * 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 declare function askQuestionUntilConditionMet({ questionToAsk, verifyResponseCallback, invalidInputMessage, tryCountMax, ...options }: QuestionUntilConditionMetOptions): Promise<string>;

package/dist/augments/{console → terminal}/question.js

@@ -5,6 +5,16 @@ const defaultAskQuestionOptions = {
     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, { hideUserInput = defaultAskQuestionOptions.hideUserInput, timeout = defaultAskQuestionOptions.timeout, } = defaultAskQuestionOptions) {
     const cliInterface = createInterface({
         input: process.stdin,
@@ -44,13 +54,24 @@ export async function askQuestion(questionToAsk, { hideUserInput = defaultAskQue
         });
     });
 }
-export async function askQuestionUntilConditionMet({ questionToAsk, conditionCallback, invalidInputMessage, tryCountMax = 5, ...options }) {
+/**
+ * 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 }) {
     let wasConditionMet = false;
     let retryCount = 0;
     let response = '';
     while (!wasConditionMet && retryCount <= tryCountMax) {
         response = (await askQuestion(questionToAsk, options)).trim();
-        wasConditionMet = await conditionCallback(response);
+        wasConditionMet = await verifyResponseCallback(response);
         if (!wasConditionMet) {
             log.error(invalidInputMessage);
         }