@augment-vir/node 30.0.0 → 30.0.2

package/dist/prisma/disable-ci-env.mock.js

@@ -0,0 +1,81 @@
+// cspell:disable
+import { arrayToObject } 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) {
+    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/dist/prisma/model-data.d.ts

@@ -0,0 +1,73 @@
+import { BasePrismaClient, PrismaAllModelsCreate, type PartialWithUndefined, type PrismaAllBasicModels, type PrismaModelName } from '@augment-vir/common';
+/**
+ * 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 declare function addData<const PrismaClient extends BasePrismaClient>(prismaClient: Readonly<PrismaClient>, data: PrismaAddDataData<PrismaClient>): Promise<void>;
+export declare function getAllPrismaModelNames<const PrismaClient extends BasePrismaClient>(prismaClient: PrismaClient): 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[];
+};
+export declare function dumpData<const PrismaClient extends BasePrismaClient>(prismaClient: PrismaClient, options?: Readonly<PartialWithUndefined<PrismaDataDumpOptions>>): Promise<PrismaAllBasicModels<PrismaClient>>;

package/dist/prisma/model-data.js

@@ -0,0 +1,70 @@
+import { assert, check } from '@augment-vir/assert';
+import { arrayToObject, awaitedForEach, ensureErrorAndPrependMessage, filterMap, getObjectTypedEntries, getObjectTypedValues, mergeDefinedProperties, omitObjectKeys, prismaModelCreateExclude, prismaModelCreateOmitId, } from '@augment-vir/common';
+export async function addData(prismaClient, data) {
+    const dataArray = (check.isArray(data) ? data : [data]);
+    await awaitedForEach(dataArray, async (dataEntry) => {
+        await addModelDataObject(prismaClient, dataEntry);
+    });
+}
+async function addModelDataObject(prismaClient, data) {
+    /** 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 = Array.isArray(mockData)
+            ? mockData
+            : getObjectTypedValues(mockData);
+        const modelApi = 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(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`);
+        }
+    });
+}
+export function getAllPrismaModelNames(prismaClient) {
+    return Object.keys(prismaClient)
+        .filter((key) => !key.startsWith('$') && !key.startsWith('_'))
+        .sort();
+}
+const defaultPrismaDumpDataOptions = {
+    limit: 100,
+    omitFields: [],
+};
+export async function dumpData(prismaClient, options = {}) {
+    const modelNames = getAllPrismaModelNames(prismaClient);
+    const finalOptions = mergeDefinedProperties(defaultPrismaDumpDataOptions, options);
+    const data = await arrayToObject(modelNames, async (modelName) => {
+        const entries = 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,
+        };
+    });
+    return data;
+}

package/dist/prisma/prisma-client.d.ts

@@ -1,7 +1,3 @@
-/**
- * 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.
- */
 export declare function generatePrismaClient(schemaFilePath: string, env?: Record<string, string>): Promise<void>;
 export declare function isGeneratedPrismaClientCurrent({ jsClientOutputDir, schemaFilePath, }: {
     schemaFilePath: string;

package/dist/prisma/prisma-client.js

@@ -3,10 +3,6 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { runPrismaCommand } from './run-prisma-command.js';
-/**
- * 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.
- */
 export async function generatePrismaClient(schemaFilePath, env = {}) {
     await runPrismaCommand({ command: 'generate' }, schemaFilePath, env);
 }

package/dist/prisma/prisma-errors.d.ts

@@ -1,11 +1,36 @@
+/**
+ * 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 declare class PrismaSchemaError extends Error {
     readonly name = "PrismaSchemaError";
     constructor(message: string);
 }
+/**
+ * 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 declare class PrismaMigrationNeededError extends Error {
     readonly name = "PrismaMigrationNeededError";
     constructor(schemaFilePath: string);
 }
+/**
+ * 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 declare class PrismaResetNeededError extends Error {
     readonly name = "PrismaResetNeededError";
     constructor(schemaFilePath: string);

package/dist/prisma/prisma-errors.js

@@ -1,15 +1,40 @@
+/**
+ * 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 {
     name = 'PrismaSchemaError';
     constructor(message) {
         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 {
     name = 'PrismaMigrationNeededError';
     constructor(schemaFilePath) {
         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 {
     name = 'PrismaResetNeededError';
     constructor(schemaFilePath) {

package/dist/prisma/prisma-migrations.d.ts

@@ -1,17 +1,23 @@
+/**
+ * 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 declare function applyPrismaMigrationsToProd(schemaFilePath: string, env?: Record<string, string>): Promise<void>;
-/**
- * @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.
- */
 export declare function applyPrismaMigrationsToDev(schemaFilePath: string, env?: Record<string, string>): Promise<void>;
 export declare function getMigrationStatus(schemaFilePath: string, env?: Record<string, string>): Promise<PrismaMigrationStatus>;
 export declare function createPrismaMigration({ migrationName, createOnly, }: {
     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>): Promise<void>;

package/dist/prisma/prisma-migrations.js

@@ -1,7 +1,7 @@
 import { check } from '@augment-vir/assert';
 import { log, safeMatch, toEnsuredNumber } from '@augment-vir/common';
 import terminate from 'terminate';
-import { runShellCommand } from '../augments/shell.js';
+import { runShellCommand } from '../augments/terminal/shell.js';
 import { PrismaMigrationNeededError, PrismaResetNeededError } from './prisma-errors.js';
 import { runPrismaCommand, verifyOutput } from './run-prisma-command.js';
 export async function applyPrismaMigrationsToProd(schemaFilePath, env = {}) {
@@ -12,12 +12,6 @@ var DbChangeRequired;
     DbChangeRequired["MigrationNeeded"] = "migration-needed";
     DbChangeRequired["ResetNeeded"] = "reset-needed";
 })(DbChangeRequired || (DbChangeRequired = {}));
-/**
- * @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.
- */
 export async function applyPrismaMigrationsToDev(schemaFilePath, env = {}) {
     const command = [
         'prisma',

package/dist/prisma/run-prisma-command.d.ts

@@ -1,4 +1,4 @@
-import { type ShellOutput } from '../augments/shell.js';
+import { type ShellOutput } from '../augments/terminal/shell.js';
 export declare function runPrismaCommand({ command, ignoreExitCode, }: {
     command: string;
     ignoreExitCode?: boolean | undefined;

package/dist/prisma/run-prisma-command.js

@@ -1,5 +1,5 @@
 import { log } from '@augment-vir/common';
-import { runShellCommand } from '../augments/shell.js';
+import { runShellCommand } from '../augments/terminal/shell.js';
 import { PrismaSchemaError } from './prisma-errors.js';
 const prismaCommandsThatSupportNoHints = [
     'generate',

package/package.json

@@ -1,6 +1,18 @@
 {
     "name": "@augment-vir/node",
-    "version": "30.0.0",
+    "version": "30.0.2",
+    "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
+    "keywords": [
+        "augment",
+        "helper",
+        "util",
+        "node",
+        "browser",
+        "backend",
+        "frontend",
+        "vir",
+        "augment-vir"
+    ],
     "homepage": "https://github.com/electrovir/augment-vir",
     "bugs": {
         "url": "https://github.com/electrovir/augment-vir/issues"
@@ -20,34 +32,32 @@
     "types": "dist/index.d.ts",
     "scripts": {
         "compile": "virmator compile",
-        "docs": "virmator docs",
         "test": "virmator --no-deps test node --test-concurrency 1",
         "test:coverage": "virmator test node coverage --test-concurrency 1",
-        "test:docs": "virmator docs check",
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^30.0.0",
-        "@augment-vir/common": "^30.0.0",
+        "@augment-vir/assert": "^30.0.2",
+        "@augment-vir/common": "^30.0.2",
         "@date-vir/duration": "^6.0.0",
         "ansi-styles": "^6.2.1",
         "terminate": "^2.8.0",
-        "type-fest": "^4.25.0",
+        "type-fest": "^4.26.1",
         "typed-event-target": "^3.4.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^30.0.0",
-        "@prisma/client": "^5.19.0",
-        "@types/node": "^22.5.0",
+        "@augment-vir/test": "^30.0.2",
+        "@prisma/client": "^5.19.1",
+        "@types/node": "^22.5.4",
         "@web/dev-server-esbuild": "^1.0.2",
-        "@web/test-runner": "^0.18.3",
+        "@web/test-runner": "^0.19.0",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.0",
-        "@web/test-runner-visual-regression": "^0.9.0",
+        "@web/test-runner-visual-regression": "^0.10.0",
         "c8": "^10.1.2",
-        "concurrently": "^8.2.2",
+        "concurrently": "^9.0.0",
         "istanbul-smart-text-reporter": "^1.1.4",
-        "prisma": "^5.19.0"
+        "prisma": "^5.19.1"
     },
     "engines": {
         "node": ">=22"

package/dist/augments/console/question.d.ts

@@ -1,14 +0,0 @@
-import { type AnyDuration } from '@date-vir/duration';
-/** Can't test requiring user input. */
-export type AskQuestionOptions = {
-    timeout: AnyDuration;
-    hideUserInput: boolean;
-};
-export declare function askQuestion(questionToAsk: string, { hideUserInput, timeout, }?: Partial<AskQuestionOptions>): Promise<string>;
-export type QuestionUntilConditionMetConfig = {
-    questionToAsk: string;
-    conditionCallback: (response: string) => boolean | Promise<boolean>;
-    invalidInputMessage: string;
-    tryCountMax?: number;
-} & Partial<AskQuestionOptions>;
-export declare function askQuestionUntilConditionMet({ questionToAsk, conditionCallback, invalidInputMessage, tryCountMax, ...options }: QuestionUntilConditionMetConfig): Promise<string>;

package/dist/augments/download.d.ts

@@ -1,4 +0,0 @@
-export declare function downloadFile({ url, writePath }: {
-    url: string;
-    writePath: string;
-}): Promise<void>;