@supabase/pg-delta 1.0.0-alpha.3 → 1.0.0-alpha.30

package/src/core/sort/topological-sort.test.ts

@@ -0,0 +1,275 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "../change.types.ts";
+import {
+  findCycle,
+  formatCycleError,
+  performStableTopologicalSort,
+} from "./topological-sort.ts";
+import type { Constraint } from "./types.ts";
+
+function mockChange(name: string, creates: string[] = []): Change {
+  const change = {
+    objectType: "table",
+    operation: "create" as const,
+    scope: "object",
+    creates,
+    drops: [],
+    requires: [],
+    serialize: () => "",
+  };
+  Object.defineProperty(change, "constructor", { value: { name } });
+  return change as unknown as Change;
+}
+
+describe("performStableTopologicalSort", () => {
+  test("no edges returns identity order", () => {
+    const result = performStableTopologicalSort(3, []);
+    expect(result).toEqual([0, 1, 2]);
+  });
+
+  test("linear chain produces correct order", () => {
+    const result = performStableTopologicalSort(3, [
+      [0, 1],
+      [1, 2],
+    ]);
+    expect(result).toEqual([0, 1, 2]);
+  });
+
+  test("reversed linear chain reorders correctly", () => {
+    const result = performStableTopologicalSort(3, [
+      [2, 1],
+      [1, 0],
+    ]);
+    expect(result).toEqual([2, 1, 0]);
+  });
+
+  test("diamond dependency resolves correctly", () => {
+    const result = performStableTopologicalSort(4, [
+      [0, 1],
+      [0, 2],
+      [1, 3],
+      [2, 3],
+    ]);
+    expect(result).toEqual([0, 1, 2, 3]);
+  });
+
+  test("cycle returns null", () => {
+    const result = performStableTopologicalSort(2, [
+      [0, 1],
+      [1, 0],
+    ]);
+    expect(result).toBeNull();
+  });
+
+  test("stable ordering among unconstrained nodes", () => {
+    const result = performStableTopologicalSort(5, [[3, 4]]);
+    expect(result).toEqual([0, 1, 2, 3, 4]);
+  });
+
+  test("duplicate edges are handled", () => {
+    const result = performStableTopologicalSort(2, [
+      [0, 1],
+      [0, 1],
+    ]);
+    expect(result).toEqual([0, 1]);
+  });
+
+  test("single node returns identity", () => {
+    const result = performStableTopologicalSort(1, []);
+    expect(result).toEqual([0]);
+  });
+});
+
+describe("findCycle", () => {
+  test("no edges means no cycle", () => {
+    expect(findCycle(3, [])).toBeNull();
+  });
+
+  test("linear chain has no cycle", () => {
+    expect(
+      findCycle(3, [
+        [0, 1],
+        [1, 2],
+      ]),
+    ).toBeNull();
+  });
+
+  test("simple cycle is detected", () => {
+    const cycle = findCycle(2, [
+      [0, 1],
+      [1, 0],
+    ]);
+    expect(cycle).not.toBeNull();
+    expect(cycle?.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("three-node cycle is detected", () => {
+    const cycle = findCycle(3, [
+      [0, 1],
+      [1, 2],
+      [2, 0],
+    ]);
+    expect(cycle).not.toBeNull();
+    expect(cycle?.length).toBe(3);
+  });
+
+  test("self-loop is detected", () => {
+    const cycle = findCycle(1, [[0, 0]]);
+    expect(cycle).not.toBeNull();
+  });
+
+  test("cycle in subgraph is found", () => {
+    const cycle = findCycle(4, [
+      [0, 1],
+      [2, 3],
+      [3, 2],
+    ]);
+    expect(cycle).not.toBeNull();
+    expect(cycle).toContain(2);
+    expect(cycle).toContain(3);
+  });
+});
+
+describe("formatCycleError", () => {
+  test("basic format without cycleEdges", () => {
+    const changes = [
+      mockChange("CreateTable", ["table:public.a"]),
+      mockChange("CreateTable", ["table:public.b"]),
+    ];
+
+    const message = formatCycleError([0, 1], changes);
+    expect(message).toContain("CycleError");
+    expect(message).toContain("2 changes");
+    expect(message).toContain("CreateTable");
+    expect(message).toContain("table:public.a");
+    expect(message).toContain("table:public.b");
+    expect(message).toContain("circular dependency");
+    expect(message).not.toContain("Cycle path");
+  });
+
+  test("catalog source with dependentStableId", () => {
+    const changes = [
+      mockChange("CreateTable", ["table:public.a"]),
+      mockChange("CreateView", ["view:public.v"]),
+    ];
+
+    const constraint: Constraint = {
+      sourceChangeIndex: 0,
+      targetChangeIndex: 1,
+      source: "catalog",
+      reason: {
+        dependentStableId: "view:public.v",
+        referencedStableId: "table:public.a",
+      },
+    };
+
+    const message = formatCycleError([0, 1], changes, [
+      { sourceIndex: 0, targetIndex: 1, constraint },
+    ]);
+    expect(message).toContain("Cycle path");
+    expect(message).toContain("source: catalog");
+    expect(message).toContain("Dependency: view:public.v → table:public.a");
+    expect(message).toContain("Cycle-breaking filter did not match");
+    expect(message).toContain("cycle-breaking filters were unable");
+  });
+
+  test("explicit source without dependentStableId", () => {
+    const changes = [
+      mockChange("CreateTable"),
+      mockChange("CreateView", ["view:public.v"]),
+    ];
+
+    const constraint: Constraint = {
+      sourceChangeIndex: 0,
+      targetChangeIndex: 1,
+      source: "explicit",
+      reason: {
+        referencedStableId: "table:public.a",
+      },
+    };
+
+    const message = formatCycleError([0, 1], changes, [
+      { sourceIndex: 0, targetIndex: 1, constraint },
+    ]);
+    expect(message).toContain("source: explicit");
+    expect(message).toContain("Requires: table:public.a");
+    expect(message).toContain(
+      "Explicit requirement without created IDs (not filtered)",
+    );
+  });
+
+  test("custom source constraint", () => {
+    const changes = [
+      mockChange("CreateTable", ["table:public.a"]),
+      mockChange("CreateTable", ["table:public.b"]),
+    ];
+
+    const constraint: Constraint = {
+      sourceChangeIndex: 0,
+      targetChangeIndex: 1,
+      source: "custom",
+    };
+
+    const message = formatCycleError([0, 1], changes, [
+      { sourceIndex: 0, targetIndex: 1, constraint },
+    ]);
+    expect(message).toContain("source: custom");
+    expect(message).toContain("Custom constraint (never filtered)");
+  });
+
+  test("edge not found in cycleEdges", () => {
+    const changes = [
+      mockChange("CreateTable", ["table:public.a"]),
+      mockChange("CreateTable", ["table:public.b"]),
+      mockChange("CreateView", ["view:public.v"]),
+    ];
+
+    const unrelatedConstraint: Constraint = {
+      sourceChangeIndex: 2,
+      targetChangeIndex: 0,
+      source: "custom",
+    };
+
+    const message = formatCycleError([0, 1], changes, [
+      { sourceIndex: 2, targetIndex: 0, constraint: unrelatedConstraint },
+    ]);
+    expect(message).toContain("(edge not found)");
+  });
+
+  test("explicit source with dependentStableId uses filter message", () => {
+    const changes = [
+      mockChange("CreateTable", ["table:public.a"]),
+      mockChange("CreateView", ["view:public.v"]),
+    ];
+
+    const constraint: Constraint = {
+      sourceChangeIndex: 0,
+      targetChangeIndex: 1,
+      source: "explicit",
+      reason: {
+        dependentStableId: "view:public.v",
+        referencedStableId: "table:public.a",
+      },
+    };
+
+    const message = formatCycleError([0, 1], changes, [
+      { sourceIndex: 0, targetIndex: 1, constraint },
+    ]);
+    expect(message).toContain("Dependency: view:public.v → table:public.a");
+    expect(message).toContain("Cycle-breaking filter did not match");
+  });
+
+  test("change with many creates truncates", () => {
+    const changes = [
+      mockChange("CreateTable", [
+        "table:public.a",
+        "table:public.b",
+        "table:public.c",
+      ]),
+    ];
+
+    const message = formatCycleError([0], changes);
+    expect(message).toContain("table:public.a, table:public.b...");
+    expect(message).not.toContain("table:public.c");
+  });
+});

package/src/core/sort/topological-sort.ts

@@ -0,0 +1,184 @@
+import type { Change } from "../change.types.ts";
+import type { Constraint } from "./types.ts";
+
+/**
+ * Stable topological sort. If multiple zero-indegree nodes exist, picks the
+ * smallest original index first to preserve input order among unconstrained items.
+ * Returns null on cycles.
+ */
+export function performStableTopologicalSort(
+  nodeCount: number,
+  edges: Array<[number, number]>,
+): number[] | null {
+  const adjacencyList: Array<Set<number>> = Array.from(
+    { length: nodeCount },
+    () => new Set<number>(),
+  );
+  const inDegreeCounts: number[] = Array.from({ length: nodeCount }, () => 0);
+
+  for (const [sourceIndex, targetIndex] of edges) {
+    if (!adjacencyList[sourceIndex].has(targetIndex)) {
+      adjacencyList[sourceIndex].add(targetIndex);
+      inDegreeCounts[targetIndex]++;
+    }
+  }
+
+  const candidateQueue: number[] = [];
+  for (let nodeIndex = 0; nodeIndex < nodeCount; nodeIndex++) {
+    if (inDegreeCounts[nodeIndex] === 0) candidateQueue.push(nodeIndex);
+  }
+  candidateQueue.sort((left, right) => left - right);
+
+  const orderedNodeIndexes: number[] = [];
+  while (candidateQueue.length > 0) {
+    const nodeIndex = candidateQueue.shift() as number;
+    orderedNodeIndexes.push(nodeIndex);
+    for (const neighborIndex of adjacencyList[nodeIndex]) {
+      inDegreeCounts[neighborIndex]--;
+      if (inDegreeCounts[neighborIndex] === 0) {
+        let inserted = false;
+        for (
+          let queuePosition = 0;
+          queuePosition < candidateQueue.length;
+          queuePosition++
+        ) {
+          if (neighborIndex < candidateQueue[queuePosition]) {
+            candidateQueue.splice(queuePosition, 0, neighborIndex);
+            inserted = true;
+            break;
+          }
+        }
+        if (!inserted) candidateQueue.push(neighborIndex);
+      }
+    }
+  }
+
+  if (orderedNodeIndexes.length !== nodeCount) return null; // cycle detected
+  return orderedNodeIndexes;
+}
+
+/**
+ * Find one cycle (if any) and return its node indices in order.
+ */
+export function findCycle(
+  nodeCount: number,
+  edges: Array<[number, number]>,
+): number[] | null {
+  const adjacencyList: Array<number[]> = Array.from(
+    { length: nodeCount },
+    () => [],
+  );
+  for (const [sourceIndex, targetIndex] of edges) {
+    adjacencyList[sourceIndex].push(targetIndex);
+  }
+
+  // 0 = unvisited, 1 = visiting, 2 = completed
+  const visitState: number[] = Array.from({ length: nodeCount }, () => 0);
+  const pathStack: number[] = [];
+  let cycleNodeIndexes: number[] | null = null;
+
+  const depthFirstSearch = (nodeIndex: number) => {
+    if (cycleNodeIndexes) return;
+    visitState[nodeIndex] = 1;
+    pathStack.push(nodeIndex);
+
+    for (const neighborIndex of adjacencyList[nodeIndex]) {
+      if (visitState[neighborIndex] === 0) {
+        depthFirstSearch(neighborIndex);
+      } else if (visitState[neighborIndex] === 1) {
+        const cycleStartIndex = pathStack.lastIndexOf(neighborIndex);
+        if (cycleStartIndex !== -1) {
+          cycleNodeIndexes = pathStack.slice(cycleStartIndex);
+        }
+        return;
+      }
+      if (cycleNodeIndexes) return;
+    }
+
+    pathStack.pop();
+    visitState[nodeIndex] = 2;
+  };
+
+  for (
+    let nodeIndex = 0;
+    nodeIndex < nodeCount && !cycleNodeIndexes;
+    nodeIndex++
+  ) {
+    if (visitState[nodeIndex] === 0) depthFirstSearch(nodeIndex);
+  }
+
+  return cycleNodeIndexes;
+}
+
+/**
+ * Format a cycle error message with details about the changes involved and the edges forming the cycle.
+ */
+export function formatCycleError(
+  cycleNodeIndexes: number[],
+  phaseChanges: Change[],
+  cycleEdges?: Array<{
+    sourceIndex: number;
+    targetIndex: number;
+    constraint: Constraint;
+  }>,
+): string {
+  const cycleChanges = cycleNodeIndexes.map((idx) => phaseChanges[idx]);
+  const changeDescriptions = cycleChanges.map((change, i) => {
+    const className = change?.constructor?.name ?? "Change";
+    const creates = change.creates.slice(0, 2).join(", ");
+    return `  ${i + 1}. [${cycleNodeIndexes[i]}] ${className}${creates ? ` (creates: ${creates}${change.creates.length > 2 ? "..." : ""})` : ""}`;
+  });
+
+  let message = `CycleError: dependency graph contains a cycle involving ${cycleNodeIndexes.length} changes:\n${changeDescriptions.join("\n")}`;
+
+  // Add cycle path information if edges are provided
+  if (cycleEdges && cycleEdges.length > 0) {
+    message += `\n\nCycle path (edges forming the cycle):`;
+    for (let i = 0; i < cycleNodeIndexes.length; i++) {
+      const sourceIndex = cycleNodeIndexes[i];
+      const targetIndex = cycleNodeIndexes[(i + 1) % cycleNodeIndexes.length];
+      const edge = cycleEdges.find(
+        (e) => e.sourceIndex === sourceIndex && e.targetIndex === targetIndex,
+      );
+
+      if (edge) {
+        const constraint = edge.constraint;
+        let edgeInfo = `\n  [${sourceIndex}] → [${targetIndex}] (source: ${constraint.source})`;
+
+        if (
+          constraint.source === "catalog" ||
+          constraint.source === "explicit"
+        ) {
+          if (constraint.reason.dependentStableId) {
+            edgeInfo += `\n    Dependency: ${constraint.reason.dependentStableId} → ${constraint.reason.referencedStableId}`;
+          } else {
+            edgeInfo += `\n    Requires: ${constraint.reason.referencedStableId}`;
+          }
+        }
+
+        // Add why it wasn't filtered
+        if (constraint.source === "custom") {
+          edgeInfo += `\n    Reason: Custom constraint (never filtered)`;
+        } else if (
+          constraint.source === "explicit" &&
+          !constraint.reason.dependentStableId
+        ) {
+          edgeInfo += `\n    Reason: Explicit requirement without created IDs (not filtered)`;
+        } else {
+          edgeInfo += `\n    Reason: Cycle-breaking filter did not match (edge preserved)`;
+        }
+
+        message += edgeInfo;
+      } else {
+        message += `\n  [${sourceIndex}] → [${targetIndex}] (edge not found)`;
+      }
+    }
+  }
+
+  message += `\n\nThis usually indicates a circular dependency in the schema changes that cannot be resolved.`;
+  if (cycleEdges && cycleEdges.length > 0) {
+    message += `\nThe cycle-breaking filters were unable to break this cycle.`;
+  }
+
+  return message;
+}

package/src/core/sort/types.ts

@@ -0,0 +1,112 @@
+/**
+ * pg_depend rows that matter for ordering.
+ *
+ * These represent dependency relationships extracted from PostgreSQL's pg_depend catalog.
+ */
+export type PgDependRow = {
+  /** Object that depends on `referenced_stable_id`. */
+  dependent_stable_id: string;
+  /** Object being depended upon. */
+  referenced_stable_id: string;
+  /**
+   * Dependency type as defined in PostgreSQL's pg_depend.deptype.
+   *
+   * - "n" (normal): Ordinary dependency — if the referenced object is dropped, the dependent object is also dropped automatically.
+   * - "a" (auto): Automatically created dependency — the dependent object was created as a result of creating the referenced object,
+   *   and should be dropped automatically when the referenced object is dropped, but not otherwise treated as a strong link.
+   * - "i" (internal): Internal dependency — the dependent object is a low-level part of the referenced object.
+   */
+  deptype: "n" | "a" | "i";
+};
+
+/**
+ * Constraint representing that one change must come before another.
+ *
+ * Unified abstraction for all ordering requirements:
+ * - Catalog dependencies (from pg_depend) → Constraints
+ * - Explicit requirements (from Change.requires) → Constraints
+ * - Custom constraints (change-to-change rules) → Constraints
+ */
+export type Constraint =
+  | CatalogConstraint
+  | ExplicitConstraint
+  | CustomConstraint;
+
+/**
+ * Base constraint properties shared by all constraint types.
+ */
+interface BaseConstraint {
+  /** Index of the change that must come first */
+  sourceChangeIndex: number;
+  /** Index of the change that must come after */
+  targetChangeIndex: number;
+}
+
+/**
+ * Constraint from catalog dependencies (pg_depend).
+ * Always has both dependent and referenced stable IDs.
+ */
+interface CatalogConstraint extends BaseConstraint {
+  source: "catalog";
+  /** The stable ID dependency that led to this constraint */
+  reason: {
+    /** The stable ID that depends on referencedStableId */
+    dependentStableId: string;
+    /** The stable ID being depended upon */
+    referencedStableId: string;
+  };
+}
+
+/**
+ * Constraint from explicit requirements (Change.requires).
+ * Always has referencedStableId, but dependentStableId is optional
+ * if the change doesn't create anything.
+ */
+interface ExplicitConstraint extends BaseConstraint {
+  source: "explicit";
+  /** The stable ID dependency that led to this constraint */
+  reason: {
+    /** The stable ID that depends on referencedStableId (undefined if change doesn't create anything) */
+    dependentStableId?: string;
+    /** The stable ID being depended upon */
+    referencedStableId: string;
+  };
+}
+
+/**
+ * Constraint from custom constraint functions.
+ * No reason field since these are direct change-to-change ordering rules.
+ */
+interface CustomConstraint extends BaseConstraint {
+  source: "custom";
+  /** Optional description for debugging */
+  description?: string;
+}
+
+export interface PhaseSortOptions {
+  /** If true, invert edges so drops run in reverse dependency order. */
+  invert?: boolean;
+}
+
+/**
+ * Edge with its originating constraint for filtering purposes.
+ */
+export interface Edge {
+  sourceIndex: number;
+  targetIndex: number;
+  constraint: Constraint;
+}
+
+/**
+ * Graph data structures for converting dependencies to Constraints.
+ */
+export interface GraphData {
+  /** Maps each change index to the set of stable IDs it creates. */
+  createdStableIdSets: Array<Set<string>>;
+  /** Maps each change index to the set of stable IDs it explicitly requires. */
+  explicitRequirementSets: Array<Set<string>>;
+  /** Maps a stable ID to the set of change indices that create it. */
+  changeIndexesByCreatedId: Map<string, Set<number>>;
+  /** Maps a stable ID to the set of change indices that explicitly require it. */
+  changeIndexesByExplicitRequirementId: Map<string, Set<number>>;
+}

package/src/core/sort/unorderable-cycle-error.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { createEmptyCatalog } from "../catalog.model.ts";
+import type { Change } from "../change.types.ts";
+import { BaseChange } from "../objects/base.change.ts";
+import { sortChanges } from "./sort-changes.ts";
+import { UnorderableCycleError } from "./unorderable-cycle-error.ts";
+
+class MutualCreateChange extends BaseChange {
+  readonly operation = "create";
+  readonly objectType = "table";
+  readonly scope = "object";
+  readonly table: { schema: string; name: string };
+  private readonly dependsOn: string;
+
+  constructor(name: string, dependsOn: string) {
+    super();
+    this.table = { schema: "public", name };
+    this.dependsOn = dependsOn;
+  }
+
+  override get creates() {
+    return [`table:public.${this.table.name}`];
+  }
+
+  override get requires() {
+    return [`table:public.${this.dependsOn}`];
+  }
+
+  serialize(): string {
+    return `CREATE TABLE public.${this.table.name} ()`;
+  }
+}
+
+describe("UnorderableCycleError", () => {
+  test("sortChanges throws a typed error carrying the offending cycle", async () => {
+    const a = new MutualCreateChange("a", "b");
+    const b = new MutualCreateChange("b", "a");
+    const catalog = await createEmptyCatalog(170000, "postgres");
+
+    let thrown: unknown;
+    try {
+      sortChanges({ mainCatalog: catalog, branchCatalog: catalog }, [
+        a,
+        b,
+      ] as unknown as Change[]);
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).toBeInstanceOf(UnorderableCycleError);
+    if (!(thrown instanceof UnorderableCycleError)) {
+      throw new Error("expected UnorderableCycleError");
+    }
+    expect(thrown.name).toBe("UnorderableCycleError");
+    expect(thrown.message).toContain("CycleError");
+    expect(new Set(thrown.cycle)).toEqual(
+      new Set<Change>([a, b] as unknown as Change[]),
+    );
+  });
+});

package/src/core/sort/unorderable-cycle-error.ts

@@ -0,0 +1,23 @@
+import type { Change } from "../change.types.ts";
+
+/**
+ * Thrown by `sortChanges` when the dependency graph contains a cycle that
+ * neither weak-edge filtering nor the change-injection cycle breakers could
+ * resolve.
+ *
+ * `message` is the human-readable `formatCycleError` output (it starts with
+ * "CycleError:" for backward compatibility with log greps).
+ */
+export class UnorderableCycleError extends Error {
+  override readonly name = "UnorderableCycleError";
+  /**
+   * Changes participating in the cycle, in cycle order. Empty when the
+   * failure came from an internal guard rather than a concrete cycle.
+   */
+  readonly cycle: readonly Change[];
+
+  constructor(message: string, cycle: readonly Change[] = []) {
+    super(message);
+    this.cycle = cycle;
+  }
+}