@skmdev/prisma-fixtures 0.1.1

package/dist/fixture-document.js

@@ -0,0 +1,349 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DANGEROUS_KEYS = exports.MAX_FIXTURE_DEFINITIONS = exports.FixtureDocumentError = void 0;
+exports.fixtureErrorContext = fixtureErrorContext;
+exports.inheritFixtureSource = inheritFixtureSource;
+exports.readFixturePaths = readFixturePaths;
+exports.readFixtureDocuments = readFixtureDocuments;
+exports.assertFixtureDefinition = assertFixtureDefinition;
+exports.isFixtureRecord = isFixtureRecord;
+exports.assertSafeFixtureValue = assertSafeFixtureValue;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const yaml_1 = require("yaml");
+const fixture_error_1 = require("./fixture-error");
+// Only messages constructed here are safe to display as lint diagnostics.
+class FixtureDocumentError extends fixture_error_1.FixtureError {
+    constructor(message, context = {}, cause) {
+        super('FIXTURE_DOCUMENT_INVALID', message, { stage: 'reading fixtures', ...context }, cause);
+        this.name = 'FixtureDocumentError';
+        (0, fixture_error_1.markFixtureErrorTrusted)(this);
+    }
+}
+exports.FixtureDocumentError = FixtureDocumentError;
+const fixtureSources = new WeakMap();
+function fixtureErrorContext(fixture, stage, path) {
+    if (!fixture)
+        return { stage, path };
+    return {
+        stage,
+        file: fixtureSources.get(fixture)?.file,
+        fixtureName: fixture.name,
+        entity: fixture.entity,
+        ...(path === undefined ? {} : { path }),
+    };
+}
+function inheritFixtureSource(source, target) {
+    const provenance = fixtureSources.get(source);
+    if (provenance)
+        fixtureSources.set(target, provenance);
+}
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_FILES = 100;
+exports.MAX_FIXTURE_DEFINITIONS = 2000;
+const MAX_DEPTH = 32;
+const MAX_NODES = 50_000;
+exports.DANGEROUS_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+const NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,127}$/;
+const FIELD_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+const RANGE_PATTERN = /^([A-Za-z][A-Za-z0-9_-]*)\{(\d+)\.\.(\d+)\}$/;
+const CURRENT_PATTERN = /\(\$current(?:([+\-*/])(\d+))?\)/g;
+function readFixturePaths(targets, validateDocument) {
+    const definitions = targets.flatMap((target) => readFixtureDocuments(node_path_1.default.resolve(target), validateDocument));
+    if (new Set(definitions.map(({ name }) => name)).size !== definitions.length) {
+        throw new FixtureDocumentError('Duplicate fixture name across paths');
+    }
+    return definitions;
+}
+function readFixtureDocuments(targetPath, validateDocument) {
+    const definitions = [];
+    for (const file of collectFiles(targetPath)) {
+        const document = readDocument(file);
+        const normalized = normalizeDocument(document, file, exports.MAX_FIXTURE_DEFINITIONS - definitions.length);
+        validateDocument?.(document, file);
+        definitions.push(...normalized);
+    }
+    const names = new Set();
+    for (const { name } of definitions) {
+        if (names.has(name))
+            throw new FixtureDocumentError('Duplicate fixture name', {
+                fixtureName: name,
+            });
+        names.add(name);
+    }
+    return definitions;
+}
+function collectFiles(targetPath) {
+    let stat;
+    try {
+        stat = node_fs_1.default.statSync(targetPath);
+    }
+    catch {
+        throw new FixtureDocumentError(`Fixture path not found: ${JSON.stringify(targetPath)}`);
+    }
+    if (stat.isFile()) {
+        if (!/\.(json|ya?ml)$/i.test(targetPath)) {
+            throw new FixtureDocumentError('Fixture file must use .json, .yml or .yaml');
+        }
+        return [targetPath];
+    }
+    if (!stat.isDirectory())
+        throw new FixtureDocumentError('Fixture path is not a file or directory');
+    const files = node_fs_1.default
+        .readdirSync(targetPath, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && /\.(json|ya?ml)$/i.test(entry.name))
+        .map((entry) => node_path_1.default.join(targetPath, entry.name))
+        .sort();
+    if (files.length > MAX_FILES)
+        throw new FixtureDocumentError('Too many fixture files');
+    return files;
+}
+function readDocument(file) {
+    if (node_fs_1.default.statSync(file).size > MAX_FILE_BYTES) {
+        throw new FixtureDocumentError(`Fixture file is too large: ${JSON.stringify(node_path_1.default.basename(file))}`);
+    }
+    const raw = node_fs_1.default.readFileSync(file, 'utf8');
+    try {
+        const value = /\.json$/i.test(file)
+            ? parseJson(raw)
+            : parseYaml(raw);
+        assertSafeFixtureValue(value);
+        return value;
+    }
+    catch (error) {
+        const detail = error instanceof FixtureDocumentError ? ` (${error.message})` : '';
+        throw new FixtureDocumentError(`Invalid fixture document: ${JSON.stringify(node_path_1.default.basename(file))}${detail}`, { file: node_path_1.default.basename(file) }, error);
+    }
+}
+function parseJson(raw) {
+    const value = JSON.parse(raw);
+    // JSON.parse keeps JSON scalar semantics but discards duplicate keys; YAML checks
+    // the original key structure without replacing the native JSON result.
+    parseYaml(raw);
+    return value;
+}
+function parseYaml(raw) {
+    const lineCounter = new yaml_1.LineCounter();
+    const document = (0, yaml_1.parseDocument)(raw, {
+        lineCounter,
+        prettyErrors: false,
+        strict: true,
+        stringKeys: true,
+        uniqueKeys: true,
+    });
+    const issue = document.errors[0] ?? document.warnings[0];
+    if (issue) {
+        const { line, col } = lineCounter.linePos(issue.pos[0]);
+        throw new FixtureDocumentError(`${issue.code} at ${line}:${col}`);
+    }
+    return document.toJS({ maxAliasCount: 0 });
+}
+function normalizeDocument(value, file, remaining) {
+    if (!isFixtureRecord(value))
+        throw invalidDocument(file);
+    assertKeys(value, [
+        'entity',
+        'locale',
+        'parameters',
+        'processor',
+        'connectedFields',
+        'deferredFields',
+        'items',
+    ], file);
+    const { entity, locale, parameters = {}, processor, connectedFields, deferredFields, items, } = value;
+    if (!isFixtureRecord(items))
+        throw invalidDocument(file);
+    assertFixtureMetadata({ ...value, parameters }, file);
+    const definitions = [];
+    const fixtureProcessor = typeof processor === 'string'
+        ? node_path_1.default.resolve(node_path_1.default.dirname(file), processor)
+        : undefined;
+    const fixtureConnectedFields = connectedFields;
+    const fixtureDeferredFields = deferredFields;
+    for (const [rawName, rawData] of Object.entries(items)) {
+        if (!isFixtureRecord(rawData))
+            throw invalidDocument(file);
+        const expandedNames = expandName(rawName, file);
+        if (expandedNames.length > remaining - definitions.length) {
+            throw new FixtureDocumentError('Too many fixture definitions');
+        }
+        for (const { name, current } of expandedNames) {
+            const definition = {
+                name,
+                entity,
+                data: replaceCurrent(rawData, current, file),
+                parameters: structuredClone(parameters),
+                ...(fixtureProcessor === undefined
+                    ? {}
+                    : { processor: fixtureProcessor }),
+                ...(locale === undefined ? {} : { locale }),
+                ...(fixtureConnectedFields === undefined
+                    ? {}
+                    : { connectedFields: [...fixtureConnectedFields] }),
+                ...(fixtureDeferredFields === undefined
+                    ? {}
+                    : { deferredFields: [...fixtureDeferredFields] }),
+            };
+            try {
+                assertFixtureDefinition(definition);
+            }
+            catch {
+                throw invalidDocument(file);
+            }
+            fixtureSources.set(definition, { file: node_path_1.default.basename(file) });
+            definitions.push(definition);
+        }
+    }
+    return definitions;
+}
+function expandName(rawName, file) {
+    const match = rawName.match(RANGE_PATTERN);
+    if (!match) {
+        if (!NAME_PATTERN.test(rawName) || exports.DANGEROUS_KEYS.has(rawName)) {
+            throw invalidDocument(file);
+        }
+        const suffix = rawName.match(/(\d+)$/)?.[1];
+        return [
+            {
+                name: rawName,
+                current: suffix === undefined ? undefined : Number(suffix),
+            },
+        ];
+    }
+    const start = Number(match[2]);
+    const end = Number(match[3]);
+    if (!Number.isSafeInteger(start) ||
+        !Number.isSafeInteger(end) ||
+        start > end ||
+        end - start + 1 > exports.MAX_FIXTURE_DEFINITIONS) {
+        throw invalidDocument(file);
+    }
+    return Array.from({ length: end - start + 1 }, (_, offset) => ({
+        name: `${match[1]}${start + offset}`,
+        current: start + offset,
+    }));
+}
+function replaceCurrent(value, current, file) {
+    if (typeof value === 'string') {
+        const replaced = value.replace(CURRENT_PATTERN, (_token, operator, rawOperand) => {
+            if (current === undefined)
+                throw invalidDocument(file);
+            const operand = rawOperand === undefined ? undefined : Number(rawOperand);
+            const result = calculateCurrent(current, operator, operand);
+            if (!Number.isFinite(result))
+                throw invalidDocument(file);
+            return String(result);
+        });
+        if (replaced.includes('($current'))
+            throw invalidDocument(file);
+        return replaced;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => replaceCurrent(item, current, file));
+    }
+    if (isFixtureRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            replaceCurrent(item, current, file),
+        ]));
+    }
+    return value;
+}
+function calculateCurrent(current, operator, operand) {
+    if (!operator || operand === undefined)
+        return current;
+    if (operator === '+')
+        return current + operand;
+    if (operator === '-')
+        return current - operand;
+    if (operator === '*')
+        return current * operand;
+    if (operator === '/')
+        return current / operand;
+    throw new Error('Invalid current operation');
+}
+function assertFixtureDefinition(value) {
+    if (!isFixtureRecord(value))
+        throw new Error('Invalid fixture definition');
+    assertKeys(value, [
+        'name',
+        'entity',
+        'data',
+        'parameters',
+        'processor',
+        'locale',
+        'connectedFields',
+        'deferredFields',
+    ]);
+    const { name, data, deferredFields } = value;
+    assertFixtureMetadata(value);
+    if (typeof name !== 'string' ||
+        !NAME_PATTERN.test(name) ||
+        exports.DANGEROUS_KEYS.has(name) ||
+        !isFixtureRecord(data)) {
+        throw new Error('Invalid fixture definition');
+    }
+    if (Array.isArray(deferredFields) &&
+        deferredFields.some((field) => field === 'id' || !Object.hasOwn(data, field))) {
+        throw new Error('Invalid deferred fixture field');
+    }
+    assertSafeFixtureValue(value);
+}
+function assertFixtureMetadata(metadata, file) {
+    const { entity, parameters, processor, locale, connectedFields, deferredFields, } = metadata;
+    if (typeof entity !== 'string' ||
+        !NAME_PATTERN.test(entity) ||
+        exports.DANGEROUS_KEYS.has(entity) ||
+        !isFixtureRecord(parameters) ||
+        (processor !== undefined &&
+            (typeof processor !== 'string' || !processor)) ||
+        (locale !== undefined && (typeof locale !== 'string' || !locale)) ||
+        (connectedFields !== undefined && !isFieldList(connectedFields)) ||
+        (deferredFields !== undefined &&
+            (!isFieldList(deferredFields) ||
+                deferredFields.length === 0 ||
+                deferredFields.some((field) => Array.isArray(connectedFields) && connectedFields.includes(field))))) {
+        throw file ? invalidDocument(file) : new Error('Invalid fixture definition');
+    }
+}
+function isFieldList(value) {
+    return (Array.isArray(value) &&
+        value.every((field) => typeof field === 'string' &&
+            FIELD_PATTERN.test(field) &&
+            !exports.DANGEROUS_KEYS.has(field)) &&
+        new Set(value).size === value.length);
+}
+function isFixtureRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === null || Object.getPrototypeOf(prototype) === null;
+}
+function assertSafeFixtureValue(value) {
+    let nodes = 0;
+    const visit = (current, depth) => {
+        if (++nodes > MAX_NODES || depth > MAX_DEPTH)
+            throw new Error('Fixture data is too deep');
+        if (Array.isArray(current))
+            return current.forEach((item) => visit(item, depth + 1));
+        if (!isFixtureRecord(current))
+            return;
+        for (const [key, item] of Object.entries(current)) {
+            if (exports.DANGEROUS_KEYS.has(key))
+                throw new Error('Unsafe fixture key');
+            visit(item, depth + 1);
+        }
+    };
+    visit(value, 0);
+}
+function assertKeys(value, allowed, file) {
+    if (Object.keys(value).some((key) => !allowed.includes(key))) {
+        throw file ? invalidDocument(file) : new Error('Invalid fixture definition');
+    }
+}
+function invalidDocument(file) {
+    return new FixtureDocumentError(`Invalid fixture document: ${JSON.stringify(node_path_1.default.basename(file))}`, { file: node_path_1.default.basename(file) });
+}

package/dist/fixture-error.d.ts

@@ -0,0 +1,22 @@
+export type FixtureErrorCode = 'FIXTURE_OPTIONS_INVALID' | 'FIXTURE_DOCUMENT_INVALID' | 'FIXTURE_REFERENCE_INVALID' | 'FIXTURE_REFERENCE_MISSING' | 'FIXTURE_REFERENCE_FIELD_MISSING' | 'FIXTURE_DEPENDENCY_CYCLE' | 'FIXTURE_TEMPLATE_FAILED' | 'FIXTURE_PROCESSOR_FAILED' | 'FIXTURE_CONNECTION_FAILED' | 'FIXTURE_WRITE_FAILED';
+export type FixtureErrorContext = {
+    stage: string;
+    file?: string;
+    fixtureName?: string;
+    entity?: string;
+    path?: string;
+};
+export declare class FixtureError extends Error {
+    readonly code: FixtureErrorCode;
+    readonly stage: string;
+    readonly file?: string;
+    readonly fixtureName?: string;
+    readonly entity?: string;
+    readonly path?: string;
+    constructor(code: FixtureErrorCode, message: string, context: FixtureErrorContext, cause?: unknown);
+}
+export declare function createFixtureError(code: FixtureErrorCode, message: string, context: FixtureErrorContext, cause?: unknown): FixtureError;
+export declare function markFixtureErrorTrusted<T extends FixtureError>(error: T): T;
+export declare function isTrustedFixtureError(error: unknown): error is FixtureError;
+export declare function wrapFixtureError(error: unknown, code: FixtureErrorCode, message: string, context: FixtureErrorContext): FixtureError;
+export declare function appendFixturePath(path: string, part: string | number): string;

package/dist/fixture-error.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FixtureError = void 0;
+exports.createFixtureError = createFixtureError;
+exports.markFixtureErrorTrusted = markFixtureErrorTrusted;
+exports.isTrustedFixtureError = isTrustedFixtureError;
+exports.wrapFixtureError = wrapFixtureError;
+exports.appendFixturePath = appendFixturePath;
+const trustedFixtureErrors = new WeakSet();
+class FixtureError extends Error {
+    code;
+    stage;
+    file;
+    fixtureName;
+    entity;
+    path;
+    constructor(code, message, context, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'FixtureError';
+        this.code = code;
+        this.stage = context.stage;
+        this.file = context.file;
+        this.fixtureName = context.fixtureName;
+        this.entity = context.entity;
+        this.path = context.path;
+    }
+}
+exports.FixtureError = FixtureError;
+function createFixtureError(code, message, context, cause) {
+    return markFixtureErrorTrusted(new FixtureError(code, message, context, cause));
+}
+function markFixtureErrorTrusted(error) {
+    trustedFixtureErrors.add(error);
+    return Object.freeze(error);
+}
+function isTrustedFixtureError(error) {
+    return error instanceof FixtureError && trustedFixtureErrors.has(error);
+}
+function wrapFixtureError(error, code, message, context) {
+    if (isTrustedFixtureError(error)) {
+        return createFixtureError(error.code, error.message, {
+            stage: error.stage || context.stage,
+            file: error.file ?? context.file,
+            fixtureName: error.fixtureName ?? context.fixtureName,
+            entity: error.entity ?? context.entity,
+            path: error.path ?? context.path,
+        }, error.cause);
+    }
+    return createFixtureError(code, message, context, error);
+}
+function appendFixturePath(path, part) {
+    const token = String(part).replaceAll('~', '~0').replaceAll('/', '~1');
+    return `${path}/${token}`;
+}

package/dist/fixture-reference.d.ts

@@ -0,0 +1,17 @@
+import { type FixtureDefinition } from './fixture-document';
+type Dependency = {
+    name: string;
+    path: string;
+};
+export type PreparedFixture = FixtureDefinition & {
+    dependencies: Dependency[];
+};
+export declare function lintFixtureReferences(definitions: FixtureDefinition[]): {
+    unresolved: number;
+};
+export declare function prepareFixtureReferences(definitions: FixtureDefinition[], random?: {
+    next: () => number;
+}): PreparedFixture[];
+export declare function resolveFixtureReferences(value: unknown, records: Record<string, Record<string, unknown>>, fixture?: FixtureDefinition, path?: string): unknown;
+export declare function applyFixtureConnections(data: Record<string, unknown>, connectedFields: string[] | undefined, fixture?: FixtureDefinition): Record<string, unknown>;
+export {};

package/dist/fixture-reference.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintFixtureReferences = lintFixtureReferences;
+exports.prepareFixtureReferences = prepareFixtureReferences;
+exports.resolveFixtureReferences = resolveFixtureReferences;
+exports.applyFixtureConnections = applyFixtureConnections;
+const fixture_document_1 = require("./fixture-document");
+const fixture_error_1 = require("./fixture-error");
+const FIXED_REFERENCE = /^@([A-Za-z][A-Za-z0-9_-]{0,127})(?:\.([A-Za-z][A-Za-z0-9_]*))?$/;
+const WILDCARD_REFERENCE = /^@([A-Za-z][A-Za-z0-9_-]{0,126})\*$/;
+const RANGE_REFERENCE = /^@([A-Za-z][A-Za-z0-9_-]*)\{(\d+)\.\.(\d+)\}$/;
+const DYNAMIC_VALUE = /<%|{{|<{/;
+function lintFixtureReferences(definitions) {
+    const byName = new Map(definitions.map((fixture) => [fixture.name, fixture]));
+    const dependencies = new Map();
+    let unresolved = 0;
+    for (const fixture of definitions) {
+        const found = [];
+        unresolved += lintValue(fixture.data, byName, found, fixture, '');
+        dependencies.set(fixture.name, found);
+    }
+    orderFixtures(definitions, dependencies, 'linting references');
+    return { unresolved };
+}
+function lintValue(value, definitions, dependencies, fixture, path) {
+    if (typeof value === 'string') {
+        if (DYNAMIC_VALUE.test(value))
+            return 1;
+        if (!value.startsWith('@') || value.startsWith('@@'))
+            return 0;
+        const fixed = value.match(FIXED_REFERENCE);
+        if (fixed) {
+            const [, name, field] = fixed;
+            if (!definitions.has(name)) {
+                throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_MISSING', 'Fixture reference target not found', (0, fixture_document_1.fixtureErrorContext)(fixture, 'linting references', path));
+            }
+            if (field && fixture_document_1.DANGEROUS_KEYS.has(field)) {
+                throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_INVALID', 'Unsafe fixture reference field', (0, fixture_document_1.fixtureErrorContext)(fixture, 'linting references', path));
+            }
+            dependencies.push({ name: name, path });
+            return 0;
+        }
+        const candidates = referenceCandidates(value, definitions, fixture, path, 'linting references');
+        if (!candidates) {
+            throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_INVALID', 'Invalid fixture reference', (0, fixture_document_1.fixtureErrorContext)(fixture, 'linting references', path));
+        }
+        if (candidates.length === 1) {
+            dependencies.push({ name: candidates[0], path });
+            return 0;
+        }
+        return 1;
+    }
+    if (Array.isArray(value)) {
+        return value.reduce((count, item, index) => count +
+            lintValue(item, definitions, dependencies, fixture, (0, fixture_error_1.appendFixturePath)(path, index)), 0);
+    }
+    if ((0, fixture_document_1.isFixtureRecord)(value)) {
+        return Object.entries(value).reduce((count, [key, item]) => count +
+            lintValue(item, definitions, dependencies, fixture, (0, fixture_error_1.appendFixturePath)(path, key)), 0);
+    }
+    return 0;
+}
+function prepareFixtureReferences(definitions, random = { next: Math.random }) {
+    const byName = new Map(definitions.map((fixture) => [fixture.name, fixture]));
+    const prepared = definitions.map((fixture) => {
+        const dependencies = [];
+        const data = prepareValue(fixture.data, byName, dependencies, random, fixture, '');
+        const result = {
+            ...fixture,
+            data: data,
+            dependencies,
+        };
+        (0, fixture_document_1.inheritFixtureSource)(fixture, result);
+        return result;
+    });
+    return orderFixtures(prepared, new Map(prepared.map(({ name, dependencies }) => [name, dependencies])), 'ordering fixtures');
+}
+function prepareValue(value, definitions, dependencies, random, fixture, path) {
+    if (typeof value === 'string') {
+        if (!value.startsWith('@') || value.startsWith('@@'))
+            return value;
+        const selected = selectReference(value, definitions, random, fixture, path);
+        const match = selected.match(FIXED_REFERENCE);
+        if (!match) {
+            throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_INVALID', 'Invalid fixture reference', (0, fixture_document_1.fixtureErrorContext)(fixture, 'preparing references', path));
+        }
+        const [, name, field] = match;
+        const target = definitions.get(name);
+        if (!target) {
+            throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_MISSING', 'Fixture reference target not found', (0, fixture_document_1.fixtureErrorContext)(fixture, 'preparing references', path));
+        }
+        if (field && fixture_document_1.DANGEROUS_KEYS.has(field)) {
+            throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_INVALID', 'Unsafe fixture reference field', (0, fixture_document_1.fixtureErrorContext)(fixture, 'preparing references', path));
+        }
+        if (!dependencies.some((dependency) => dependency.name === name)) {
+            dependencies.push({ name: name, path });
+        }
+        return selected;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => prepareValue(item, definitions, dependencies, random, fixture, (0, fixture_error_1.appendFixturePath)(path, index)));
+    }
+    if ((0, fixture_document_1.isFixtureRecord)(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            prepareValue(item, definitions, dependencies, random, fixture, (0, fixture_error_1.appendFixturePath)(path, key)),
+        ]));
+    }
+    return value;
+}
+function selectReference(value, definitions, random, fixture, path) {
+    const candidates = referenceCandidates(value, definitions, fixture, path);
+    return candidates ? `@${pick(candidates, random)}` : value;
+}
+function referenceCandidates(value, definitions, fixture, path, stage = 'preparing references') {
+    const wildcard = value.match(WILDCARD_REFERENCE);
+    if (wildcard) {
+        const pattern = new RegExp(`^${wildcard[1]}\\d+$`);
+        const candidates = [...definitions.keys()].filter((name) => pattern.test(name));
+        if (!candidates.length) {
+            throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_MISSING', 'Fixture reference candidates not found', (0, fixture_document_1.fixtureErrorContext)(fixture, stage, path));
+        }
+        return candidates;
+    }
+    const range = value.match(RANGE_REFERENCE);
+    if (!range)
+        return undefined;
+    const start = Number(range[2]);
+    const end = Number(range[3]);
+    const length = end - start + 1;
+    if (!Number.isSafeInteger(start) ||
+        !Number.isSafeInteger(end) ||
+        !Number.isSafeInteger(length) ||
+        start > end) {
+        throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_INVALID', 'Invalid fixture reference range', (0, fixture_document_1.fixtureErrorContext)(fixture, stage, path));
+    }
+    if (length > definitions.size) {
+        throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_MISSING', 'Fixture reference candidates not found', (0, fixture_document_1.fixtureErrorContext)(fixture, stage, path));
+    }
+    const candidates = Array.from({ length }, (_, offset) => `${range[1]}${start + offset}`);
+    if (candidates.some((name) => !definitions.has(name))) {
+        throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_MISSING', 'Fixture reference candidates not found', (0, fixture_document_1.fixtureErrorContext)(fixture, stage, path));
+    }
+    return candidates;
+}
+function pick(values, random) {
+    return values[Math.floor(random.next() * values.length)];
+}
+function orderFixtures(fixtures, dependencies, stage) {
+    const byName = new Map(fixtures.map((fixture) => [fixture.name, fixture]));
+    const state = new Map();
+    const ordered = [];
+    const stack = [];
+    const visit = (fixture) => {
+        if (state.get(fixture.name) === 'visited')
+            return;
+        state.set(fixture.name, 'visiting');
+        stack.push(fixture.name);
+        for (const dependency of dependencies.get(fixture.name) ?? []) {
+            if (state.get(dependency.name) === 'visiting') {
+                const start = stack.indexOf(dependency.name);
+                const cycle = [...stack.slice(start), dependency.name].join(' -> ');
+                throw (0, fixture_error_1.createFixtureError)('FIXTURE_DEPENDENCY_CYCLE', `Fixture dependency cycle: ${cycle}`, (0, fixture_document_1.fixtureErrorContext)(fixture, stage, dependency.path));
+            }
+            visit(byName.get(dependency.name));
+        }
+        stack.pop();
+        state.set(fixture.name, 'visited');
+        ordered.push(fixture);
+    };
+    fixtures.forEach(visit);
+    return ordered;
+}
+function resolveFixtureReferences(value, records, fixture, path = '') {
+    if (typeof value === 'string') {
+        if (value.startsWith('@@'))
+            return value.slice(1);
+        if (!value.startsWith('@'))
+            return value;
+        const match = value.match(FIXED_REFERENCE);
+        if (!match) {
+            throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_INVALID', 'Invalid fixture reference', (0, fixture_document_1.fixtureErrorContext)(fixture, 'resolving references', path));
+        }
+        const [, name, field] = match;
+        const record = records[name];
+        if (!record) {
+            throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_MISSING', 'Fixture reference target was not loaded', (0, fixture_document_1.fixtureErrorContext)(fixture, 'resolving references', path));
+        }
+        if (!field)
+            return record;
+        if (fixture_document_1.DANGEROUS_KEYS.has(field)) {
+            throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_INVALID', 'Unsafe fixture reference field', (0, fixture_document_1.fixtureErrorContext)(fixture, 'resolving references', path));
+        }
+        if (!Object.hasOwn(record, field) || record[field] === undefined) {
+            throw (0, fixture_error_1.createFixtureError)('FIXTURE_REFERENCE_FIELD_MISSING', 'Referenced fixture field is missing from the loaded record', (0, fixture_document_1.fixtureErrorContext)(fixture, 'resolving references', path));
+        }
+        return record[field];
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => resolveFixtureReferences(item, records, fixture, (0, fixture_error_1.appendFixturePath)(path, index)));
+    }
+    if ((0, fixture_document_1.isFixtureRecord)(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            resolveFixtureReferences(item, records, fixture, (0, fixture_error_1.appendFixturePath)(path, key)),
+        ]));
+    }
+    return value;
+}
+function applyFixtureConnections(data, connectedFields, fixture) {
+    if (!connectedFields?.length)
+        return data;
+    const connected = { ...data };
+    for (const field of connectedFields) {
+        if (!Object.hasOwn(connected, field) || connected[field] == null)
+            continue;
+        const value = connected[field];
+        const fieldPath = (0, fixture_error_1.appendFixturePath)('', field);
+        connected[field] = {
+            connect: Array.isArray(value)
+                ? value.map((record, index) => connectionId(record, fixture, (0, fixture_error_1.appendFixturePath)(fieldPath, index)))
+                : connectionId(value, fixture, fieldPath),
+        };
+    }
+    return connected;
+}
+function connectionId(value, fixture, path) {
+    if (!(0, fixture_document_1.isFixtureRecord)(value) ||
+        !Object.hasOwn(value, 'id') ||
+        value.id === undefined) {
+        throw (0, fixture_error_1.createFixtureError)('FIXTURE_CONNECTION_FAILED', 'Fixture connection record is invalid', (0, fixture_document_1.fixtureErrorContext)(fixture, 'connecting fixture', path));
+    }
+    return { id: value.id };
+}