@augment-vir/node 30.0.1 → 30.0.2

package/dist/augments/os/operating-system.d.ts

@@ -19,3 +19,21 @@ export declare enum OperatingSystem {
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export declare const currentOperatingSystem: OperatingSystem;
+/**
+ * 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 declare function isOperatingSystem(operatingSystem: OperatingSystem): boolean;

package/dist/augments/os/operating-system.js

@@ -20,6 +20,26 @@ export var OperatingSystem;
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export const currentOperatingSystem = 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) {
+    return currentOperatingSystem === operatingSystem;
+}
 function getOperatingSystem() {
     /** We can't test all of these on a single system. */
     /* node:coverage ignore next 7 */

package/dist/augments/prisma.d.ts

@@ -1,6 +1,8 @@
+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';
+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';
 /**
@@ -84,6 +86,14 @@ export declare const prisma: {
         /**
          * 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;
         /**
@@ -91,5 +101,57 @@ export declare const 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,3 +1,4 @@
+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';
@@ -83,6 +84,14 @@ export const prisma = {
         /**
          * 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,
         /**
@@ -90,5 +99,57 @@ export const 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/docker/docker-image.js

@@ -21,7 +21,9 @@ export async function removeImageFromLocalRegistry(
 /** @example 'alpine:3.20.2' */
 imageName) {
     try {
-        await runShellCommand(`docker image rm '${imageName}'`, { rejectOnError: true });
+        await runShellCommand(`docker image rm '${imageName}'`, {
+            rejectOnError: true,
+        });
     }
     catch (caught) {
         const error = ensureError(caught);

package/dist/docker/run-docker-test.mock.d.ts

@@ -0,0 +1,2 @@
+import type { MaybePromise } from '@augment-vir/common';
+export declare function dockerTest(callback: () => MaybePromise<void>): () => MaybePromise<void>;

package/dist/docker/run-docker-test.mock.js

@@ -0,0 +1,16 @@
+import { isOperatingSystem, OperatingSystem } from '../augments/os/operating-system.js';
+export function dockerTest(callback) {
+    if (isOperatingSystem(OperatingSystem.Mac) && process.env.CI) {
+        /**
+         * We cannot test Docker on macOS GitHub Actions runners.
+         *
+         * @see
+         * - https://github.com/actions/runner-images/issues/8104
+         * - https://github.com/douglascamata/setup-docker-macos-action?tab=readme-ov-file#arm64-processors-m1-m2-m3-series-used-on-macos-14-images-are-unsupported
+         * - https://github.com/actions/runner-images/issues/2150
+         * - https://github.com/actions/runner/issues/1456
+         */
+        return () => { };
+    }
+    return callback;
+}

package/dist/prisma/disable-ci-env.mock.d.ts

@@ -0,0 +1,2 @@
+import { type MaybePromise } from '@augment-vir/common';
+export declare function testWithNonCiEnv(callback: () => MaybePromise<void>): () => Promise<void>;

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "30.0.1",
+    "version": "30.0.2",
     "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
     "keywords": [
         "augment",
@@ -37,27 +37,27 @@
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^30.0.1",
-        "@augment-vir/common": "^30.0.1",
+        "@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.1",
-        "@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"