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

package/dist/core/expand-replace-dependencies.d.ts

@@ -0,0 +1,14 @@
+import type { Catalog } from "./catalog.model.ts";
+import type { Change } from "./change.types.ts";
+/**
+ * For objects we are replacing (drop + create), ensure that any dependents are also
+ * replaced so that destructive drops succeed. Uses dependency edges from pg_depend
+ * (already captured in Catalog.depends) plus change metadata (creates/drops/requires).
+ *
+ * New changes are appended; ordering is handled later by the sorter.
+ */
+export declare function expandReplaceDependencies({ changes, mainCatalog, branchCatalog, }: {
+    changes: Change[];
+    mainCatalog: Catalog;
+    branchCatalog: Catalog;
+}): Change[];

package/dist/core/expand-replace-dependencies.js

@@ -0,0 +1,280 @@
+import { CreateDomain } from "./objects/domain/changes/domain.create.js";
+import { DropDomain } from "./objects/domain/changes/domain.drop.js";
+import { CreateMaterializedView } from "./objects/materialized-view/changes/materialized-view.create.js";
+import { DropMaterializedView } from "./objects/materialized-view/changes/materialized-view.drop.js";
+import { CreateProcedure } from "./objects/procedure/changes/procedure.create.js";
+import { DropProcedure } from "./objects/procedure/changes/procedure.drop.js";
+import { AlterTableAddConstraint, AlterTableValidateConstraint, } from "./objects/table/changes/table.alter.js";
+import { CreateCommentOnConstraint } from "./objects/table/changes/table.comment.js";
+import { CreateTable } from "./objects/table/changes/table.create.js";
+import { DropTable } from "./objects/table/changes/table.drop.js";
+import { CreateCompositeType } from "./objects/type/composite-type/changes/composite-type.create.js";
+import { DropCompositeType } from "./objects/type/composite-type/changes/composite-type.drop.js";
+import { CreateEnum } from "./objects/type/enum/changes/enum.create.js";
+import { DropEnum } from "./objects/type/enum/changes/enum.drop.js";
+import { CreateRange } from "./objects/type/range/changes/range.create.js";
+import { DropRange } from "./objects/type/range/changes/range.drop.js";
+import { CreateView } from "./objects/view/changes/view.create.js";
+import { DropView } from "./objects/view/changes/view.drop.js";
+/**
+ * For objects we are replacing (drop + create), ensure that any dependents are also
+ * replaced so that destructive drops succeed. Uses dependency edges from pg_depend
+ * (already captured in Catalog.depends) plus change metadata (creates/drops/requires).
+ *
+ * New changes are appended; ordering is handled later by the sorter.
+ */
+export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog, }) {
+    const createdIds = new Set();
+    const droppedIds = new Set();
+    for (const change of changes) {
+        for (const id of change.creates ?? [])
+            createdIds.add(id);
+        for (const id of change.drops ?? [])
+            droppedIds.add(id);
+    }
+    const replaceRoots = new Set();
+    for (const id of createdIds) {
+        if (droppedIds.has(id)) {
+            replaceRoots.add(id);
+        }
+    }
+    if (replaceRoots.size === 0) {
+        return changes;
+    }
+    // Build referenced -> dependents adjacency from main catalog dependencies.
+    const dependentsByReferenced = new Map();
+    for (const dep of mainCatalog.depends) {
+        let list = dependentsByReferenced.get(dep.referenced_stable_id);
+        if (!list) {
+            list = new Set();
+            dependentsByReferenced.set(dep.referenced_stable_id, list);
+        }
+        list.add(dep.dependent_stable_id);
+    }
+    const additions = [];
+    const visitedTargets = new Set();
+    const visitedRefs = new Set(replaceRoots);
+    const queue = [...replaceRoots];
+    while (queue.length > 0) {
+        const refId = queue.shift();
+        const dependents = dependentsByReferenced.get(refId);
+        if (!dependents)
+            continue;
+        for (const dependentRaw of dependents) {
+            // Continue traversing the dependency graph from the raw dependent id.
+            if (!visitedRefs.has(dependentRaw)) {
+                visitedRefs.add(dependentRaw);
+                queue.push(dependentRaw);
+            }
+            const targetId = normalizeDependentId(dependentRaw);
+            if (!targetId)
+                continue;
+            // Also traverse using the normalized owning object id (e.g., table for a column).
+            if (!visitedRefs.has(targetId)) {
+                visitedRefs.add(targetId);
+                queue.push(targetId);
+            }
+            if (visitedTargets.has(targetId))
+                continue;
+            visitedTargets.add(targetId);
+            // Already handled (either original replace or previously added).
+            if (createdIds.has(targetId) && droppedIds.has(targetId))
+                continue;
+            if (replaceRoots.has(targetId))
+                continue;
+            const resolved = resolveObjectForStableId(targetId, mainCatalog, branchCatalog);
+            if (!resolved)
+                continue;
+            const hasCreate = createdIds.has(targetId);
+            const hasDrop = droppedIds.has(targetId);
+            const addDrop = !hasDrop;
+            const addCreate = !hasCreate;
+            if (!addDrop && !addCreate)
+                continue;
+            const replacementChanges = buildReplaceChanges(resolved, {
+                addDrop,
+                addCreate,
+            });
+            if (!replacementChanges)
+                continue;
+            additions.push(...replacementChanges);
+            // Track new creates/drops so we don't duplicate work for downstream dependents.
+            for (const change of replacementChanges) {
+                for (const id of change.creates ?? [])
+                    createdIds.add(id);
+                for (const id of change.drops ?? [])
+                    droppedIds.add(id);
+            }
+        }
+    }
+    if (additions.length === 0) {
+        return changes;
+    }
+    return [...changes, ...additions];
+}
+function normalizeDependentId(dependentId) {
+    let id = dependentId;
+    while (id.startsWith("comment:")) {
+        id = id.slice("comment:".length);
+    }
+    if (id.startsWith("acl:") ||
+        id.startsWith("defacl:") ||
+        id.startsWith("membership:") ||
+        id.startsWith("role:") ||
+        id.startsWith("schema:")) {
+        return null;
+    }
+    if (id.startsWith("column:")) {
+        const parts = id.slice("column:".length).split(".");
+        if (parts.length >= 2) {
+            const [schema, table] = parts;
+            return `table:${schema}.${table}`;
+        }
+        return null;
+    }
+    if (id.startsWith("constraint:")) {
+        const parts = id.slice("constraint:".length).split(".");
+        if (parts.length >= 2) {
+            const [schema, table] = parts;
+            return `table:${schema}.${table}`;
+        }
+        return null;
+    }
+    return id;
+}
+function resolveObjectForStableId(stableId, mainCatalog, branchCatalog) {
+    if (stableId.startsWith("table:")) {
+        const main = mainCatalog.tables[stableId];
+        const branch = branchCatalog.tables[stableId];
+        return main && branch ? { kind: "table", main, branch } : null;
+    }
+    if (stableId.startsWith("view:")) {
+        const main = mainCatalog.views[stableId];
+        const branch = branchCatalog.views[stableId];
+        return main && branch ? { kind: "view", main, branch } : null;
+    }
+    if (stableId.startsWith("materializedView:")) {
+        const main = mainCatalog.materializedViews[stableId];
+        const branch = branchCatalog.materializedViews[stableId];
+        return main && branch ? { kind: "materialized_view", main, branch } : null;
+    }
+    if (stableId.startsWith("procedure:")) {
+        const main = mainCatalog.procedures[stableId];
+        const branch = branchCatalog.procedures[stableId];
+        return main && branch ? { kind: "procedure", main, branch } : null;
+    }
+    if (stableId.startsWith("domain:")) {
+        const main = mainCatalog.domains[stableId];
+        const branch = branchCatalog.domains[stableId];
+        return main && branch ? { kind: "domain", main, branch } : null;
+    }
+    if (stableId.startsWith("type:")) {
+        const enumMain = mainCatalog.enums[stableId];
+        const enumBranch = branchCatalog.enums[stableId];
+        if (enumMain && enumBranch) {
+            return { kind: "enum", main: enumMain, branch: enumBranch };
+        }
+        const rangeMain = mainCatalog.ranges[stableId];
+        const rangeBranch = branchCatalog.ranges[stableId];
+        if (rangeMain && rangeBranch) {
+            return { kind: "range", main: rangeMain, branch: rangeBranch };
+        }
+        const compositeMain = mainCatalog.compositeTypes[stableId];
+        const compositeBranch = branchCatalog.compositeTypes[stableId];
+        if (compositeMain && compositeBranch) {
+            return {
+                kind: "composite_type",
+                main: compositeMain,
+                branch: compositeBranch,
+            };
+        }
+    }
+    return null;
+}
+function buildReplaceChanges(resolved, options) {
+    const { addDrop, addCreate } = options;
+    if (!addDrop && !addCreate)
+        return null;
+    switch (resolved.kind) {
+        case "table":
+            return [
+                ...(addDrop ? [new DropTable({ table: resolved.main })] : []),
+                ...(addCreate
+                    ? [
+                        new CreateTable({ table: resolved.branch }),
+                        ...(resolved.branch.constraints ?? [])
+                            .filter((c) => !c.is_partition_clone)
+                            .flatMap((constraint) => {
+                            const items = [
+                                new AlterTableAddConstraint({
+                                    table: resolved.branch,
+                                    constraint,
+                                }),
+                            ];
+                            if (!constraint.validated) {
+                                items.push(new AlterTableValidateConstraint({
+                                    table: resolved.branch,
+                                    constraint,
+                                }));
+                            }
+                            if (constraint.comment !== null &&
+                                constraint.comment !== undefined) {
+                                items.push(new CreateCommentOnConstraint({
+                                    table: resolved.branch,
+                                    constraint,
+                                }));
+                            }
+                            return items;
+                        }),
+                    ]
+                    : []),
+            ];
+        case "view":
+            return [
+                ...(addDrop ? [new DropView({ view: resolved.main })] : []),
+                ...(addCreate ? [new CreateView({ view: resolved.branch })] : []),
+            ];
+        case "materialized_view":
+            return [
+                ...(addDrop
+                    ? [new DropMaterializedView({ materializedView: resolved.main })]
+                    : []),
+                ...(addCreate
+                    ? [new CreateMaterializedView({ materializedView: resolved.branch })]
+                    : []),
+            ];
+        case "procedure":
+            return [
+                ...(addDrop ? [new DropProcedure({ procedure: resolved.main })] : []),
+                ...(addCreate
+                    ? [new CreateProcedure({ procedure: resolved.branch })]
+                    : []),
+            ];
+        case "enum":
+            return [
+                ...(addDrop ? [new DropEnum({ enum: resolved.main })] : []),
+                ...(addCreate ? [new CreateEnum({ enum: resolved.branch })] : []),
+            ];
+        case "range":
+            return [
+                ...(addDrop ? [new DropRange({ range: resolved.main })] : []),
+                ...(addCreate ? [new CreateRange({ range: resolved.branch })] : []),
+            ];
+        case "composite_type":
+            return [
+                ...(addDrop
+                    ? [new DropCompositeType({ compositeType: resolved.main })]
+                    : []),
+                ...(addCreate
+                    ? [new CreateCompositeType({ compositeType: resolved.branch })]
+                    : []),
+            ];
+        case "domain":
+            return [
+                ...(addDrop ? [new DropDomain({ domain: resolved.main })] : []),
+                ...(addCreate ? [new CreateDomain({ domain: resolved.branch })] : []),
+            ];
+        default:
+            return null;
+    }
+}

package/dist/core/fingerprint.d.ts

@@ -0,0 +1,23 @@
+import type { Catalog } from "./catalog.model.ts";
+import type { Change } from "./change.types.ts";
+/**
+ * Build a deterministic fingerprint for the objects actually touched by a plan.
+ * Uses the stableIds declared by the changes (creates/requires/drops) and snapshots
+ * only the catalog entities that exist for those stableIds (parent objects, no virtuals).
+ */
+export declare function buildPlanScopeFingerprint(catalog: Catalog, changes: Change[]): {
+    hash: string;
+    stableIds: string[];
+};
+/**
+ * Compute a fingerprint from a catalog and a set of stableIds.
+ */
+export declare function hashStableIds(catalog: Catalog, stableIds: string[]): string;
+/**
+ * Hash a string to hex SHA256.
+ */
+export declare function sha256(input: string): string;
+/**
+ * Collect the union of stableIds referenced by all changes.
+ */
+export declare function collectStableIds(changes: Change[]): string[];

package/dist/core/fingerprint.js

@@ -0,0 +1,174 @@
+import crypto from "node:crypto";
+/**
+ * Build a deterministic fingerprint for the objects actually touched by a plan.
+ * Uses the stableIds declared by the changes (creates/requires/drops) and snapshots
+ * only the catalog entities that exist for those stableIds (parent objects, no virtuals).
+ */
+export function buildPlanScopeFingerprint(catalog, changes) {
+    const stableIds = collectStableIds(changes);
+    const hash = hashStableIds(catalog, stableIds);
+    return { hash, stableIds };
+}
+/**
+ * Compute a fingerprint from a catalog and a set of stableIds.
+ */
+export function hashStableIds(catalog, stableIds) {
+    const catalogLookup = buildCatalogLookup(catalog);
+    const projection = [];
+    for (const stableId of stableIds) {
+        const record = catalogLookup[stableId];
+        if (!record) {
+            continue;
+        }
+        projection.push({
+            stableId,
+            snapshot: record.stableSnapshot(),
+        });
+    }
+    const canonical = stableStringify(projection);
+    return sha256(canonical);
+}
+/**
+ * Hash a string to hex SHA256.
+ */
+export function sha256(input) {
+    return crypto.createHash("sha256").update(input).digest("hex");
+}
+/**
+ * Collect the union of stableIds referenced by all changes.
+ */
+export function collectStableIds(changes) {
+    const ids = new Set();
+    for (const change of changes) {
+        for (const id of getChangeStableIds(change)) {
+            ids.add(id);
+        }
+    }
+    return Array.from(ids).sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Gather the stableIds a change touches (creates/requires/drops) and, when the
+ * change has a primary entity with a stableId, include it as well.
+ */
+function getChangeStableIds(change) {
+    const ids = [];
+    // Dependencies declared on the change.
+    ids.push(...change.creates, ...change.requires, ...change.drops);
+    // Best-effort primary entity stableId, when available.
+    const primary = getPrimaryStableId(change);
+    if (primary)
+        ids.push(primary);
+    return ids;
+}
+/**
+ * Extract the primary entity stableId for a change, when it exists.
+ */
+function getPrimaryStableId(change) {
+    switch (change.objectType) {
+        case "aggregate":
+            return change.aggregate.stableId;
+        case "collation":
+            return change.collation.stableId;
+        case "composite_type":
+            return change.compositeType.stableId;
+        case "domain":
+            return change.domain.stableId;
+        case "enum":
+            return change.enum.stableId;
+        case "event_trigger":
+            return change.eventTrigger.stableId;
+        case "extension":
+            return change.extension.stableId;
+        case "foreign_data_wrapper":
+            return change.foreignDataWrapper.stableId;
+        case "foreign_table":
+            return change.foreignTable.stableId;
+        case "index":
+            return change.index.stableId;
+        case "language":
+            return change.language.stableId;
+        case "materialized_view":
+            return change.materializedView.stableId;
+        case "procedure":
+            return change.procedure.stableId;
+        case "publication":
+            return change.publication.stableId;
+        case "range":
+            return change.range.stableId;
+        case "role":
+            return change.role.stableId;
+        case "schema":
+            return change.schema.stableId;
+        case "sequence":
+            return change.sequence.stableId;
+        case "server":
+            return change.server.stableId;
+        case "subscription":
+            return change.subscription.stableId;
+        case "table":
+            return change.table.stableId;
+        case "trigger":
+            return change.trigger.stableId;
+        case "rls_policy":
+            return change.policy.stableId;
+        case "rule":
+            return change.rule.stableId;
+        case "view":
+            return change.view.stableId;
+        case "user_mapping":
+            return change.userMapping.stableId;
+        default:
+            return null;
+    }
+}
+/**
+ * Build a flat lookup of catalog objects keyed by stableId.
+ */
+function buildCatalogLookup(catalog) {
+    return {
+        ...catalog.aggregates,
+        ...catalog.collations,
+        ...catalog.compositeTypes,
+        ...catalog.domains,
+        ...catalog.enums,
+        ...catalog.extensions,
+        ...catalog.procedures,
+        ...catalog.indexes,
+        ...catalog.materializedViews,
+        ...catalog.subscriptions,
+        ...catalog.publications,
+        ...catalog.rlsPolicies,
+        ...catalog.roles,
+        ...catalog.schemas,
+        ...catalog.sequences,
+        ...catalog.tables,
+        ...catalog.triggers,
+        ...catalog.eventTriggers,
+        ...catalog.rules,
+        ...catalog.ranges,
+        ...catalog.views,
+        ...catalog.foreignDataWrappers,
+        ...catalog.servers,
+        ...catalog.userMappings,
+        ...catalog.foreignTables,
+    };
+}
+/**
+ * Deterministic stringify with sorted object keys.
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        if (typeof value === "bigint") {
+            return JSON.stringify(value.toString());
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    const inner = entries
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
+        .join(",");
+    return `{${inner}}`;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @supabase/pg-delta - PostgreSQL migrations made easy
+ *
+ * This module exports the public API for the pg-delta library.
+ */
+export type { ChangeGroup, ChangeScope, ChildObjectType, ClusterGroup, ClusterObjectType, CreatePlanOptions, HierarchicalPlan, MaterializedViewChildren, ObjectType, ParentType, Plan, SchemaGroup, TableChildren, TypeGroup, } from "./plan/index.ts";
+export { createPlan, groupChangesHierarchically, } from "./plan/index.ts";
+export type { Integration } from "./integrations/integration.types.ts";
+export { diffCatalogs } from "./catalog.diff.ts";
+export { Catalog, extractCatalog } from "./catalog.model.ts";
+export type { Change } from "./change.types.ts";
+export type { DiffContext } from "./context.ts";
+export { buildPlanScopeFingerprint, collectStableIds, hashStableIds, sha256, } from "./fingerprint.ts";
+export { postgresConfig } from "./postgres-config.ts";
+export { sortChanges } from "./sort/sort-changes.ts";

package/dist/core/index.js

@@ -0,0 +1,14 @@
+/**
+ * @supabase/pg-delta - PostgreSQL migrations made easy
+ *
+ * This module exports the public API for the pg-delta library.
+ */
+export { createPlan, groupChangesHierarchically, } from "./plan/index.js";
+// =============================================================================
+// Low-level APIs (for advanced usage)
+// =============================================================================
+export { diffCatalogs } from "./catalog.diff.js";
+export { Catalog, extractCatalog } from "./catalog.model.js";
+export { buildPlanScopeFingerprint, collectStableIds, hashStableIds, sha256, } from "./fingerprint.js";
+export { postgresConfig } from "./postgres-config.js";
+export { sortChanges } from "./sort/sort-changes.js";

package/dist/core/integrations/filter/dsl.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Filter DSL - A serializable domain-specific language for change filtering.
+ */
+import type { Change } from "../../change.types.ts";
+import type { ChangeFilter } from "../../main.ts";
+/**
+ * Core properties that all changes have.
+ */
+type CoreProperties = {
+    type?: Change["objectType"];
+    operation?: "create" | "alter" | "drop";
+    scope?: Change["scope"];
+};
+/**
+ * Extracted properties that are extracted from changes via extractor functions.
+ * String value = exact match, Array value = value must be in array
+ */
+type ExtractedProperties = {
+    schema?: string | string[];
+    owner?: string | string[];
+    member?: string | string[];
+};
+/**
+ * Property pattern - matches against change properties.
+ * Multiple properties are combined with AND (all must match).
+ */
+type PropertyPattern = CoreProperties & ExtractedProperties & {
+    and?: never;
+    or?: never;
+    not?: never;
+};
+/**
+ * Composition pattern - combines other patterns using logical operators.
+ * Composition operators are exclusive - cannot be mixed with properties.
+ */
+type CompositionPattern = ({
+    and: FilterPattern[];
+    or?: never;
+    not?: never;
+} & {
+    [K in keyof CoreProperties]?: never;
+} & {
+    [K in keyof ExtractedProperties]?: never;
+}) | ({
+    or: FilterPattern[];
+    and?: never;
+    not?: never;
+} & {
+    [K in keyof CoreProperties]?: never;
+} & {
+    [K in keyof ExtractedProperties]?: never;
+}) | ({
+    not: FilterPattern;
+    and?: never;
+    or?: never;
+} & {
+    [K in keyof CoreProperties]?: never;
+} & {
+    [K in keyof ExtractedProperties]?: never;
+});
+/**
+ * Filter pattern DSL.
+ * Either a property pattern (matches against change properties) or
+ * a composition pattern (combines other patterns using logical operators).
+ * Composition operators are exclusive - cannot be mixed with properties.
+ */
+export type FilterPattern = PropertyPattern | CompositionPattern;
+/**
+ * Filter DSL - a single pattern expression.
+ */
+export type FilterDSL = FilterPattern;
+/**
+ * Evaluate a pattern against a change.
+ *
+ * @param pattern - The pattern to evaluate
+ * @param change - The change to match against
+ * @returns true if the pattern matches, false otherwise
+ */
+export declare function evaluatePattern(pattern: FilterPattern, change: Change): boolean;
+/**
+ * Compile a Filter DSL to a ChangeFilter function.
+ *
+ * @param dsl - The filter DSL pattern
+ * @returns A ChangeFilter function that evaluates the pattern
+ *
+ * @example
+ * ```ts
+ * const filter = compileFilterDSL({
+ *   or: [
+ *     { type: "schema", operation: "create" },
+ *     { schema: "public" }
+ *   ]
+ * });
+ * ```
+ */
+export declare function compileFilterDSL(dsl: FilterDSL): ChangeFilter;
+export {};