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

package/dist/core/plan/hierarchy.js

@@ -0,0 +1,488 @@
+/**
+ * Hierarchical grouping of changes for tree display.
+ */
+import { AlterTableAddColumn, AlterTableAlterColumnDropDefault, AlterTableAlterColumnDropNotNull, AlterTableAlterColumnSetDefault, AlterTableAlterColumnSetNotNull, AlterTableAlterColumnType, AlterTableDropColumn, } from "../objects/table/changes/table.alter.js";
+import { CreateTable } from "../objects/table/changes/table.create.js";
+import { getObjectSchema, getParentInfo } from "./serialize.js";
+// ============================================================================
+// Empty Structure Factories
+// ============================================================================
+/**
+ * Create an empty ChangeGroup.
+ */
+function emptyChangeGroup() {
+    return { create: [], alter: [], drop: [] };
+}
+/**
+ * Create an empty TableChildren structure.
+ */
+function emptyTableChildren() {
+    return {
+        changes: emptyChangeGroup(),
+        columns: emptyChangeGroup(),
+        indexes: emptyChangeGroup(),
+        triggers: emptyChangeGroup(),
+        rules: emptyChangeGroup(),
+        policies: emptyChangeGroup(),
+        partitions: {},
+    };
+}
+/**
+ * Create an empty MaterializedViewChildren structure.
+ */
+function emptyMaterializedViewChildren() {
+    return {
+        changes: emptyChangeGroup(),
+        indexes: emptyChangeGroup(),
+    };
+}
+/**
+ * Create an empty TypeGroup structure.
+ */
+function emptyTypeGroup() {
+    return {
+        enums: emptyChangeGroup(),
+        composites: emptyChangeGroup(),
+        ranges: emptyChangeGroup(),
+        domains: emptyChangeGroup(),
+    };
+}
+/**
+ * Create an empty SchemaGroup structure.
+ */
+function emptySchemaGroup() {
+    return {
+        changes: emptyChangeGroup(),
+        tables: {},
+        views: {},
+        materializedViews: {},
+        functions: emptyChangeGroup(),
+        procedures: emptyChangeGroup(),
+        aggregates: emptyChangeGroup(),
+        sequences: emptyChangeGroup(),
+        types: emptyTypeGroup(),
+        collations: emptyChangeGroup(),
+        foreignTables: {},
+    };
+}
+/**
+ * Create an empty ClusterGroup structure.
+ */
+function emptyClusterGroup() {
+    return {
+        roles: emptyChangeGroup(),
+        extensions: emptyChangeGroup(),
+        eventTriggers: emptyChangeGroup(),
+        publications: emptyChangeGroup(),
+        subscriptions: emptyChangeGroup(),
+        foreignDataWrappers: emptyChangeGroup(),
+        servers: emptyChangeGroup(),
+        userMappings: emptyChangeGroup(),
+    };
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Add a change to a ChangeGroup based on its operation.
+ */
+function addToChangeGroup(group, change) {
+    group[change.operation].push({ original: change });
+}
+/**
+ * Check if a Change is a column operation (ADD/DROP/ALTER COLUMN).
+ * Uses instanceof checks for type safety.
+ */
+function isColumnOperation(change) {
+    if (change.objectType !== "table") {
+        return null;
+    }
+    if (change instanceof AlterTableAddColumn ||
+        change instanceof AlterTableDropColumn ||
+        change instanceof AlterTableAlterColumnType ||
+        change instanceof AlterTableAlterColumnSetDefault ||
+        change instanceof AlterTableAlterColumnDropDefault ||
+        change instanceof AlterTableAlterColumnSetNotNull ||
+        change instanceof AlterTableAlterColumnDropNotNull) {
+        return change.column.name;
+    }
+    return null;
+}
+/**
+ * Check if a Change creates a partition table.
+ * Returns the parent table name if it's a partition, null otherwise.
+ * Uses instanceof checks for type safety.
+ *
+ * IMPORTANT: This function should ONLY be called for table changes.
+ * Materialized views and other object types should never reach this function.
+ */
+function isPartitionTable(change) {
+    // First check: must be a table change
+    if (change.objectType !== "table") {
+        return null;
+    }
+    // Second check: must be a CreateTable change (only CreateTable can create partitions)
+    // Use instanceof to safely verify the change type
+    if (!(change instanceof CreateTable)) {
+        return null;
+    }
+    // Third check: verify the table is actually marked as a partition
+    // Both is_partition flag AND parent_name must be set
+    if (!change.table.is_partition || !change.table.parent_name) {
+        return null;
+    }
+    return change.table.parent_name;
+}
+/**
+ * Check if a table name (from an AlterTable change) is an existing partition.
+ * Checks both mainCatalog and branchCatalog to see if the table is a partition.
+ * Returns the parent table name if found, null otherwise.
+ */
+function isExistingPartition(ctx, schemaName, tableName) {
+    const tableKey = `${schemaName}.${tableName}`;
+    // Check branchCatalog first (target state - where partitions should be)
+    const branchTable = ctx.branchCatalog.tables[tableKey];
+    if (branchTable?.is_partition && branchTable.parent_name) {
+        return branchTable.parent_name;
+    }
+    // Also check mainCatalog (source state)
+    const mainTable = ctx.mainCatalog.tables[tableKey];
+    if (mainTable?.is_partition && mainTable.parent_name) {
+        return mainTable.parent_name;
+    }
+    return null;
+}
+// ============================================================================
+// Main Grouping Function
+// ============================================================================
+/**
+ * Group changes into a hierarchical structure for tree display.
+ *
+ * This function takes original Change objects (not SerializedChange) to enable
+ * detection of column operations, partitions, and other type-specific details.
+ *
+ * Organizes changes by:
+ * 1. Cluster-wide vs schema-scoped
+ * 2. Schema > Object Type > Object Name
+ * 3. Parent > Child (e.g., Table > Index, Table > Column)
+ * 4. Partitioned Table > Partition
+ */
+export function groupChangesHierarchically(ctx, changes) {
+    const result = {
+        cluster: emptyClusterGroup(),
+        schemas: {},
+    };
+    for (const change of changes) {
+        const columnName = isColumnOperation(change);
+        // Check for partitions: either creating a new partition (CreateTable) or any change on an existing partition
+        let partitionOf = null;
+        const changeSchema = getObjectSchema(change);
+        if (change.objectType === "table" && changeSchema) {
+            // First check if this is a CreateTable creating a partition
+            partitionOf = isPartitionTable(change);
+            // If not, check if this table is an existing partition (for any table change including privilege changes)
+            if (!partitionOf) {
+                partitionOf = isExistingPartition(ctx, changeSchema, change.table.name);
+            }
+        }
+        if (!changeSchema) {
+            addClusterChange(result.cluster, change);
+            continue;
+        }
+        if (!result.schemas[changeSchema]) {
+            result.schemas[changeSchema] = emptySchemaGroup();
+        }
+        const schemaGroup = result.schemas[changeSchema];
+        const parent = getParentInfo(change);
+        if (parent) {
+            addChildChange(schemaGroup, change);
+            continue;
+        }
+        addSchemaLevelChange(schemaGroup, change, {
+            columnName,
+            partitionOf,
+        });
+    }
+    return result;
+}
+// ============================================================================
+// Add Functions (exhaustive on object types)
+// ============================================================================
+/**
+ * Add a change to the cluster group (exhaustive on cluster-wide types).
+ */
+function addClusterChange(cluster, change) {
+    const objectType = change.objectType;
+    switch (objectType) {
+        case "role":
+            addToChangeGroup(cluster.roles, change);
+            break;
+        case "extension":
+            addToChangeGroup(cluster.extensions, change);
+            break;
+        case "event_trigger":
+            addToChangeGroup(cluster.eventTriggers, change);
+            break;
+        case "language":
+            // Languages are cluster-wide, but we don't have a group for them yet
+            break;
+        case "publication":
+            addToChangeGroup(cluster.publications, change);
+            break;
+        case "subscription":
+            addToChangeGroup(cluster.subscriptions, change);
+            break;
+        case "foreign_data_wrapper":
+            addToChangeGroup(cluster.foreignDataWrappers, change);
+            break;
+        case "server":
+            addToChangeGroup(cluster.servers, change);
+            break;
+        case "user_mapping":
+            addToChangeGroup(cluster.userMappings, change);
+            break;
+        case "aggregate":
+        case "collation":
+        case "composite_type":
+        case "domain":
+        case "enum":
+        case "foreign_table":
+        case "index":
+        case "materialized_view":
+        case "procedure":
+        case "range":
+        case "rls_policy":
+        case "rule":
+        case "schema":
+        case "sequence":
+        case "table":
+        case "trigger":
+        case "view":
+            // These have schemas and shouldn't be added to cluster group
+            break;
+        default: {
+            const _exhaustive = objectType;
+            throw new Error(`Unhandled object type: ${_exhaustive}`);
+        }
+    }
+}
+/**
+ * Add a child change (index, trigger, policy, rule) to its parent (exhaustive).
+ */
+function addChildChange(schema, change) {
+    const parentInfo = getParentInfo(change);
+    if (!parentInfo)
+        return;
+    const parentName = parentInfo.name;
+    const parentType = parentInfo.type;
+    let parentGroup;
+    switch (parentType) {
+        case "table":
+            if (!schema.tables[parentName]) {
+                schema.tables[parentName] = emptyTableChildren();
+            }
+            parentGroup = schema.tables[parentName];
+            break;
+        case "view":
+            if (!schema.views[parentName]) {
+                schema.views[parentName] = emptyTableChildren();
+            }
+            parentGroup = schema.views[parentName];
+            break;
+        case "materialized_view":
+            if (!schema.materializedViews[parentName]) {
+                schema.materializedViews[parentName] = emptyMaterializedViewChildren();
+            }
+            parentGroup = schema.materializedViews[parentName];
+            break;
+        case "foreign_table":
+            if (!schema.foreignTables[parentName]) {
+                schema.foreignTables[parentName] = emptyTableChildren();
+            }
+            parentGroup = schema.foreignTables[parentName];
+            break;
+        default: {
+            const _exhaustive = parentType;
+            throw new Error(`Unhandled parent type: ${_exhaustive}`);
+        }
+    }
+    const objectType = change.objectType;
+    switch (objectType) {
+        case "index":
+            addToChangeGroup(parentGroup.indexes, change);
+            break;
+        case "trigger":
+            if ("triggers" in parentGroup) {
+                addToChangeGroup(parentGroup.triggers, change);
+            }
+            break;
+        case "rule":
+            if ("rules" in parentGroup) {
+                addToChangeGroup(parentGroup.rules, change);
+            }
+            break;
+        case "rls_policy":
+            if ("policies" in parentGroup) {
+                addToChangeGroup(parentGroup.policies, change);
+            }
+            break;
+        case "aggregate":
+        case "collation":
+        case "composite_type":
+        case "domain":
+        case "enum":
+        case "event_trigger":
+        case "extension":
+        case "foreign_data_wrapper":
+        case "foreign_table":
+        case "language":
+        case "materialized_view":
+        case "procedure":
+        case "publication":
+        case "range":
+        case "role":
+        case "schema":
+        case "sequence":
+        case "server":
+        case "subscription":
+        case "table":
+        case "user_mapping":
+        case "view":
+            break;
+        default: {
+            const _exhaustive = objectType;
+            throw new Error(`Unhandled object type: ${_exhaustive}`);
+        }
+    }
+}
+/**
+ * Add a schema-level change to the appropriate group (exhaustive).
+ */
+function addSchemaLevelChange(schema, change, enrichment) {
+    const objectType = change.objectType;
+    switch (objectType) {
+        case "schema":
+            addToChangeGroup(schema.changes, change);
+            break;
+        case "table": {
+            // Verify the original change is actually a table change
+            // (safeguard against materialized views or other objects being incorrectly routed here)
+            if (change.objectType !== "table") {
+                // This shouldn't happen, but if it does, skip this change
+                // It will be handled by its correct objectType case
+                break;
+            }
+            if (enrichment.columnName) {
+                const tableName = change.table.name;
+                if (!schema.tables[tableName]) {
+                    schema.tables[tableName] = emptyTableChildren();
+                }
+                addToChangeGroup(schema.tables[tableName].columns, change);
+                break;
+            }
+            if (enrichment.partitionOf) {
+                // For CreateTable changes, verify it's actually a partition
+                if (change instanceof CreateTable) {
+                    // Additional verification: ensure the table is actually marked as a partition
+                    if (!change.table.is_partition || !change.table.parent_name) {
+                        // Table has parent_name but is_partition is false (inheritance, not partitioning)
+                        // Treat as regular table change
+                        const tableName = change.table.name;
+                        if (!schema.tables[tableName]) {
+                            schema.tables[tableName] = emptyTableChildren();
+                        }
+                        addToChangeGroup(schema.tables[tableName].changes, change);
+                        break;
+                    }
+                }
+                // For AlterTable changes on existing partitions, enrichment.partitionOf comes from catalog lookup
+                // which is already verified, so we can trust it
+                const parentName = enrichment.partitionOf;
+                if (!schema.tables[parentName]) {
+                    schema.tables[parentName] = emptyTableChildren();
+                }
+                const partitionName = change.table.name;
+                if (!schema.tables[parentName].partitions[partitionName]) {
+                    schema.tables[parentName].partitions[partitionName] =
+                        emptyTableChildren();
+                }
+                addToChangeGroup(schema.tables[parentName].partitions[partitionName].changes, change);
+                break;
+            }
+            const tableName = change.table.name;
+            if (!schema.tables[tableName]) {
+                schema.tables[tableName] = emptyTableChildren();
+            }
+            addToChangeGroup(schema.tables[tableName].changes, change);
+            break;
+        }
+        case "view": {
+            const viewName = change.view.name;
+            if (!schema.views[viewName]) {
+                schema.views[viewName] = emptyTableChildren();
+            }
+            addToChangeGroup(schema.views[viewName].changes, change);
+            break;
+        }
+        case "materialized_view": {
+            const matviewName = change.materializedView.name;
+            if (!schema.materializedViews[matviewName]) {
+                schema.materializedViews[matviewName] = emptyMaterializedViewChildren();
+            }
+            addToChangeGroup(schema.materializedViews[matviewName].changes, change);
+            break;
+        }
+        case "foreign_table": {
+            const ftName = change.foreignTable.name;
+            if (!schema.foreignTables[ftName]) {
+                schema.foreignTables[ftName] = emptyTableChildren();
+            }
+            addToChangeGroup(schema.foreignTables[ftName].changes, change);
+            break;
+        }
+        case "procedure":
+            addToChangeGroup(schema.functions, change);
+            break;
+        case "aggregate":
+            addToChangeGroup(schema.aggregates, change);
+            break;
+        case "sequence":
+            addToChangeGroup(schema.sequences, change);
+            break;
+        case "enum":
+            addToChangeGroup(schema.types.enums, change);
+            break;
+        case "composite_type":
+            addToChangeGroup(schema.types.composites, change);
+            break;
+        case "range":
+            addToChangeGroup(schema.types.ranges, change);
+            break;
+        case "domain":
+            addToChangeGroup(schema.types.domains, change);
+            break;
+        case "collation":
+            addToChangeGroup(schema.collations, change);
+            break;
+        case "extension":
+            break;
+        case "index":
+        case "trigger":
+        case "rule":
+        case "rls_policy":
+            break;
+        case "event_trigger":
+        case "foreign_data_wrapper":
+        case "language":
+        case "publication":
+        case "role":
+        case "server":
+        case "subscription":
+        case "user_mapping":
+            break;
+        default: {
+            const _exhaustive = objectType;
+            throw new Error(`Unhandled object type: ${_exhaustive}`);
+        }
+    }
+}

package/dist/core/plan/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Plan module - create and organize migration plans.
+ *
+ * @example
+ * ```ts
+ * import { createPlan, groupChangesHierarchically } from "./plan";
+ *
+ * const planResult = await createPlan(fromUrl, toUrl);
+ * if (planResult) {
+ *   const { plan, sortedChanges, ctx } = planResult;
+ *   const hierarchy = groupChangesHierarchically(ctx, sortedChanges);
+ *   console.log(plan.statements);
+ * }
+ * ```
+ */
+export { createPlan } from "./create.ts";
+export { groupChangesHierarchically } from "./hierarchy.ts";
+export { deserializePlan, serializePlan } from "./io.ts";
+export type { ChangeEntry, ChangeGroup, ChangeScope, ChildObjectType, ClusterGroup, ClusterObjectType, CreatePlanOptions, HierarchicalPlan, MaterializedViewChildren, ObjectType, ParentType, Plan, SchemaGroup, TableChildren, TypeGroup, } from "./types.ts";

package/dist/core/plan/index.js

@@ -0,0 +1,21 @@
+/**
+ * Plan module - create and organize migration plans.
+ *
+ * @example
+ * ```ts
+ * import { createPlan, groupChangesHierarchically } from "./plan";
+ *
+ * const planResult = await createPlan(fromUrl, toUrl);
+ * if (planResult) {
+ *   const { plan, sortedChanges, ctx } = planResult;
+ *   const hierarchy = groupChangesHierarchically(ctx, sortedChanges);
+ *   console.log(plan.statements);
+ * }
+ * ```
+ */
+// Plan creation
+export { createPlan } from "./create.js";
+// Hierarchical grouping
+export { groupChangesHierarchically } from "./hierarchy.js";
+// Plan I/O
+export { deserializePlan, serializePlan } from "./io.js";

package/dist/core/plan/io.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Plan I/O utilities for serializing and deserializing plans to/from JSON.
+ */
+import { type Plan } from "./types.ts";
+/**
+ * Serialize a plan to JSON string.
+ */
+export declare function serializePlan(plan: Plan): string;
+/**
+ * Deserialize a plan from JSON string.
+ */
+export declare function deserializePlan(json: string): Plan;

package/dist/core/plan/io.js

@@ -0,0 +1,17 @@
+/**
+ * Plan I/O utilities for serializing and deserializing plans to/from JSON.
+ */
+import { PlanSchema } from "./types.js";
+/**
+ * Serialize a plan to JSON string.
+ */
+export function serializePlan(plan) {
+    return JSON.stringify(plan, null, 2);
+}
+/**
+ * Deserialize a plan from JSON string.
+ */
+export function deserializePlan(json) {
+    const parsed = JSON.parse(json);
+    return PlanSchema.parse(parsed);
+}

package/dist/core/plan/risk.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Risk classification for migration plans.
+ * Identifies data-loss operations that require explicit confirmation.
+ */
+import type { Change } from "../change.types.ts";
+import type { PlanRisk } from "./types.ts";
+/**
+ * Classify all changes for data-loss risk.
+ */
+export declare function classifyChangesRisk(changes: Change[]): PlanRisk;

package/dist/core/plan/risk.js

@@ -0,0 +1,38 @@
+/**
+ * Risk classification for migration plans.
+ * Identifies data-loss operations that require explicit confirmation.
+ */
+import { DropSequence } from "../objects/sequence/changes/sequence.drop.js";
+import { AlterTableDropColumn } from "../objects/table/changes/table.alter.js";
+import { DropTable } from "../objects/table/changes/table.drop.js";
+/**
+ * Classify a single change for data-loss risk.
+ */
+function classifyChangeRisk(change) {
+    if (change instanceof DropTable) {
+        return `drop table ${change.table.schema}.${change.table.name}`;
+    }
+    if (change instanceof AlterTableDropColumn) {
+        return `drop column ${change.column.name} on ${change.table.schema}.${change.table.name}`;
+    }
+    if (change instanceof DropSequence) {
+        return `drop sequence ${change.sequence.schema}.${change.sequence.name}`;
+    }
+    // Extend here if TRUNCATE or other data-loss operations are added.
+    return null;
+}
+/**
+ * Classify all changes for data-loss risk.
+ */
+export function classifyChangesRisk(changes) {
+    const statements = [];
+    for (const change of changes) {
+        const reason = classifyChangeRisk(change);
+        if (reason)
+            statements.push(reason);
+    }
+    if (statements.length > 0) {
+        return { level: "data_loss", statements };
+    }
+    return { level: "safe" };
+}

package/dist/core/plan/serialize.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Helpers for extracting object info from Change objects.
+ */
+import type { Change } from "../change.types.ts";
+import type { ParentType } from "./types.ts";
+/**
+ * Parent info for child objects (indexes, triggers, etc.)
+ */
+type ParentInfo = {
+    type: ParentType;
+    name: string;
+};
+/**
+ * Get the object name from a change (exhaustive).
+ */
+export declare function getObjectName(change: Change): string;
+/**
+ * Get the schema from a change, or null for cluster-wide objects (exhaustive).
+ */
+export declare function getObjectSchema(change: Change): string | null;
+/**
+ * Get parent info for child objects (indexes, triggers, policies, rules).
+ * Returns null for top-level objects (exhaustive).
+ */
+export declare function getParentInfo(change: Change): ParentInfo | null;
+export {};