@supabase/pg-delta 0.0.0 → 1.0.0-alpha.0

package/dist/core/sort/debug-visualization.js

@@ -0,0 +1,145 @@
+import debug from "debug";
+import { findCycle } from "./topological-sort.js";
+const debugGraph = debug("pg-delta:graph");
+/**
+ * Generate a Mermaid diagram representation of the dependency graph for debugging.
+ */
+function generateMermaidDiagram(phaseChanges, graphData, edges, requirementSets, dependenciesByReferencedId) {
+    const cycleNodeIndexes = findCycle(phaseChanges.length, edges) ?? [];
+    const mermaidLines = [];
+    mermaidLines.push("flowchart TD");
+    // Add nodes
+    for (let changeIndex = 0; changeIndex < phaseChanges.length; changeIndex++) {
+        const changeInstance = phaseChanges[changeIndex];
+        const changeClassName = changeInstance?.constructor?.name ?? "Change";
+        const truncatedCreates = Array.isArray(changeInstance.creates)
+            ? changeInstance.creates.slice(0, 3)
+            : [];
+        const nodeLabel = `${changeIndex}: ${changeClassName} ${truncatedCreates.length > 0 ? `[${truncatedCreates.join(",")}]` : ""}`.replaceAll('"', "'");
+        mermaidLines.push(`  n${changeIndex}["${nodeLabel}"]`);
+    }
+    // Add edges with descriptions
+    for (const [sourceIndex, targetIndex] of edges) {
+        const edgeDescription = describeEdge(sourceIndex, targetIndex, graphData, requirementSets, dependenciesByReferencedId).replaceAll('"', "'");
+        if (edgeDescription.length > 0) {
+            mermaidLines.push(`  n${sourceIndex} -- "${edgeDescription}" --> n${targetIndex}`);
+        }
+        else {
+            mermaidLines.push(`  n${sourceIndex} --> n${targetIndex}`);
+        }
+    }
+    // Highlight cycles if any
+    if (cycleNodeIndexes.length > 0) {
+        mermaidLines.push("  classDef cycleNode fill:#ffe6e6,stroke:#ff4d4f,stroke-width:2px;");
+        for (const nodeIndex of cycleNodeIndexes) {
+            mermaidLines.push(`  class n${nodeIndex} cycleNode;`);
+        }
+        const cycleEdges = [];
+        for (let cycleIndex = 0; cycleIndex < cycleNodeIndexes.length; cycleIndex++) {
+            const sourceIndex = cycleNodeIndexes[cycleIndex];
+            const targetIndex = cycleNodeIndexes[(cycleIndex + 1) % cycleNodeIndexes.length];
+            cycleEdges.push([sourceIndex, targetIndex]);
+        }
+        let edgeIndex = 0;
+        for (const [sourceIndex, targetIndex] of edges) {
+            const edgeBelongsToCycle = cycleEdges.some(([cycleSourceIndex, cycleTargetIndex]) => cycleSourceIndex === sourceIndex && cycleTargetIndex === targetIndex);
+            if (edgeBelongsToCycle) {
+                mermaidLines.push(`  linkStyle ${edgeIndex} stroke:#ff4d4f,stroke-width:2px;`);
+            }
+            edgeIndex++;
+        }
+    }
+    return mermaidLines.join("\n");
+}
+/**
+ * Build requirementSets from explicit requirements and constraints (for debug visualization).
+ *
+ * This reconstructs what requirements were inferred from constraints by looking at
+ * the constraints that were processed. Only processes catalog/explicit constraints,
+ * as custom constraints don't affect requirement sets.
+ */
+function buildRequirementSets(explicitRequirementSets, constraints, changeIndexesByCreatedId, _changeIndexesByExplicitRequirementId) {
+    // Start with explicit requirements
+    const requirementSets = explicitRequirementSets.map((explicitRequirements) => new Set(explicitRequirements));
+    // Add requirements inferred from catalog/explicit constraints
+    // For each constraint with a reason, if the referenced ID is created by some change,
+    // then the target change requires the referenced ID
+    for (const constraint of constraints) {
+        // Only process catalog/explicit constraints (custom constraints don't affect requirements)
+        if (constraint.source === "custom" || !constraint.reason)
+            continue;
+        const referencedProducers = changeIndexesByCreatedId.get(constraint.reason.referencedStableId);
+        if (!referencedProducers || referencedProducers.size === 0)
+            continue;
+        // The target change requires the referenced stable ID
+        requirementSets[constraint.targetChangeIndex].add(constraint.reason.referencedStableId);
+    }
+    return requirementSets;
+}
+/**
+ * Build dependenciesByReferencedId from dependency rows (for debug visualization).
+ */
+function buildDependenciesByReferencedId(dependencyRows) {
+    const dependenciesByReferencedId = new Map();
+    for (const dependencyRow of dependencyRows) {
+        // Filter out unknown dependencies
+        if (dependencyRow.referenced_stable_id.startsWith("unknown:") ||
+            dependencyRow.dependent_stable_id.startsWith("unknown:")) {
+            continue;
+        }
+        let dependentIds = dependenciesByReferencedId.get(dependencyRow.referenced_stable_id);
+        if (!dependentIds) {
+            dependentIds = new Set();
+            dependenciesByReferencedId.set(dependencyRow.referenced_stable_id, dependentIds);
+        }
+        dependentIds.add(dependencyRow.dependent_stable_id);
+    }
+    return dependenciesByReferencedId;
+}
+/**
+ * Describe an edge in the dependency graph for visualization.
+ */
+function describeEdge(sourceIndex, targetIndex, graphData, requirementSets, dependenciesByReferencedId) {
+    // Check if target explicitly requires something created by source
+    for (const createdId of graphData.createdStableIdSets[sourceIndex]) {
+        if (requirementSets[targetIndex].has(createdId)) {
+            return `${createdId} -> (requires)`;
+        }
+    }
+    // Check pg_depend relationships
+    for (const createdId of graphData.createdStableIdSets[sourceIndex]) {
+        const outgoingDependencies = dependenciesByReferencedId.get(createdId);
+        if (!outgoingDependencies)
+            continue;
+        // Check if target requires this ID
+        for (const requiredId of requirementSets[targetIndex]) {
+            if (outgoingDependencies.has(requiredId)) {
+                return `${createdId} -> ${requiredId}`;
+            }
+        }
+        // Check if target creates something that depends on this ID
+        for (const targetCreatedId of graphData.createdStableIdSets[targetIndex]) {
+            if (outgoingDependencies.has(targetCreatedId)) {
+                return `${createdId} -> ${targetCreatedId}`;
+            }
+        }
+    }
+    return "";
+}
+/**
+ * Print debug information about the dependency graph.
+ *
+ * Builds debug-only data structures (requirementSets, dependenciesByReferencedId) just-in-time.
+ */
+export function printDebugGraph(phaseChanges, graphData, edges, dependencyRows, constraints) {
+    try {
+        // Build debug-only data structures just-in-time
+        const requirementSets = buildRequirementSets(graphData.explicitRequirementSets, constraints, graphData.changeIndexesByCreatedId, graphData.changeIndexesByExplicitRequirementId);
+        const dependenciesByReferencedId = buildDependenciesByReferencedId(dependencyRows);
+        const mermaidDiagram = generateMermaidDiagram(phaseChanges, graphData, edges, requirementSets, dependenciesByReferencedId);
+        debugGraph("\n==== Mermaid (cycle detected) ====\n%s\n==== end ====", mermaidDiagram);
+    }
+    catch (_error) {
+        // ignore debug printing errors
+    }
+}

package/dist/core/sort/dependency-filter.d.ts

@@ -0,0 +1,19 @@
+import type { Change } from "../change.types.ts";
+import type { Edge, GraphData } from "./types.ts";
+/**
+ * Identify edges that are part of a cycle.
+ *
+ * Given cycle node indices, returns edges where both source and target are in the cycle
+ * and form consecutive nodes in the cycle path.
+ */
+export declare function getEdgesInCycle(cycleNodeIndexes: number[], edges: Edge[]): Edge[];
+/**
+ * Filter edges involved in cycles based on their constraint's cycle-breaking rules.
+ *
+ * This is applied when cycles are detected to break them by removing problematic edges.
+ * Only filters edges that:
+ * 1. Are part of the detected cycle(s)
+ * 2. Have a reason (stable ID dependency) - custom constraints are never filtered
+ * 3. Match the cycle-breaking filter criteria
+ */
+export declare function filterEdgesForCycleBreaking(edges: Edge[], cycleNodeIndexes: number[], phaseChanges: Change[], graphData: GraphData): Edge[];

package/dist/core/sort/dependency-filter.js

@@ -0,0 +1,152 @@
+import { CreateSequence } from "../objects/sequence/changes/sequence.create.js";
+import { stableId } from "../objects/utils.js";
+import { findConsumerIndexes } from "./graph-utils.js";
+/**
+ * Check if a sequence is owned by a given column.
+ *
+ * @param sequence - The sequence object with ownership information
+ * @param referencedStableId - The column stable ID to check against
+ * @returns true if the sequence is owned by the referenced column
+ */
+function isSequenceOwnedBy(sequence, referencedStableId) {
+    if (!sequence.owned_by_schema ||
+        !sequence.owned_by_table ||
+        !sequence.owned_by_column) {
+        return false;
+    }
+    const ownedByColumnId = stableId.column(sequence.owned_by_schema, sequence.owned_by_table, sequence.owned_by_column);
+    return referencedStableId === ownedByColumnId;
+}
+/**
+ * Check if a sequence ownership dependency should be filtered to prevent cycles.
+ *
+ * CYCLE SCENARIO:
+ * When a sequence is owned by a table column that also uses the sequence (via DEFAULT),
+ * PostgreSQL's pg_depend creates a bidirectional dependency cycle:
+ *   1. column → sequence (column default depends on sequence)
+ *   2. sequence → column (sequence ownership depends on column)
+ *
+ * This creates: sequence → column → sequence (cycle!)
+ *
+ * HOW WE BREAK THE CYCLE:
+ * We filter out the ownership dependency edge (sequence → column) because:
+ *   - CREATE phase: Sequences should be created before tables. Ownership is set later
+ *     via ALTER SEQUENCE OWNED BY after both the sequence and table exist.
+ *   - DROP phase: Prevents cycles when dropping sequences owned by tables that
+ *     aren't being dropped.
+ *
+ * PARAMETERS:
+ * @param dependentStableId - The sequence stable ID (e.g., "sequence:schema.seq_name")
+ * @param referencedStableId - The column stable ID (e.g., "column:schema.table.col")
+ *   Note: PostgreSQL's pg_depend creates sequence ownership dependencies on columns (not tables)
+ *   when refobjsubid > 0, so we only check for column dependencies
+ * @param phaseChanges - All changes in the current phase
+ * @param graphData - Graph data structures for looking up changes
+ * @returns true if this ownership dependency should be filtered (removed) to break the cycle
+ */
+function shouldFilterSequenceOwnershipDependency(dependentStableId, referencedStableId, phaseChanges, graphData) {
+    // Early exit: only filter edges FROM sequences TO columns
+    // Note: PostgreSQL's pg_depend creates sequence ownership dependencies on columns (not tables)
+    // when refobjsubid > 0, so we only need to check for column dependencies
+    if (!dependentStableId.startsWith("sequence:") ||
+        !referencedStableId.startsWith("column:")) {
+        return false;
+    }
+    // Find all changes that create or consume this sequence
+    // (includes the CreateSequence change that creates it)
+    const changesInvolvingSequence = findConsumerIndexes(dependentStableId, graphData.changeIndexesByCreatedId, graphData.changeIndexesByExplicitRequirementId);
+    // Check if any CreateSequence change creates a sequence that is owned by
+    // the referenced table/column. If so, filter this ownership dependency edge.
+    for (const changeIndex of changesInvolvingSequence) {
+        const change = phaseChanges[changeIndex];
+        // Only filter edges from CreateSequence changes, not AlterSequenceSetOwnedBy.
+        // AlterSequenceSetOwnedBy is a separate change that sets ownership after
+        // both the sequence and table exist, so it doesn't create the cycle.
+        if (!(change instanceof CreateSequence)) {
+            continue;
+        }
+        // Check if this CreateSequence creates a sequence owned by the referenced table/column
+        if (isSequenceOwnedBy(change.sequence, referencedStableId)) {
+            return true; // Filter this edge to break the cycle
+        }
+    }
+    return false; // Don't filter - this is not a cycle-causing ownership dependency
+}
+/**
+ * Cycle-breaking filters for stable ID dependencies.
+ *
+ * Prevents cycles that would occur due to special PostgreSQL behaviors.
+ * Delegates to specific filter functions for each type of cycle.
+ *
+ * @param dependentStableId - The dependent object's stable ID
+ * @param referencedStableId - The referenced object's stable ID
+ * @param phaseChanges - All changes in the current phase
+ * @param graphData - Graph data structures for looking up changes
+ * @returns true if this dependency edge should be filtered (removed) to break a cycle
+ */
+function shouldFilterStableIdDependencyForCycleBreaking(dependentStableId, referencedStableId, phaseChanges, graphData) {
+    // Filter sequence ownership dependencies that create cycles with column defaults
+    if (shouldFilterSequenceOwnershipDependency(dependentStableId, referencedStableId, phaseChanges, graphData)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Identify edges that are part of a cycle.
+ *
+ * Given cycle node indices, returns edges where both source and target are in the cycle
+ * and form consecutive nodes in the cycle path.
+ */
+export function getEdgesInCycle(cycleNodeIndexes, edges) {
+    const cycleEdges = [];
+    // Create a map of edges for quick lookup
+    const edgeMap = new Map();
+    for (const edge of edges) {
+        const key = `${edge.sourceIndex}->${edge.targetIndex}`;
+        edgeMap.set(key, edge);
+    }
+    // Find edges that connect consecutive nodes in the cycle
+    for (let i = 0; i < cycleNodeIndexes.length; i++) {
+        const sourceIndex = cycleNodeIndexes[i];
+        const targetIndex = cycleNodeIndexes[(i + 1) % cycleNodeIndexes.length];
+        const key = `${sourceIndex}->${targetIndex}`;
+        const edge = edgeMap.get(key);
+        if (edge) {
+            cycleEdges.push(edge);
+        }
+    }
+    return cycleEdges;
+}
+/**
+ * Filter edges involved in cycles based on their constraint's cycle-breaking rules.
+ *
+ * This is applied when cycles are detected to break them by removing problematic edges.
+ * Only filters edges that:
+ * 1. Are part of the detected cycle(s)
+ * 2. Have a reason (stable ID dependency) - custom constraints are never filtered
+ * 3. Match the cycle-breaking filter criteria
+ */
+export function filterEdgesForCycleBreaking(edges, cycleNodeIndexes, phaseChanges, graphData) {
+    // Get edges that are part of the cycle
+    const cycleEdges = getEdgesInCycle(cycleNodeIndexes, edges);
+    // Use string keys for comparison since Set.has() uses reference equality
+    const cycleEdgeKeys = new Set(cycleEdges.map((e) => `${e.sourceIndex}->${e.targetIndex}`));
+    return edges.filter((edge) => {
+        const edgeKey = `${edge.sourceIndex}->${edge.targetIndex}`;
+        // If edge is not in the cycle, keep it
+        if (!cycleEdgeKeys.has(edgeKey)) {
+            return true;
+        }
+        // Edge is in cycle - check if it should be filtered
+        const constraint = edge.constraint;
+        // Custom constraints are never filtered
+        if (constraint.source === "custom")
+            return true;
+        const { dependentStableId, referencedStableId } = constraint.reason;
+        // Skip if dependentStableId is undefined (explicit requirement without created IDs)
+        if (!dependentStableId)
+            return true;
+        // Apply cycle-breaking filters - return false to filter out this edge
+        return !shouldFilterStableIdDependencyForCycleBreaking(dependentStableId, referencedStableId, phaseChanges, graphData);
+    });
+}

package/dist/core/sort/graph-builder.d.ts

@@ -0,0 +1,37 @@
+import type { Change } from "../change.types.ts";
+import type { Constraint, Edge, GraphData, PgDependRow, PhaseSortOptions } from "./types.ts";
+/**
+ * Convert catalog dependencies to Constraints.
+ *
+ * For each catalog dependency (stable ID → stable ID), finds the changes that
+ * create/require those stable IDs and creates Constraints between them.
+ *
+ * Filters out unknown stable IDs (basic validation).
+ * Cycle-breaking filters are applied later when detecting cycles.
+ */
+export declare function convertCatalogDependenciesToConstraints(dependencyRows: PgDependRow[], graphData: GraphData): Constraint[];
+/**
+ * Convert explicit requirements to Constraints.
+ *
+ * For each change that explicitly requires something:
+ * - If the change creates stable IDs, creates Constraints from producers of required IDs to this change
+ * - If the change doesn't create anything but requires something, creates Constraints from producers to this change
+ *
+ * Cycle-breaking filters are applied later when detecting cycles.
+ */
+export declare function convertExplicitRequirementsToConstraints(phaseChanges: Change[], graphData: GraphData): Constraint[];
+/**
+ * Build graph data structures from phase changes.
+ *
+ * Creates change sets and reverse indexes needed for converting dependencies to Constraints.
+ * In DROP phase (invert=true), dropped IDs are included in createdStableIdSets.
+ */
+export declare function buildGraphData(phaseChanges: Change[], options: PhaseSortOptions): GraphData;
+/**
+ * Convert Constraints to edges.
+ */
+export declare function convertConstraintsToEdges(constraints: Constraint[], options: PhaseSortOptions): Edge[];
+/**
+ * Convert edges to simple edge pairs for cycle detection and sorting.
+ */
+export declare function edgesToPairs(edges: Edge[]): Array<[number, number]>;

package/dist/core/sort/graph-builder.js

@@ -0,0 +1,172 @@
+import { findConsumerIndexes } from "./graph-utils.js";
+/**
+ * Convert catalog dependencies to Constraints.
+ *
+ * For each catalog dependency (stable ID → stable ID), finds the changes that
+ * create/require those stable IDs and creates Constraints between them.
+ *
+ * Filters out unknown stable IDs (basic validation).
+ * Cycle-breaking filters are applied later when detecting cycles.
+ */
+export function convertCatalogDependenciesToConstraints(dependencyRows, graphData) {
+    const constraints = [];
+    for (const row of dependencyRows) {
+        // Filter out unknown stable IDs (basic validation)
+        if (row.referenced_stable_id.startsWith("unknown:") ||
+            row.dependent_stable_id.startsWith("unknown:")) {
+            continue;
+        }
+        const producerIndexes = graphData.changeIndexesByCreatedId.get(row.referenced_stable_id);
+        if (!producerIndexes || producerIndexes.size === 0)
+            continue;
+        const consumerIndexes = findConsumerIndexes(row.dependent_stable_id, graphData.changeIndexesByCreatedId, graphData.changeIndexesByExplicitRequirementId);
+        if (consumerIndexes.size === 0)
+            continue;
+        for (const producerIndex of producerIndexes) {
+            for (const consumerIndex of consumerIndexes) {
+                if (producerIndex === consumerIndex)
+                    continue;
+                constraints.push({
+                    sourceChangeIndex: producerIndex,
+                    targetChangeIndex: consumerIndex,
+                    source: "catalog",
+                    reason: {
+                        dependentStableId: row.dependent_stable_id,
+                        referencedStableId: row.referenced_stable_id,
+                    },
+                });
+            }
+        }
+    }
+    return constraints;
+}
+/**
+ * Convert explicit requirements to Constraints.
+ *
+ * For each change that explicitly requires something:
+ * - If the change creates stable IDs, creates Constraints from producers of required IDs to this change
+ * - If the change doesn't create anything but requires something, creates Constraints from producers to this change
+ *
+ * Cycle-breaking filters are applied later when detecting cycles.
+ */
+export function convertExplicitRequirementsToConstraints(phaseChanges, graphData) {
+    const constraints = [];
+    for (let consumerIndex = 0; consumerIndex < phaseChanges.length; consumerIndex++) {
+        const createdIds = graphData.createdStableIdSets[consumerIndex];
+        const requiredIds = graphData.explicitRequirementSets[consumerIndex];
+        if (requiredIds.size === 0)
+            continue;
+        for (const requiredId of requiredIds) {
+            const producerIndexes = graphData.changeIndexesByCreatedId.get(requiredId);
+            if (!producerIndexes || producerIndexes.size === 0)
+                continue;
+            if (createdIds.size > 0) {
+                for (const createdId of createdIds) {
+                    for (const producerIndex of producerIndexes) {
+                        if (producerIndex === consumerIndex)
+                            continue;
+                        constraints.push({
+                            sourceChangeIndex: producerIndex,
+                            targetChangeIndex: consumerIndex,
+                            source: "explicit",
+                            reason: {
+                                dependentStableId: createdId,
+                                referencedStableId: requiredId,
+                            },
+                        });
+                    }
+                }
+            }
+            else {
+                // Change doesn't create anything but requires something
+                for (const producerIndex of producerIndexes) {
+                    if (producerIndex === consumerIndex)
+                        continue;
+                    constraints.push({
+                        sourceChangeIndex: producerIndex,
+                        targetChangeIndex: consumerIndex,
+                        source: "explicit",
+                        reason: {
+                            referencedStableId: requiredId,
+                        },
+                    });
+                }
+            }
+        }
+    }
+    return constraints;
+}
+/**
+ * Build graph data structures from phase changes.
+ *
+ * Creates change sets and reverse indexes needed for converting dependencies to Constraints.
+ * In DROP phase (invert=true), dropped IDs are included in createdStableIdSets.
+ */
+export function buildGraphData(phaseChanges, options) {
+    const createdStableIdSets = phaseChanges.map((changeItem) => {
+        const createdIds = new Set(changeItem.creates);
+        if (options.invert) {
+            for (const droppedId of changeItem.drops ?? []) {
+                createdIds.add(droppedId);
+            }
+        }
+        return createdIds;
+    });
+    const explicitRequirementSets = phaseChanges.map((changeItem) => new Set(changeItem.requires ?? []));
+    const changeIndexesByCreatedId = new Map();
+    for (let changeIndex = 0; changeIndex < phaseChanges.length; changeIndex++) {
+        for (const createdId of createdStableIdSets[changeIndex]) {
+            let producerIndexes = changeIndexesByCreatedId.get(createdId);
+            if (!producerIndexes) {
+                producerIndexes = new Set();
+                changeIndexesByCreatedId.set(createdId, producerIndexes);
+            }
+            producerIndexes.add(changeIndex);
+        }
+    }
+    const changeIndexesByExplicitRequirementId = new Map();
+    for (let changeIndex = 0; changeIndex < explicitRequirementSets.length; changeIndex++) {
+        for (const requiredId of explicitRequirementSets[changeIndex]) {
+            let consumerIndexes = changeIndexesByExplicitRequirementId.get(requiredId);
+            if (!consumerIndexes) {
+                consumerIndexes = new Set();
+                changeIndexesByExplicitRequirementId.set(requiredId, consumerIndexes);
+            }
+            consumerIndexes.add(changeIndex);
+        }
+    }
+    return {
+        createdStableIdSets,
+        explicitRequirementSets,
+        changeIndexesByCreatedId,
+        changeIndexesByExplicitRequirementId,
+    };
+}
+/**
+ * Convert Constraints to edges.
+ */
+export function convertConstraintsToEdges(constraints, options) {
+    const edges = [];
+    for (const constraint of constraints) {
+        if (constraint.sourceChangeIndex === constraint.targetChangeIndex)
+            continue;
+        const sourceIndex = options.invert
+            ? constraint.targetChangeIndex
+            : constraint.sourceChangeIndex;
+        const targetIndex = options.invert
+            ? constraint.sourceChangeIndex
+            : constraint.targetChangeIndex;
+        edges.push({
+            sourceIndex,
+            targetIndex,
+            constraint,
+        });
+    }
+    return edges;
+}
+/**
+ * Convert edges to simple edge pairs for cycle detection and sorting.
+ */
+export function edgesToPairs(edges) {
+    return edges.map((edge) => [edge.sourceIndex, edge.targetIndex]);
+}

package/dist/core/sort/graph-utils.d.ts

@@ -0,0 +1,14 @@
+import type { Edge } from "./types.ts";
+/**
+ * Find all change indices that could be consumers for a given dependent stable ID.
+ *
+ * A consumer is either:
+ * 1. A change that explicitly requires the dependent ID, OR
+ * 2. A change that creates the dependent ID (since creating something implies
+ *    it depends on its own dependencies)
+ */
+export declare function findConsumerIndexes(dependentStableId: string, changeIndexesByCreatedId: Map<string, Set<number>>, changeIndexesByExplicitRequirementId: Map<string, Set<number>>): Set<number>;
+/**
+ * Deduplicate edges, keeping the first occurrence.
+ */
+export declare function dedupeEdges(edges: Edge[]): Edge[];

package/dist/core/sort/graph-utils.js

@@ -0,0 +1,41 @@
+/**
+ * Find all change indices that could be consumers for a given dependent stable ID.
+ *
+ * A consumer is either:
+ * 1. A change that explicitly requires the dependent ID, OR
+ * 2. A change that creates the dependent ID (since creating something implies
+ *    it depends on its own dependencies)
+ */
+export function findConsumerIndexes(dependentStableId, changeIndexesByCreatedId, changeIndexesByExplicitRequirementId) {
+    const consumerIndexes = new Set();
+    // Add changes that explicitly require this ID
+    const explicitConsumerIndexes = changeIndexesByExplicitRequirementId.get(dependentStableId);
+    if (explicitConsumerIndexes) {
+        for (const consumerIndex of explicitConsumerIndexes) {
+            consumerIndexes.add(consumerIndex);
+        }
+    }
+    // Add changes that create this ID (they are consumers of dependencies)
+    const dependentProducers = changeIndexesByCreatedId.get(dependentStableId);
+    if (dependentProducers) {
+        for (const producerIndex of dependentProducers) {
+            consumerIndexes.add(producerIndex);
+        }
+    }
+    return consumerIndexes;
+}
+/**
+ * Deduplicate edges, keeping the first occurrence.
+ */
+export function dedupeEdges(edges) {
+    const seenEdges = new Set();
+    const uniqueEdges = [];
+    for (const edge of edges) {
+        const edgeKey = `${edge.sourceIndex}->${edge.targetIndex}`;
+        if (seenEdges.has(edgeKey))
+            continue;
+        seenEdges.add(edgeKey);
+        uniqueEdges.push(edge);
+    }
+    return uniqueEdges;
+}

package/dist/core/sort/logical-sort.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Logical pre-sorting for migration scripts.
+ *
+ * Groups changes by object type, stable ID, and scope to create a readable,
+ * logically organized migration script before dependency resolution.
+ *
+ * This is a pre-sorting step that runs before the dependency-based topological sort.
+ * It groups related changes together while preserving the ability for the dependency
+ * resolver to reorder within groups when necessary.
+ */
+import type { Change } from "../change.types.ts";
+/**
+ * Logically pre-sort changes by grouping them into a readable structure.
+ *
+ * Groups changes by:
+ * 1. Phase (DROP vs CREATE/ALTER)
+ * 2. Object type (schema, table, index, etc.)
+ * 3. Main stable ID (table:public.users, etc.)
+ * 4. Scope (object, comment, privilege, etc.)
+ *
+ * Within each group, preserves the original order (stability).
+ *
+ * @param changes - Array of changes to sort
+ * @returns Logically grouped and sorted array of changes
+ */
+export declare function logicalSort(changes: Change[]): Change[];