@supabase/pg-delta 1.0.0-alpha.4 → 1.0.0-alpha.6

package/dist/core/export/file-mapper.js

@@ -0,0 +1,474 @@
+/**
+ * Map changes to declarative schema file paths.
+ */
+import createDebug from "debug";
+import { getObjectName, getObjectSchema, getParentInfo, } from "../plan/serialize.js";
+const debugExport = createDebug("pg-delta:export");
+function isRoleDefaultPrivilegeChange(change) {
+    return (change.objectType === "role" &&
+        change.scope === "default_privilege" &&
+        "inSchema" in change);
+}
+function requireSchema(change) {
+    const schema = getObjectSchema(change);
+    if (!schema) {
+        throw new Error(`Expected schema for ${change.objectType} change '${getObjectName(change)}' (operation: ${change.operation})`);
+    }
+    return schema;
+}
+function schemaPath(schema, ...parts) {
+    return `schemas/${schema}/${parts.join("/")}`;
+}
+// ============================================================================
+// File Path Mapping
+// ============================================================================
+export function getFilePath(change) {
+    switch (change.objectType) {
+        case "role":
+            if (isRoleDefaultPrivilegeChange(change) && change.inSchema) {
+                const schemaName = change.inSchema;
+                return {
+                    path: schemaPath(schemaName, "schema.sql"),
+                    category: "schema",
+                    metadata: {
+                        objectType: "default_privilege",
+                        schemaName,
+                        objectName: schemaName,
+                    },
+                };
+            }
+            return {
+                path: "cluster/roles.sql",
+                category: "cluster",
+                metadata: { objectType: "role" },
+            };
+        case "extension": {
+            const extensionName = getObjectName(change);
+            return {
+                path: `cluster/extensions/${extensionName}.sql`,
+                category: "extensions",
+                metadata: { objectType: "extension", objectName: extensionName },
+            };
+        }
+        case "foreign_data_wrapper":
+        case "server":
+        case "user_mapping":
+            return {
+                path: "cluster/foreign_data_wrappers.sql",
+                category: "cluster",
+                metadata: { objectType: change.objectType },
+            };
+        case "publication":
+            return {
+                path: "cluster/publications.sql",
+                category: "cluster",
+                metadata: { objectType: "publication" },
+            };
+        case "subscription":
+            return {
+                path: "cluster/subscriptions.sql",
+                category: "cluster",
+                metadata: { objectType: "subscription" },
+            };
+        case "event_trigger":
+            return {
+                path: "cluster/event_triggers.sql",
+                category: "cluster",
+                metadata: { objectType: "event_trigger" },
+            };
+        case "language":
+            return {
+                path: "cluster/languages.sql",
+                category: "cluster",
+                metadata: { objectType: "language" },
+            };
+        case "schema": {
+            const schemaName = change.schema.name;
+            return {
+                path: schemaPath(schemaName, "schema.sql"),
+                category: "schema",
+                metadata: {
+                    objectType: "schema",
+                    schemaName,
+                    objectName: schemaName,
+                },
+            };
+        }
+        case "enum":
+        case "composite_type":
+        case "range": {
+            const schema = requireSchema(change);
+            const objectName = getObjectName(change);
+            return {
+                path: schemaPath(schema, "types", `${objectName}.sql`),
+                category: "types",
+                metadata: {
+                    objectType: change.objectType,
+                    schemaName: schema,
+                    objectName,
+                },
+            };
+        }
+        case "domain": {
+            const schema = requireSchema(change);
+            const objectName = getObjectName(change);
+            return {
+                path: schemaPath(schema, "domains", `${objectName}.sql`),
+                category: "domains",
+                metadata: {
+                    objectType: "domain",
+                    schemaName: schema,
+                    objectName,
+                },
+            };
+        }
+        case "collation": {
+            const schema = requireSchema(change);
+            const objectName = getObjectName(change);
+            return {
+                path: schemaPath(schema, "collations", `${objectName}.sql`),
+                category: "collations",
+                metadata: {
+                    objectType: "collation",
+                    schemaName: schema,
+                    objectName,
+                },
+            };
+        }
+        case "sequence": {
+            const schema = requireSchema(change);
+            const objectName = getObjectName(change);
+            // ALTER SEQUENCE ... OWNED BY must be grouped with the owning table,
+            // not the sequence file, to avoid ordering issues: the table must exist
+            // before the OWNED BY clause can reference its column.
+            if (change.operation === "alter" &&
+                "ownedBy" in change &&
+                change.ownedBy) {
+                const ownedBy = change.ownedBy;
+                return {
+                    path: schemaPath(ownedBy.schema, "tables", `${ownedBy.table}.sql`),
+                    category: "tables",
+                    metadata: {
+                        objectType: "table",
+                        schemaName: ownedBy.schema,
+                        objectName: ownedBy.table,
+                    },
+                };
+            }
+            return {
+                path: schemaPath(schema, "sequences", `${objectName}.sql`),
+                category: "sequences",
+                metadata: {
+                    objectType: "sequence",
+                    schemaName: schema,
+                    objectName,
+                },
+            };
+        }
+        case "table": {
+            const schema = change.table.schema;
+            const tableName = change.table.name;
+            // Partitions always go in the same file as their parent table.
+            if (change.table.is_partition && change.table.parent_name) {
+                const parentSchema = change.table.parent_schema ?? change.table.schema;
+                return {
+                    path: schemaPath(parentSchema, "tables", `${change.table.parent_name}.sql`),
+                    category: "tables",
+                    metadata: {
+                        objectType: "table",
+                        schemaName: parentSchema,
+                        objectName: change.table.parent_name,
+                    },
+                };
+            }
+            return {
+                path: schemaPath(schema, "tables", `${tableName}.sql`),
+                category: "tables",
+                metadata: {
+                    objectType: "table",
+                    schemaName: schema,
+                    objectName: tableName,
+                },
+            };
+        }
+        case "foreign_table": {
+            const schema = requireSchema(change);
+            const objectName = getObjectName(change);
+            return {
+                path: schemaPath(schema, "foreign_tables", `${objectName}.sql`),
+                category: "foreign_tables",
+                metadata: {
+                    objectType: "foreign_table",
+                    schemaName: schema,
+                    objectName,
+                },
+            };
+        }
+        case "view": {
+            const schema = requireSchema(change);
+            const objectName = getObjectName(change);
+            return {
+                path: schemaPath(schema, "views", `${objectName}.sql`),
+                category: "views",
+                metadata: {
+                    objectType: "view",
+                    schemaName: schema,
+                    objectName,
+                },
+            };
+        }
+        case "materialized_view": {
+            const schema = requireSchema(change);
+            const objectName = getObjectName(change);
+            return {
+                path: schemaPath(schema, "matviews", `${objectName}.sql`),
+                category: "matviews",
+                metadata: {
+                    objectType: "materialized_view",
+                    schemaName: schema,
+                    objectName,
+                },
+            };
+        }
+        case "procedure": {
+            const schema = requireSchema(change);
+            const objectName = getObjectName(change);
+            const isProcedure = change.procedure.kind === "p";
+            return {
+                path: schemaPath(schema, isProcedure ? "procedures" : "functions", `${objectName}.sql`),
+                category: isProcedure ? "procedures" : "functions",
+                metadata: {
+                    objectType: isProcedure ? "procedure" : "function",
+                    schemaName: schema,
+                    objectName,
+                },
+            };
+        }
+        case "aggregate": {
+            const schema = requireSchema(change);
+            const objectName = getObjectName(change);
+            return {
+                path: schemaPath(schema, "aggregates", `${objectName}.sql`),
+                category: "aggregates",
+                metadata: {
+                    objectType: "aggregate",
+                    schemaName: schema,
+                    objectName,
+                },
+            };
+        }
+        case "index": {
+            const schema = requireSchema(change);
+            const parent = getParentInfo(change);
+            if (!parent) {
+                throw new Error(`Expected parent for index '${getObjectName(change)}' in schema '${schema}'`);
+            }
+            const parentName = parent.name;
+            const category = parent.type === "materialized_view" ? "matviews" : "tables";
+            return {
+                path: schemaPath(schema, category, `${parentName}.sql`),
+                category,
+                metadata: {
+                    objectType: parent.type,
+                    schemaName: schema,
+                    objectName: parentName,
+                },
+            };
+        }
+        case "trigger":
+        case "rls_policy":
+        case "rule": {
+            const schema = requireSchema(change);
+            const parent = getParentInfo(change);
+            if (!parent) {
+                throw new Error(`Expected parent for ${change.objectType} '${getObjectName(change)}' in schema '${schema}'`);
+            }
+            const parentName = parent.name;
+            const category = parent.type === "view"
+                ? "views"
+                : parent.type === "materialized_view"
+                    ? "matviews"
+                    : "tables";
+            return {
+                path: schemaPath(schema, category, `${parentName}.sql`),
+                category,
+                metadata: {
+                    objectType: parent.type,
+                    schemaName: schema,
+                    objectName: parentName,
+                },
+            };
+        }
+        default: {
+            const _exhaustive = change;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Compile user-facing `GroupingPattern[]` into `CompiledPattern[]`.
+ * Strings are turned into `new RegExp(str)`. Invalid regex strings are skipped
+ * (no throw), so the returned `compiled` array may be shorter than the input.
+ * Any skipped patterns are reported in `warnings`.
+ */
+export function compilePatterns(patterns) {
+    const compiled = [];
+    const warnings = [];
+    for (const p of patterns) {
+        let regex;
+        if (typeof p.pattern === "string") {
+            try {
+                regex = new RegExp(p.pattern);
+            }
+            catch (e) {
+                const msg = `Skipping invalid grouping regex '${p.pattern}': ${e instanceof Error ? e.message : String(e)}`;
+                debugExport(msg);
+                warnings.push(msg);
+                continue;
+            }
+        }
+        else {
+            // Strip /g and /y flags — .test() mutates lastIndex with these flags,
+            // causing non-deterministic matching across repeated calls.
+            const flags = p.pattern.flags.replace(/[gy]/g, "");
+            regex =
+                flags !== p.pattern.flags
+                    ? new RegExp(p.pattern.source, flags)
+                    : p.pattern;
+        }
+        compiled.push({ regex, name: p.name });
+    }
+    return { compiled, warnings };
+}
+/**
+ * Create a file mapper that applies regex-based grouping on top of the
+ * default `getFilePath` mapping.
+ *
+ * When no grouping config is provided (or it is undefined), the plain
+ * `getFilePath` function is returned unchanged.
+ */
+export function createFileMapper(grouping, onWarning) {
+    if (!grouping)
+        return getFilePath;
+    const { compiled, warnings } = compilePatterns(grouping.groupPatterns ?? []);
+    for (const w of warnings) {
+        onWarning?.(w);
+    }
+    const autoPartitions = grouping.autoGroupPartitions !== false; // default true
+    const flatSet = new Set(grouping.flatSchemas ?? []);
+    return (change) => {
+        const basePath = getFilePath(change);
+        // Flat schemas: collapse everything into one file per category.
+        // Applied first -- skips pattern matching for these schemas.
+        if (flatSet.size > 0 &&
+            basePath.metadata.schemaName &&
+            flatSet.has(basePath.metadata.schemaName)) {
+            return flattenSchema(basePath);
+        }
+        const groupName = resolveGroupName(change, basePath, compiled, autoPartitions);
+        if (!groupName)
+            return basePath;
+        return applyGrouping(basePath, groupName, grouping.mode);
+    };
+}
+/**
+ * Flatten a schema-scoped file path into one file per category.
+ *
+ * e.g. `schemas/partman/tables/template_public_events.sql`
+ *    → `schemas/partman/tables.sql`
+ *
+ * `schema.sql` is left unchanged (it is already flat).
+ */
+export function flattenSchema(filePath) {
+    const schema = filePath.metadata.schemaName ?? "";
+    const category = filePath.category;
+    // schema.sql stays as-is
+    if (category === "schema")
+        return filePath;
+    return {
+        path: schemaPath(schema, `${category}.sql`),
+        category,
+        metadata: {
+            ...filePath.metadata,
+            objectName: category,
+        },
+    };
+}
+/**
+ * Determine the group name for a change, or `null` if it should not be
+ * grouped.
+ *
+ * Resolution order:
+ *  1. Automatic partition detection -- resolve the parent table name.
+ *  2. Regex patterns -- first match wins (user controls priority by ordering).
+ *
+ * The resolved name from step 1 is fed through step 2 so that a partition
+ * parent name can itself be matched by a broader pattern (e.g. parent
+ * "kubernetes_resource_events" matches `/^kubernetes/`).
+ *
+ * If auto-detect resolved a parent but no pattern matched, the parent name
+ * is used as-is.
+ */
+export function resolveGroupName(change, filePath, patterns, autoPartitions) {
+    // Only schema-scoped objects can be grouped (skip cluster-level).
+    if (!filePath.metadata.schemaName)
+        return null;
+    // 1. Auto-detect partitions: table changes where the table is a partition
+    //    of another table.
+    let resolvedName = null;
+    if (autoPartitions &&
+        change.objectType === "table" &&
+        change.table.is_partition &&
+        change.table.parent_name) {
+        resolvedName = change.table.parent_name;
+    }
+    // 2. Regex patterns -- first match wins.
+    const nameToMatch = resolvedName ?? filePath.metadata.objectName;
+    if (nameToMatch) {
+        for (const p of patterns) {
+            if (p.regex.test(nameToMatch)) {
+                return p.name;
+            }
+        }
+    }
+    // 3. If auto-detect found a parent but no pattern matched, use the parent
+    //    name directly.
+    return resolvedName;
+}
+/**
+ * Rewrite a `FilePath` according to the chosen grouping mode.
+ *
+ * - **single-file**: the filename becomes `{prefix}.sql` inside the original
+ *   category directory.
+ *   e.g. `schemas/public/tables/wal_verification_results_p20260107.sql`
+ *     → `schemas/public/tables/wal_verification_results.sql`
+ *
+ * - **subdirectory**: the file is moved to a prefix-named directory under the
+ *   schema root, with the category as the filename.
+ *   e.g. `schemas/public/tables/wal_verification_results_p20260107.sql`
+ *     → `schemas/public/wal_verification_results/tables.sql`
+ */
+export function applyGrouping(filePath, prefix, mode) {
+    const schema = filePath.metadata.schemaName ?? "";
+    const category = filePath.category;
+    if (mode === "single-file") {
+        // Replace the filename, keep the category directory.
+        return {
+            path: schemaPath(schema, category, `${prefix}.sql`),
+            category,
+            metadata: {
+                ...filePath.metadata,
+                objectName: prefix,
+            },
+        };
+    }
+    // subdirectory mode: schemas/{schema}/{prefix}/{category}.sql
+    return {
+        path: schemaPath(schema, prefix, `${category}.sql`),
+        category,
+        metadata: {
+            ...filePath.metadata,
+            objectName: prefix,
+        },
+    };
+}

package/dist/core/export/grouper.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Group changes into declarative schema files and order them for readability.
+ */
+import type { Change } from "../change.types.ts";
+import type { FileCategory, FileMetadata, FilePath } from "./types.ts";
+interface FileGroup {
+    path: string;
+    category: FileCategory;
+    metadata: FileMetadata;
+    changes: Change[];
+}
+export declare function groupChangesByFile(changes: Change[], mapper?: (change: Change) => FilePath): FileGroup[];
+export {};

package/dist/core/export/grouper.js

@@ -0,0 +1,76 @@
+/**
+ * Group changes into declarative schema files and order them for readability.
+ */
+import { getFilePath } from "./file-mapper.js";
+import { CATEGORY_PRIORITY } from "./types.js";
+// ============================================================================
+// Within-file ordering
+// ============================================================================
+const OPERATION_PRIORITY = {
+    create: 0,
+    alter: 1,
+};
+const SCOPE_PRIORITY = {
+    object: 0,
+    comment: 1,
+    privilege: 2,
+    default_privilege: 3,
+    membership: 4,
+};
+/**
+ * Sort changes within a file for readability:
+ * 1. By operation: create → alter
+ * 2. By scope: object → comment → privilege → default_privilege → membership
+ * 3. Stable tie-break by original position
+ */
+function sortChangesWithinFile(changes) {
+    // Tag each change with its original index for stable tie-breaking.
+    const tagged = changes.map((change, index) => ({ change, index }));
+    tagged.sort((a, b) => {
+        const opA = OPERATION_PRIORITY[a.change.operation] ?? 99;
+        const opB = OPERATION_PRIORITY[b.change.operation] ?? 99;
+        if (opA !== opB)
+            return opA - opB;
+        const scopeA = SCOPE_PRIORITY[a.change.scope ?? "object"] ?? 99;
+        const scopeB = SCOPE_PRIORITY[b.change.scope ?? "object"] ?? 99;
+        if (scopeA !== scopeB)
+            return scopeA - scopeB;
+        return a.index - b.index;
+    });
+    return tagged.map((t) => t.change);
+}
+// ============================================================================
+// Grouping & Ordering
+// ============================================================================
+export function groupChangesByFile(changes, mapper = getFilePath) {
+    const groups = new Map();
+    for (const change of changes) {
+        const file = mapper(change);
+        const existing = groups.get(file.path);
+        if (!existing) {
+            groups.set(file.path, {
+                path: file.path,
+                category: file.category,
+                metadata: file.metadata,
+                changes: [change],
+            });
+            continue;
+        }
+        existing.changes.push(change);
+    }
+    // Sort within each file for readability.
+    for (const group of groups.values()) {
+        group.changes = sortChangesWithinFile(group.changes);
+    }
+    // Sort files by category priority, then alphabetically by path.
+    return Array.from(groups.values()).sort(sortByCategory);
+}
+/**
+ * Sort by category priority, then path for determinism.
+ */
+function sortByCategory(a, b) {
+    const categoryDiff = CATEGORY_PRIORITY[a.category] - CATEGORY_PRIORITY[b.category];
+    if (categoryDiff !== 0)
+        return categoryDiff;
+    return a.path.localeCompare(b.path);
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Declarative schema export.
+ */
+import type { Integration } from "../integrations/integration.types.ts";
+import type { createPlan } from "../plan/create.ts";
+import type { SqlFormatOptions } from "../plan/sql-format/types.ts";
+import type { DeclarativeSchemaOutput, Grouping } from "./types.ts";
+/**
+ * The result of createPlan, containing the plan, sorted changes, and context.
+ * Use this type when you have already confirmed createPlan returned non-null.
+ */
+type PlanResult = NonNullable<Awaited<ReturnType<typeof createPlan>>>;
+export interface ExportOptions {
+    /** Integration for custom serialization */
+    integration?: Integration;
+    /**
+     * SQL formatter options to control the output style.
+     * Merged on top of the default export options (maxWidth: 180, keywordCase: "upper").
+     * See `SqlFormatOptions` for available keys.
+     */
+    formatOptions?: SqlFormatOptions | null;
+    /**
+     * Group entities by name prefix into consolidated files or subdirectories.
+     * Supports automatic partition detection and/or explicit prefix lists.
+     */
+    grouping?: Grouping;
+    /** Callback for non-fatal warnings (e.g. invalid grouping regex patterns). */
+    onWarning?: (message: string) => void;
+}
+/**
+ * Export a declarative schema from a plan result.
+ *
+ * Takes the output of `createPlan()` and generates a declarative schema output
+ * with files grouped by object type. Drop operations are excluded since
+ * declarative mode targets the final desired state.
+ *
+ * Dependency-based filtering (cascading exclusions) is handled by `createPlan`,
+ * so this function only needs to filter out drop operations.
+ *
+ * @param planResult - The result from createPlan() containing plan, sortedChanges, and ctx
+ * @param options - Optional integration for custom serialization
+ * @returns Declarative schema output with grouped files
+ */
+export declare function exportDeclarativeSchema(planResult: PlanResult, options?: ExportOptions): DeclarativeSchemaOutput;
+export {};

package/dist/core/export/index.js

@@ -0,0 +1,63 @@
+/**
+ * Declarative schema export.
+ */
+import { buildPlanScopeFingerprint, hashStableIds } from "../fingerprint.js";
+import { DEFAULT_OPTIONS } from "../plan/sql-format/constants.js";
+import { formatSqlScript } from "../plan/statements.js";
+import { createFileMapper } from "./file-mapper.js";
+import { groupChangesByFile } from "./grouper.js";
+/**
+ * Export a declarative schema from a plan result.
+ *
+ * Takes the output of `createPlan()` and generates a declarative schema output
+ * with files grouped by object type. Drop operations are excluded since
+ * declarative mode targets the final desired state.
+ *
+ * Dependency-based filtering (cascading exclusions) is handled by `createPlan`,
+ * so this function only needs to filter out drop operations.
+ *
+ * @param planResult - The result from createPlan() containing plan, sortedChanges, and ctx
+ * @param options - Optional integration for custom serialization
+ * @returns Declarative schema output with grouped files
+ */
+export function exportDeclarativeSchema(planResult, options) {
+    const { ctx, sortedChanges } = planResult;
+    const integration = options?.integration;
+    const formatOptions = options?.formatOptions === null
+        ? undefined
+        : {
+            ...DEFAULT_OPTIONS,
+            maxWidth: 180,
+            keywordCase: "upper",
+            ...options?.formatOptions,
+        };
+    // Drop filtering and dependency cascading are handled upstream by createPlan.
+    const { hash: sourceFingerprint, stableIds } = buildPlanScopeFingerprint(ctx.mainCatalog, sortedChanges);
+    const targetFingerprint = hashStableIds(ctx.branchCatalog, stableIds);
+    const mapper = createFileMapper(options?.grouping, options?.onWarning);
+    const groups = groupChangesByFile(sortedChanges, mapper);
+    const files = groups.map((group, index) => {
+        const statements = group.changes.map((change) => serializeChange(change, integration));
+        return buildFileEntry(group.path, group.metadata, statements, index, formatOptions);
+    });
+    return {
+        version: 1,
+        mode: "declarative",
+        generatedAt: new Date().toISOString(),
+        source: { fingerprint: sourceFingerprint },
+        target: { fingerprint: targetFingerprint },
+        files,
+    };
+}
+function serializeChange(change, integration) {
+    return integration?.serialize?.(change) ?? change.serialize();
+}
+function buildFileEntry(path, metadata, statements, order, formatOptions) {
+    return {
+        path,
+        order,
+        statements: statements.length,
+        sql: formatSqlScript(statements, formatOptions),
+        metadata,
+    };
+}