@mosaic-code/prisma-deadlock-avoidance-tests 0.1.0

package/dist/graphs/table-graph.d.ts

@@ -0,0 +1,61 @@
+import { Graph } from '@dagrejs/graphlib';
+import type { CallerInfo, TableEdgeLabel, TableCycleInfo } from '../types.js';
+/**
+ * Manages a directed graph of table lock ordering.
+ * Nodes represent tables, edges represent "table A was locked before table B".
+ */
+export declare class TableLockGraph {
+    private graph;
+    constructor();
+    /**
+     * Add an edge indicating that `from` table was locked before `to` table.
+     * Deduplicates callers by file:line.
+     */
+    addEdge(from: string, to: string, caller: CallerInfo): void;
+    /**
+     * Merge edges from another graph into this one.
+     * Used to merge transaction graphs into the global graph.
+     */
+    mergeFrom(other: TableLockGraph): void;
+    /**
+     * Check if the graph has any cycles
+     */
+    hasCycles(): boolean;
+    /**
+     * Find all cycles in the graph
+     */
+    findCycles(): string[][];
+    /**
+     * Find cycles and build detailed cycle info including callers
+     */
+    findCyclesWithCallers(): TableCycleInfo[];
+    /**
+     * Build detailed cycle info for a cycle
+     */
+    private buildCycleInfo;
+    /**
+     * Get the edge label between two tables
+     */
+    getEdge(from: string, to: string): TableEdgeLabel | undefined;
+    /**
+     * Get all tables in the graph
+     */
+    getTables(): string[];
+    /**
+     * Get all edges in the graph
+     */
+    getEdges(): Array<{
+        from: string;
+        to: string;
+        label: TableEdgeLabel;
+    }>;
+    /**
+     * Clear all data from the graph
+     */
+    reset(): void;
+    /**
+     * Get the underlying graphlib Graph (for testing)
+     */
+    getUnderlyingGraph(): Graph;
+}
+//# sourceMappingURL=table-graph.d.ts.map

package/dist/graphs/table-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-graph.d.ts","sourceRoot":"","sources":["../../src/graphs/table-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAO,MAAM,mBAAmB,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAG7E;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAO;;IAMpB;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAsB3D;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAStC;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,UAAU,IAAI,MAAM,EAAE,EAAE;IAIxB;;OAEG;IACH,qBAAqB,IAAI,cAAc,EAAE;IAKzC;;OAEG;IACH,OAAO,CAAC,cAAc;IAwBtB;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7D;;OAEG;IACH,SAAS,IAAI,MAAM,EAAE;IAIrB;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,cAAc,CAAA;KAAE,CAAC;IAQtE;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,kBAAkB,IAAI,KAAK;CAG5B"}

package/dist/graphs/table-graph.js

@@ -0,0 +1,123 @@
+import { Graph, alg } from '@dagrejs/graphlib';
+import { addCallerIfUnique } from '../utils/caller-extractor.js';
+/**
+ * Manages a directed graph of table lock ordering.
+ * Nodes represent tables, edges represent "table A was locked before table B".
+ */
+export class TableLockGraph {
+    graph;
+    constructor() {
+        this.graph = new Graph({ directed: true });
+    }
+    /**
+     * Add an edge indicating that `from` table was locked before `to` table.
+     * Deduplicates callers by file:line.
+     */
+    addEdge(from, to, caller) {
+        // Ensure nodes exist
+        if (!this.graph.hasNode(from)) {
+            this.graph.setNode(from);
+        }
+        if (!this.graph.hasNode(to)) {
+            this.graph.setNode(to);
+        }
+        // Get or create edge label
+        const existingLabel = this.graph.edge(from, to);
+        if (existingLabel) {
+            // Deduplicate callers by file:line
+            addCallerIfUnique(existingLabel.callers, caller);
+        }
+        else {
+            this.graph.setEdge(from, to, { callers: [caller] });
+        }
+    }
+    /**
+     * Merge edges from another graph into this one.
+     * Used to merge transaction graphs into the global graph.
+     */
+    mergeFrom(other) {
+        for (const edge of other.graph.edges()) {
+            const label = other.graph.edge(edge);
+            for (const caller of label.callers) {
+                this.addEdge(edge.v, edge.w, caller);
+            }
+        }
+    }
+    /**
+     * Check if the graph has any cycles
+     */
+    hasCycles() {
+        return !alg.isAcyclic(this.graph);
+    }
+    /**
+     * Find all cycles in the graph
+     */
+    findCycles() {
+        return alg.findCycles(this.graph);
+    }
+    /**
+     * Find cycles and build detailed cycle info including callers
+     */
+    findCyclesWithCallers() {
+        const cycles = this.findCycles();
+        return cycles.map((cycle) => this.buildCycleInfo(cycle));
+    }
+    /**
+     * Build detailed cycle info for a cycle
+     */
+    buildCycleInfo(cycle) {
+        const callers = [];
+        // For each consecutive pair of tables in the cycle, find the edge callers
+        for (let i = 0; i < cycle.length; i++) {
+            const from = cycle[i];
+            const to = cycle[(i + 1) % cycle.length];
+            const label = this.graph.edge(from, to);
+            if (label && label.callers.length > 0) {
+                // Add the first caller for this edge
+                callers.push({
+                    table: to,
+                    caller: label.callers[0],
+                });
+            }
+        }
+        return {
+            tables: cycle,
+            callers,
+        };
+    }
+    /**
+     * Get the edge label between two tables
+     */
+    getEdge(from, to) {
+        return this.graph.edge(from, to);
+    }
+    /**
+     * Get all tables in the graph
+     */
+    getTables() {
+        return this.graph.nodes();
+    }
+    /**
+     * Get all edges in the graph
+     */
+    getEdges() {
+        return this.graph.edges().map((e) => ({
+            from: e.v,
+            to: e.w,
+            label: this.graph.edge(e),
+        }));
+    }
+    /**
+     * Clear all data from the graph
+     */
+    reset() {
+        this.graph = new Graph({ directed: true });
+    }
+    /**
+     * Get the underlying graphlib Graph (for testing)
+     */
+    getUnderlyingGraph() {
+        return this.graph;
+    }
+}
+//# sourceMappingURL=table-graph.js.map

package/dist/graphs/table-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-graph.js","sourceRoot":"","sources":["../../src/graphs/table-graph.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { withDeadlockDetection } from './extension.js';
+export { assertConsistentTableLocking, assertConsistentRowLocking, assertNoDeadlockRisk, resetDeadlockDetection, trackForUpdate, } from './extension.js';
+export { TableLockingAssertionError } from './assertions/table-assertion.js';
+export { RowLockingAssertionError } from './assertions/row-assertion.js';
+export type { CallerInfo, StrictMode, RowLockingOptions, TableCycleInfo, RowCycleInfo, DeadlockDetectionConfig, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAGtD,OAAO,EACL,4BAA4B,EAC5B,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,GACf,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AAC5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAGxE,YAAY,EACV,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,uBAAuB,GACxB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// Main extension
+export { withDeadlockDetection } from './extension.js';
+// Assertion functions
+export { assertConsistentTableLocking, assertConsistentRowLocking, assertNoDeadlockRisk, resetDeadlockDetection, trackForUpdate, } from './extension.js';
+// Error types
+export { TableLockingAssertionError } from './assertions/table-assertion.js';
+export { RowLockingAssertionError } from './assertions/row-assertion.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iBAAiB;AACjB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAEtD,sBAAsB;AACtB,OAAO,EACL,4BAA4B,EAC5B,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,GACf,MAAM,gBAAgB,CAAA;AAEvB,cAAc;AACd,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AAC5E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Information about where a locking operation was called from
+ */
+export interface CallerInfo {
+    file: string;
+    line: number;
+    column: number;
+    functionName?: string;
+}
+/**
+ * Operations that acquire locks on database records
+ */
+export type LockingOperation = 'findUniqueForUpdate' | 'findFirstForUpdate' | 'findManyForUpdate' | 'update' | 'updateMany' | 'delete' | 'deleteMany' | 'create' | 'createMany' | 'createManyAndReturn' | 'upsert' | '$queryRaw' | '$queryRawUnsafe' | '$executeRaw' | '$executeRawUnsafe';
+/**
+ * Strict ordering modes for row locking assertions
+ * - 'ASC': Primary keys must always be locked in ascending order
+ * - 'DESC': Primary keys must always be locked in descending order
+ * - true: Primary keys must be consistently ordered (either all ASC or all DESC)
+ * - false: No ordering requirement, only cycles are violations
+ */
+export type StrictMode = 'ASC' | 'DESC' | true | false;
+/**
+ * Options for assertConsistentRowLocking
+ */
+export interface RowLockingOptions {
+    /** Specific tables to check. If empty/undefined, checks all tables. */
+    tables?: string[];
+    /** Ordering strictness mode. Defaults to false. */
+    strict?: StrictMode;
+}
+/**
+ * Information about a cycle detected in table locking order
+ */
+export interface TableCycleInfo {
+    /** Tables involved in the cycle, in order */
+    tables: string[];
+    /** Callers that contributed to the cycle */
+    callers: Array<{
+        table: string;
+        caller: CallerInfo;
+    }>;
+}
+/**
+ * Information about a cycle or ordering violation in row locking
+ */
+export interface RowCycleInfo {
+    /** The table where the violation occurred */
+    table: string;
+    /** Primary keys involved in the cycle/violation */
+    primaryKeys: Array<string | number>;
+    /** Callers that contributed to the issue */
+    callers: CallerInfo[];
+    /** Optional message describing the violation */
+    message?: string;
+}
+/**
+ * Label stored on table graph edges
+ */
+export interface TableEdgeLabel {
+    /** All callers that created this edge (deduplicated by file:line) */
+    callers: CallerInfo[];
+}
+/**
+ * Label stored on row graph edges
+ */
+export interface RowEdgeLabel {
+    /** All callers that created this edge */
+    callers: CallerInfo[];
+    /** The table this edge belongs to */
+    table: string;
+}
+/**
+ * Configuration options for the deadlock detection extension
+ */
+export interface DeadlockDetectionConfig {
+    /** Whether detection is enabled. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Model metadata from Prisma DMMF
+ */
+export interface ModelMeta {
+    name: string;
+    dbName: string | null;
+    fields: ModelField[];
+}
+/**
+ * Field metadata from Prisma DMMF
+ */
+export interface ModelField {
+    name: string;
+    kind: 'scalar' | 'object' | 'enum' | 'unsupported';
+    type: string;
+    dbName: string | null;
+    isId: boolean;
+    isUnique: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,qBAAqB,GACrB,oBAAoB,GACpB,mBAAmB,GACnB,QAAQ,GACR,YAAY,GACZ,QAAQ,GACR,YAAY,GACZ,QAAQ,GACR,YAAY,GACZ,qBAAqB,GACrB,QAAQ,GACR,WAAW,GACX,iBAAiB,GACjB,aAAa,GACb,mBAAmB,CAAA;AAEvB;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,CAAA;AAEtD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,mDAAmD;IACnD,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,4CAA4C;IAC5C,OAAO,EAAE,KAAK,CAAC;QACb,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,UAAU,CAAA;KACnB,CAAC,CAAA;CACH;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,WAAW,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAA;IACnC,4CAA4C;IAC5C,OAAO,EAAE,UAAU,EAAE,CAAA;IACrB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,OAAO,EAAE,UAAU,EAAE,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,OAAO,EAAE,UAAU,EAAE,CAAA;IACrB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,EAAE,UAAU,EAAE,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,aAAa,CAAA;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,EAAE,OAAO,CAAA;IACb,QAAQ,EAAE,OAAO,CAAA;CAClB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils/caller-extractor.d.ts

@@ -0,0 +1,27 @@
+import type { CallerInfo } from '../types.js';
+/**
+ * Extract the first relevant caller from the current stack trace.
+ * Filters out node_modules, Prisma internals, and this library's code.
+ *
+ * @returns CallerInfo for the first non-library caller, or a fallback if none found
+ */
+export declare function extractCaller(): CallerInfo;
+/**
+ * Create a unique key for a caller based on file and line.
+ * Used for deduplication in graphs.
+ */
+export declare function callerKey(caller: CallerInfo): string;
+/**
+ * Add a caller to an array if it's not already present (deduplicated by file:line).
+ * Modifies the array in place.
+ *
+ * @param callers Array of callers to add to
+ * @param caller Caller to add if unique
+ */
+export declare function addCallerIfUnique(callers: CallerInfo[], caller: CallerInfo): void;
+/**
+ * Format a CallerInfo as a human-readable string.
+ * File paths are made relative to the current working directory.
+ */
+export declare function formatCaller(caller: CallerInfo): string;
+//# sourceMappingURL=caller-extractor.d.ts.map

package/dist/utils/caller-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller-extractor.d.ts","sourceRoot":"","sources":["../../src/utils/caller-extractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AA+F7C;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAmB1C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAMjF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAOvD"}

package/dist/utils/caller-extractor.js

@@ -0,0 +1,144 @@
+import { fileURLToPath } from 'node:url';
+import { relative } from 'node:path';
+/**
+ * Get the current working directory for relative path calculation
+ */
+function getCwd() {
+    // Try to get from process.cwd() first, fall back to the URL of this module
+    try {
+        return process.cwd();
+    }
+    catch {
+        // Fallback: use this file's location
+        const moduleUrl = import.meta.url;
+        const modulePath = fileURLToPath(moduleUrl);
+        return modulePath.slice(0, modulePath.lastIndexOf('/'));
+    }
+}
+/**
+ * Make a file path relative to the current working directory if possible.
+ * Returns the original path if it cannot be made relative.
+ */
+function makeRelativePath(filePath) {
+    if (filePath === 'unknown') {
+        return filePath;
+    }
+    // Don't try to make non-file paths relative
+    if (filePath.startsWith('node:') || filePath.startsWith('(node:')) {
+        return filePath;
+    }
+    try {
+        const cwd = getCwd();
+        return relative(cwd, filePath);
+    }
+    catch {
+        // If relative path calculation fails, return original
+        return filePath;
+    }
+}
+/**
+ * Patterns to filter out from stack traces.
+ * These represent library code that should not be considered the "caller"
+ */
+const IGNORE_PATTERNS = [
+    /node_modules/,
+    /\.prisma[\\/]client/,
+    /prisma-deadlock-avoidance-tests[\\/](?:src|dist)[\\/]/,
+    /prisma-select-for-update[\\/](?:src|dist)[\\/]/,
+    /\(node:/,
+    /^node:/,
+];
+/**
+ * Parse a V8 stack frame line and extract location info.
+ * Handles both formats:
+ * - "    at functionName (file:line:column)"
+ * - "    at file:line:column"
+ */
+function parseStackFrame(line) {
+    // Try format: "at functionName (file:line:column)"
+    const withFnMatch = line.match(/at\s+(.+?)\s+\((.+):(\d+):(\d+)\)/);
+    if (withFnMatch) {
+        const [, functionName, file, lineStr, columnStr] = withFnMatch;
+        return {
+            file,
+            line: parseInt(lineStr, 10),
+            column: parseInt(columnStr, 10),
+            functionName: functionName || undefined,
+        };
+    }
+    // Try format: "at file:line:column"
+    const withoutFnMatch = line.match(/at\s+(.+):(\d+):(\d+)/);
+    if (withoutFnMatch) {
+        const [, file, lineStr, columnStr] = withoutFnMatch;
+        return {
+            file,
+            line: parseInt(lineStr, 10),
+            column: parseInt(columnStr, 10),
+        };
+    }
+    return null;
+}
+/**
+ * Check if a file path should be ignored
+ */
+function shouldIgnore(file) {
+    return IGNORE_PATTERNS.some((pattern) => pattern.test(file));
+}
+/**
+ * Extract the first relevant caller from the current stack trace.
+ * Filters out node_modules, Prisma internals, and this library's code.
+ *
+ * @returns CallerInfo for the first non-library caller, or a fallback if none found
+ */
+export function extractCaller() {
+    const stack = new Error().stack ?? '';
+    const lines = stack.split('\n').slice(1); // Skip "Error" line
+    for (const line of lines) {
+        const parsed = parseStackFrame(line);
+        if (!parsed)
+            continue;
+        if (!shouldIgnore(parsed.file)) {
+            return parsed;
+        }
+    }
+    // Fallback if no relevant frame found
+    return {
+        file: 'unknown',
+        line: 0,
+        column: 0,
+    };
+}
+/**
+ * Create a unique key for a caller based on file and line.
+ * Used for deduplication in graphs.
+ */
+export function callerKey(caller) {
+    return `${caller.file}:${caller.line}`;
+}
+/**
+ * Add a caller to an array if it's not already present (deduplicated by file:line).
+ * Modifies the array in place.
+ *
+ * @param callers Array of callers to add to
+ * @param caller Caller to add if unique
+ */
+export function addCallerIfUnique(callers, caller) {
+    const key = callerKey(caller);
+    const alreadyExists = callers.some((c) => callerKey(c) === key);
+    if (!alreadyExists) {
+        callers.push(caller);
+    }
+}
+/**
+ * Format a CallerInfo as a human-readable string.
+ * File paths are made relative to the current working directory.
+ */
+export function formatCaller(caller) {
+    const relativeFile = makeRelativePath(caller.file);
+    const location = `${relativeFile}:${caller.line}:${caller.column}`;
+    if (caller.functionName) {
+        return `${caller.functionName} (${location})`;
+    }
+    return location;
+}
+//# sourceMappingURL=caller-extractor.js.map

package/dist/utils/caller-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller-extractor.js","sourceRoot":"","sources":["../../src/utils/caller-extractor.ts"],"names":[],"mappings":"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"}

package/dist/utils/primary-key-extractor.d.ts

@@ -0,0 +1,23 @@
+import type { ModelMeta, ModelField } from '../types.js';
+/**
+ * Get model metadata from Prisma DMMF
+ */
+export declare function getModelMeta(modelName: string): ModelMeta | null;
+/**
+ * Get the primary key field(s) for a model
+ */
+export declare function getPrimaryKeyFields(model: ModelMeta): ModelField[];
+/**
+ * Extract primary key value from a single result object
+ */
+export declare function extractPrimaryKey(model: ModelMeta, result: Record<string, unknown>): string | null;
+/**
+ * Extract primary keys from query results (array or single object)
+ */
+export declare function extractPrimaryKeys(modelName: string, result: unknown): string[];
+/**
+ * Extract primary keys from a raw result, handling both model field names
+ * and database column names
+ */
+export declare function extractPrimaryKeysFromRaw(modelName: string, results: Record<string, unknown>[]): string[];
+//# sourceMappingURL=primary-key-extractor.d.ts.map

package/dist/utils/primary-key-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primary-key-extractor.d.ts","sourceRoot":"","sources":["../../src/utils/primary-key-extractor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExD;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAsBhE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,EAAE,CAElE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,GAAG,IAAI,CA4Bf;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO,GACd,MAAM,EAAE,CAyBV;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GACjC,MAAM,EAAE,CA6CV"}

package/dist/utils/primary-key-extractor.js

@@ -0,0 +1,128 @@
+import { Prisma } from '@prisma/client';
+/**
+ * Get model metadata from Prisma DMMF
+ */
+export function getModelMeta(modelName) {
+    const dmmf = Prisma.dmmf;
+    const model = dmmf.datamodel.models.find((m) => m.name.toLowerCase() === modelName.toLowerCase());
+    if (!model) {
+        return null;
+    }
+    return {
+        name: model.name,
+        dbName: model.dbName ?? null,
+        fields: model.fields.map((f) => ({
+            name: f.name,
+            kind: f.kind,
+            type: f.type,
+            dbName: f.dbName ?? null,
+            isId: f.isId ?? false,
+            isUnique: f.isUnique ?? false,
+        })),
+    };
+}
+/**
+ * Get the primary key field(s) for a model
+ */
+export function getPrimaryKeyFields(model) {
+    return model.fields.filter((f) => f.isId);
+}
+/**
+ * Extract primary key value from a single result object
+ */
+export function extractPrimaryKey(model, result) {
+    const pkFields = getPrimaryKeyFields(model);
+    if (pkFields.length === 0) {
+        return null;
+    }
+    if (pkFields.length === 1) {
+        // Single primary key
+        const field = pkFields[0];
+        const value = result[field.name];
+        if (value !== undefined && value !== null) {
+            return String(value);
+        }
+        return null;
+    }
+    // Composite primary key - serialize as JSON
+    const pkValues = {};
+    for (const field of pkFields) {
+        const value = result[field.name];
+        if (value === undefined || value === null) {
+            return null;
+        }
+        pkValues[field.name] = value;
+    }
+    return JSON.stringify(pkValues);
+}
+/**
+ * Extract primary keys from query results (array or single object)
+ */
+export function extractPrimaryKeys(modelName, result) {
+    const model = getModelMeta(modelName);
+    if (!model) {
+        return [];
+    }
+    const keys = [];
+    if (Array.isArray(result)) {
+        for (const item of result) {
+            if (item && typeof item === 'object') {
+                const pk = extractPrimaryKey(model, item);
+                if (pk !== null) {
+                    keys.push(pk);
+                }
+            }
+        }
+    }
+    else if (result && typeof result === 'object') {
+        const pk = extractPrimaryKey(model, result);
+        if (pk !== null) {
+            keys.push(pk);
+        }
+    }
+    return keys;
+}
+/**
+ * Extract primary keys from a raw result, handling both model field names
+ * and database column names
+ */
+export function extractPrimaryKeysFromRaw(modelName, results) {
+    const model = getModelMeta(modelName);
+    if (!model) {
+        return [];
+    }
+    const pkFields = getPrimaryKeyFields(model);
+    if (pkFields.length === 0) {
+        return [];
+    }
+    const keys = [];
+    for (const result of results) {
+        if (pkFields.length === 1) {
+            const field = pkFields[0];
+            // Try model field name first, then db column name
+            const value = result[field.name] ?? (field.dbName ? result[field.dbName] : undefined);
+            if (value !== undefined && value !== null) {
+                keys.push(String(value));
+            }
+        }
+        else {
+            // Composite key
+            const pkValues = {};
+            let allFound = true;
+            for (const field of pkFields) {
+                const value = result[field.name] ??
+                    (field.dbName ? result[field.dbName] : undefined);
+                if (value === undefined || value === null) {
+                    allFound = false;
+                    break;
+                }
+                pkValues[field.name] = value;
+            }
+            if (allFound) {
+                keys.push(JSON.stringify(pkValues));
+            }
+        }
+    }
+    return keys;
+}
+//# sourceMappingURL=primary-key-extractor.js.map