@skmdev/prisma-fixtures 0.1.1

package/dist/cleanup-options.d.ts

@@ -0,0 +1,5 @@
+export type FixturePreservedTable = string;
+export type FixtureCleanupOptions = {
+    preserveTables?: FixturePreservedTable[];
+};
+export declare function normalizeCleanupOptions(value?: unknown): FixtureCleanupOptions;

package/dist/cleanup-options.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCleanupOptions = normalizeCleanupOptions;
+const fixture_document_1 = require("./fixture-document");
+function normalizeCleanupOptions(value = {}) {
+    if (!(0, fixture_document_1.isFixtureRecord)(value) ||
+        Object.keys(value).some((key) => key !== 'preserveTables')) {
+        throw new Error('Invalid fixture cleanup options');
+    }
+    const preserveTables = value.preserveTables;
+    if (preserveTables === undefined)
+        return {};
+    if (!Array.isArray(preserveTables) ||
+        preserveTables.some((entry) => typeof entry !== 'string' || !/^[^.]+\.[^.]+$/.test(entry)) ||
+        new Set(preserveTables).size !== preserveTables.length) {
+        throw new Error('Invalid fixture cleanup options');
+    }
+    return { preserveTables };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const node_util_1 = require("node:util");
+const ajv_1 = __importDefault(require("ajv"));
+const fixture_document_1 = require("./fixture-document");
+const fixture_error_1 = require("./fixture-error");
+const fixture_reference_1 = require("./fixture-reference");
+const load_options_1 = require("./load-options");
+const prisma_config_1 = require("./prisma-config");
+const fixture_config_1 = require("./fixture-config");
+const index_1 = require("./index");
+const help = `Usage: prisma-fixtures [path...] [--client <module>] [options]
+       prisma-fixtures init [fixtures-directory]
+
+Load YAML/JSON fixtures using your Prisma client, in one transaction.
+Defaults are read from .prisma-fixtures (JSON) and adjacent Prisma config.
+A string client exports a client/factory; a config client object names generated Prisma output.
+init creates a minimal config without overwriting existing config.
+
+  --config <file>        Read a JSON config instead of .prisma-fixtures
+  --client <module>      Path to your client module (.js, .cjs, .mjs, .ts)
+  --databaseUrl <url>    Override Prisma config URL or pass to a client factory
+  --require <module>    Preload a module; repeat for additional modules
+  --timeout <ms>        Transaction timeout (default: 60000)
+  --seed <integer>      Reproduce generated values and random references
+  --refDate <timestamp> Fix Faker relative dates (canonical UTC timestamp)
+  --clean               Clear database data, preserving schema and migrations
+  --reset               Clear database data, then load fixtures
+  --list                List fixture names/entities without executing code
+  --lint                Check fixture syntax/structure without executing code
+  --schema <file>       Also validate --lint against a generated JSON Schema
+  --debug, -d           Include error type/code, never record data or URLs
+  --no-color            Accepted for compatibility; output is always plain
+  --version, -v         Print the package version
+  --help, -h            Show this help
+`;
+let stage = 'arguments';
+let debug = false;
+async function main() {
+    const { values, positionals } = parseCliArguments();
+    debug = values.debug ?? false;
+    const lint = values.lint ?? false;
+    if (values.help)
+        return void process.stdout.write(help);
+    if (values.version) {
+        const { version } = require('../package.json');
+        return void console.log(version);
+    }
+    if (positionals[0] === 'init') {
+        if (positionals.length > 2 || Object.keys(values).length !== 0) {
+            throw new Error('init accepts only an optional fixtures directory');
+        }
+        stage = 'initializing config';
+        return initializeConfig(positionals[1]);
+    }
+    stage = 'reading config';
+    const config = (0, fixture_config_1.readFixtureConfig)(values.config);
+    const targets = positionals.length ? positionals : (config.fixtures ?? []);
+    stage = 'arguments';
+    if ((!values.clean && targets.length === 0) ||
+        [values.list, lint, values.clean, values.reset].filter(Boolean).length > 1) {
+        process.stderr.write(help);
+        process.exitCode = 1;
+        return;
+    }
+    const timeout = Number(values.timeout ?? config.timeout ?? 60000);
+    if (!Number.isSafeInteger(timeout) || timeout <= 0) {
+        throw new Error('Invalid transaction timeout');
+    }
+    const cliSeed = values.seed;
+    if (cliSeed !== undefined && !/^\d+$/.test(cliSeed)) {
+        throw new Error('Invalid fixture load options');
+    }
+    const loadOptions = (0, load_options_1.normalizeLoadOptions)({
+        seed: cliSeed === undefined ? config.seed : Number(cliSeed),
+        refDate: values.refDate ?? config.refDate,
+    });
+    const schemaFile = values.schema ?? config.schema;
+    const validate = lint && schemaFile !== undefined
+        ? readSchemaValidator(schemaFile)
+        : undefined;
+    stage = 'reading fixtures';
+    const definitions = values.clean ? [] : (0, fixture_document_1.readFixturePaths)(targets, validate);
+    if (lint) {
+        if (definitions.length > fixture_document_1.MAX_FIXTURE_DEFINITIONS) {
+            throw new fixture_document_1.FixtureDocumentError('Too many fixture definitions');
+        }
+        const { unresolved } = (0, fixture_reference_1.lintFixtureReferences)(definitions);
+        console.log(`Linted ${definitions.length} fixtures (syntax and structure${schemaFile === undefined ? '' : ', model schema'}, static references; ${unresolved} dynamic values or multi-candidate references unresolved).`);
+        return;
+    }
+    if (values.list) {
+        console.log(JSON.stringify(definitions.map(({ name, entity }) => ({ name, entity })), null, 2));
+        return;
+    }
+    const { client, guard, preserveTables } = await loadClient(config, values);
+    let count;
+    let operationError;
+    try {
+        if (typeof client.$transaction !== 'function') {
+            throw new Error('The client must implement $transaction');
+        }
+        stage = values.clean
+            ? 'cleaning fixtures'
+            : values.reset
+                ? 'resetting fixtures'
+                : 'loading fixtures';
+        const action = async (transaction) => {
+            if (values.clean) {
+                await (0, index_1.cleanFixtures)(transaction, {
+                    preserveTables,
+                });
+                return;
+            }
+            return values.reset
+                ? (0, index_1.resetFixtures)(transaction, definitions, {
+                    preserveTables,
+                    ...loadOptions,
+                })
+                : (0, index_1.loadFixtures)(transaction, definitions, loadOptions);
+        };
+        const records = guard
+            ? await guard.fixtureTransaction(client, action, timeout)
+            : await client.$transaction(action, { timeout });
+        count = records === undefined ? 0 : Object.keys(records).length;
+    }
+    catch (error) {
+        operationError = error;
+        throw error;
+    }
+    finally {
+        try {
+            if (operationError === undefined)
+                stage = 'disconnecting the client';
+            await client.$disconnect();
+        }
+        catch (error) {
+            if (operationError === undefined)
+                throw error;
+        }
+    }
+    console.log(values.clean
+        ? 'Cleaned database data.'
+        : `${values.reset ? 'Reset and loaded' : 'Loaded'} ${count} fixtures.`);
+}
+function parseCliArguments() {
+    return (0, node_util_1.parseArgs)({
+        allowPositionals: true,
+        options: {
+            config: { type: 'string' },
+            client: { type: 'string' },
+            databaseUrl: { type: 'string' },
+            require: { type: 'string', multiple: true },
+            timeout: { type: 'string' },
+            seed: { type: 'string' },
+            refDate: { type: 'string' },
+            clean: { type: 'boolean' },
+            reset: { type: 'boolean' },
+            list: { type: 'boolean' },
+            lint: { type: 'boolean' },
+            schema: { type: 'string' },
+            debug: { type: 'boolean', short: 'd' },
+            'no-color': { type: 'boolean' },
+            version: { type: 'boolean', short: 'v' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+}
+function initializeConfig(directory) {
+    if (node_fs_1.default.existsSync('.prisma-fixtures')) {
+        console.error('.prisma-fixtures already exists; no changes made.');
+        process.exitCode = 1;
+        return;
+    }
+    const fixtures = directory ??
+        (node_fs_1.default.existsSync('prisma/fixtures') ? './prisma/fixtures' : './fixtures');
+    if (directory) {
+        if (!node_fs_1.default.existsSync(fixtures) || !node_fs_1.default.statSync(fixtures).isDirectory()) {
+            console.error('Fixture directory does not exist; no changes made.');
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else {
+        node_fs_1.default.mkdirSync(fixtures, { recursive: true });
+    }
+    node_fs_1.default.writeFileSync('.prisma-fixtures', `${JSON.stringify({ fixtures: [fixtures] }, null, 2)}\n`, { flag: 'wx' });
+    console.log(`Created .prisma-fixtures using ${fixtures}.`);
+}
+function readSchemaValidator(schemaFile) {
+    stage = 'reading schema';
+    const raw = node_fs_1.default.readFileSync(node_path_1.default.resolve(schemaFile), 'utf8');
+    let validate;
+    try {
+        validate = new ajv_1.default({ strict: false, validateFormats: false }).compile(JSON.parse(raw));
+    }
+    catch {
+        throw new fixture_document_1.FixtureDocumentError('Invalid fixture JSON Schema');
+    }
+    return (document, file) => {
+        if (validate(document))
+            return;
+        const error = validate.errors?.[0];
+        throw new fixture_document_1.FixtureDocumentError(`Fixture document ${JSON.stringify(node_path_1.default.basename(file))}: ${JSON.stringify(error?.instancePath || '/')} ${error?.message ?? 'does not match the schema'}`);
+    };
+}
+async function loadClient(config, values) {
+    stage = 'loading the client';
+    let clientConfig = values.client ? node_path_1.default.resolve(values.client) : config.client;
+    const requireFromCwd = (0, node_module_1.createRequire)(node_path_1.default.resolve('package.json'));
+    for (const preload of values.require ?? [])
+        requireFromCwd(preload);
+    let prismaDefaults;
+    if (!clientConfig) {
+        stage = 'loading Prisma config';
+        prismaDefaults = await (0, prisma_config_1.loadPrismaDefaults)(node_path_1.default.dirname(node_path_1.default.resolve(values.config ?? '.prisma-fixtures')), requireFromCwd, values.databaseUrl);
+        const clientExtension = node_path_1.default.extname(prismaDefaults.module);
+        if ((clientExtension === '.ts' || clientExtension === '.cts') &&
+            !require.extensions[clientExtension]) {
+            requireFromCwd('ts-node/register');
+        }
+        clientConfig = { module: prismaDefaults.module, adapter: 'pg' };
+        stage = 'loading the client';
+    }
+    const preserveTables = [
+        ...new Set([
+            ...(config.preserveTables ?? []),
+            ...(prismaDefaults?.preserveTables ?? []),
+        ]),
+    ];
+    let candidate;
+    let guard;
+    if (typeof clientConfig === 'string') {
+        const imported = await import((0, node_url_1.pathToFileURL)(clientConfig).href);
+        let exported = imported.default;
+        if (exported && typeof exported === 'object' && 'default' in exported) {
+            exported = exported.default;
+        }
+        if (values.databaseUrl !== undefined && typeof exported !== 'function') {
+            throw new Error('--databaseUrl requires a client factory');
+        }
+        candidate =
+            typeof exported === 'function'
+                ? await exported({ databaseUrl: values.databaseUrl })
+                : exported;
+    }
+    else {
+        if (clientConfig.guard) {
+            const imported = requireFromCwd(clientConfig.guard);
+            if (!(0, fixture_document_1.isFixtureRecord)(imported) ||
+                typeof imported.fixtureDatabaseUrl !== 'function' ||
+                typeof imported.fixtureTransaction !== 'function') {
+                throw new Error('Invalid fixture guard module');
+            }
+            guard = imported;
+        }
+        const environment = {
+            ...process.env,
+            ...(values.databaseUrl === undefined
+                ? {}
+                : { DATABASE_URL: values.databaseUrl }),
+        };
+        const databaseUrl = guard
+            ? guard.fixtureDatabaseUrl(environment)
+            : (values.databaseUrl ??
+                prismaDefaults?.databaseUrl ??
+                environment.DATABASE_URL);
+        if (typeof databaseUrl !== 'string' || !databaseUrl.trim()) {
+            throw new Error('DATABASE_URL is required');
+        }
+        const generated = await importGeneratedClient(clientConfig.module, requireFromCwd);
+        candidate = createGeneratedClient(generated, requireFromCwd, databaseUrl);
+    }
+    if (!candidate ||
+        typeof candidate !== 'object' ||
+        !('$disconnect' in candidate) ||
+        typeof candidate.$disconnect !== 'function') {
+        throw new Error('The client must implement $disconnect');
+    }
+    return { client: candidate, guard, preserveTables };
+}
+function createGeneratedClient(generated, requireFromCwd, databaseUrl) {
+    const clientExports = (0, fixture_document_1.isFixtureRecord)(generated) ? generated : undefined;
+    const defaultExport = (0, fixture_document_1.isFixtureRecord)(clientExports?.default)
+        ? clientExports.default
+        : undefined;
+    const PrismaClient = clientExports?.PrismaClient ?? defaultExport?.PrismaClient;
+    const adapter = requireFromCwd('@prisma/adapter-pg');
+    if (typeof PrismaClient !== 'function' ||
+        typeof adapter.PrismaPg !== 'function') {
+        throw new Error('Invalid generated Prisma client or pg adapter');
+    }
+    return new PrismaClient({
+        adapter: new adapter.PrismaPg({ connectionString: databaseUrl }),
+    });
+}
+async function importGeneratedClient(modulePath, requireFromCwd) {
+    try {
+        return requireFromCwd(modulePath);
+    }
+    catch (error) {
+        if (error === null ||
+            typeof error !== 'object' ||
+            !('code' in error) ||
+            !['ERR_REQUIRE_ESM', 'ERR_REQUIRE_ASYNC_MODULE'].includes(String(error.code))) {
+            throw error;
+        }
+        return import((0, node_url_1.pathToFileURL)(modulePath).href);
+    }
+}
+main().catch((error) => {
+    if ((0, fixture_error_1.isTrustedFixtureError)(error)) {
+        console.error(formatFixtureError(error));
+        process.exitCode = 1;
+        return;
+    }
+    // Prisma and user hooks can put database URLs or record data in messages/stacks.
+    const details = debug && error instanceof Error
+        ? ` (${error.name.replace(/[^A-Za-z0-9_]/g, '').slice(0, 60)})`
+        : '';
+    console.error(`Fixture command failed during ${stage}${details}.`);
+    process.exitCode = 1;
+});
+function formatFixtureError(error) {
+    const location = [error.file, error.fixtureName, error.path]
+        .filter((value) => value !== undefined)
+        .map((value) => JSON.stringify(value))
+        .join(' ');
+    const output = `Fixture command failed during ${error.stage} [${error.code}]: ${location}${location ? ' ' : ''}${error.message}.`;
+    const suffix = '… [truncated]';
+    return output.length <= 4096
+        ? output
+        : `${output.slice(0, 4096 - suffix.length)}${suffix}`;
+}

package/dist/fixture-config.d.ts

@@ -0,0 +1,14 @@
+import { type FixtureCleanupOptions } from './cleanup-options';
+import { type FixtureLoadOptions } from './load-options';
+export type ConfiguredPrismaClient = {
+    module: string;
+    adapter: 'pg';
+    guard?: string;
+};
+export type FixtureConfig = FixtureCleanupOptions & FixtureLoadOptions & {
+    fixtures?: string[];
+    client?: string | ConfiguredPrismaClient;
+    timeout?: number;
+    schema?: string;
+};
+export declare function readFixtureConfig(file?: string): FixtureConfig;

package/dist/fixture-config.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFixtureConfig = readFixtureConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const cleanup_options_1 = require("./cleanup-options");
+const fixture_document_1 = require("./fixture-document");
+const load_options_1 = require("./load-options");
+function readFixtureConfig(file) {
+    const configFile = node_path_1.default.resolve(file ?? '.prisma-fixtures');
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(configFile, 'utf8');
+    }
+    catch (error) {
+        if (file === undefined &&
+            error instanceof Error &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return {};
+        }
+        throw error;
+    }
+    const config = JSON.parse(raw);
+    if (!(0, fixture_document_1.isFixtureRecord)(config) ||
+        Object.keys(config).some((key) => ![
+            'fixtures',
+            'client',
+            'timeout',
+            'schema',
+            'preserveTables',
+            'seed',
+            'refDate',
+        ].includes(key))) {
+        throw new Error('Invalid fixture CLI config');
+    }
+    const { fixtures, client, timeout, schema, preserveTables, seed, refDate } = config;
+    if ((fixtures !== undefined &&
+        (!Array.isArray(fixtures) ||
+            !fixtures.length ||
+            !fixtures.every(isPath))) ||
+        (client !== undefined && !isClientConfig(client)) ||
+        (schema !== undefined && !isPath(schema)) ||
+        (timeout !== undefined &&
+            (typeof timeout !== 'number' ||
+                !Number.isSafeInteger(timeout) ||
+                timeout <= 0))) {
+        throw new Error('Invalid fixture CLI config');
+    }
+    let cleanup;
+    let load;
+    try {
+        cleanup = (0, cleanup_options_1.normalizeCleanupOptions)({ preserveTables });
+        load = (0, load_options_1.normalizeLoadOptions)({ seed, refDate });
+    }
+    catch {
+        throw new Error('Invalid fixture CLI config');
+    }
+    const directory = node_path_1.default.dirname(configFile);
+    return {
+        fixtures: fixtures?.map((target) => node_path_1.default.resolve(directory, target)),
+        client: resolveClientPaths(client, directory),
+        timeout,
+        schema: schema === undefined ? undefined : node_path_1.default.resolve(directory, schema),
+        ...cleanup,
+        ...load,
+    };
+}
+function isPath(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isClientConfig(value) {
+    return (isPath(value) ||
+        ((0, fixture_document_1.isFixtureRecord)(value) &&
+            Object.keys(value).every((key) => ['module', 'adapter', 'guard'].includes(key)) &&
+            isPath(value.module) &&
+            value.adapter === 'pg' &&
+            (value.guard === undefined || isPath(value.guard))));
+}
+function resolveClientPaths(client, directory) {
+    if (client === undefined)
+        return undefined;
+    if (typeof client === 'string')
+        return node_path_1.default.resolve(directory, client);
+    return {
+        module: node_path_1.default.resolve(directory, client.module),
+        adapter: 'pg',
+        ...(client.guard === undefined
+            ? {}
+            : { guard: node_path_1.default.resolve(directory, client.guard) }),
+    };
+}

package/dist/fixture-document.d.ts

@@ -0,0 +1,23 @@
+import { FixtureError, type FixtureErrorContext } from './fixture-error';
+export declare class FixtureDocumentError extends FixtureError {
+    constructor(message: string, context?: Partial<FixtureErrorContext>, cause?: unknown);
+}
+export type FixtureDefinition = {
+    name: string;
+    entity: string;
+    data: Record<string, unknown>;
+    parameters: Record<string, unknown>;
+    processor?: string;
+    locale?: string;
+    connectedFields?: string[];
+    deferredFields?: string[];
+};
+export declare function fixtureErrorContext(fixture: FixtureDefinition | undefined, stage: string, path?: string): FixtureErrorContext;
+export declare function inheritFixtureSource(source: FixtureDefinition, target: FixtureDefinition): void;
+export declare const MAX_FIXTURE_DEFINITIONS = 2000;
+export declare const DANGEROUS_KEYS: Set<string>;
+export declare function readFixturePaths(targets: string[], validateDocument?: (value: unknown, file: string) => void): FixtureDefinition[];
+export declare function readFixtureDocuments(targetPath: string, validateDocument?: (value: unknown, file: string) => void): FixtureDefinition[];
+export declare function assertFixtureDefinition(value: unknown): asserts value is FixtureDefinition;
+export declare function isFixtureRecord(value: unknown): value is Record<string, unknown>;
+export declare function assertSafeFixtureValue(value: unknown): void;