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

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

@@ -0,0 +1,12 @@
+import type { Change } from "../../change.types.ts";
+/**
+ * Property extractor function that extracts a value from a change.
+ */
+type PropertyExtractor = (change: Change) => string | null;
+/**
+ * Registry of property extractors.
+ * Maps property names to extractor functions.
+ */
+export declare const PROPERTY_EXTRACTORS: Record<string, PropertyExtractor>;
+export declare function getSchema(change: Change): string | null;
+export {};

package/dist/core/integrations/filter/extractors.js

@@ -0,0 +1,136 @@
+/**
+ * Registry of property extractors.
+ * Maps property names to extractor functions.
+ */
+export const PROPERTY_EXTRACTORS = {
+    schema: getSchema,
+    owner: getOwner,
+    member: (change) => {
+        if (change.scope === "membership") {
+            return change.member;
+        }
+        return null;
+    },
+};
+export function getSchema(change) {
+    switch (change.objectType) {
+        case "aggregate":
+            return change.aggregate.schema;
+        case "collation":
+            return change.collation.schema;
+        case "composite_type":
+            return change.compositeType.schema;
+        case "domain":
+            return change.domain.schema;
+        case "enum":
+            return change.enum.schema;
+        case "event_trigger":
+            return null;
+        case "extension":
+            return change.extension.schema;
+        case "index":
+            return change.index.schema;
+        case "language":
+            return null;
+        case "materialized_view":
+            return change.materializedView.schema;
+        case "procedure":
+            return change.procedure.schema;
+        case "publication":
+            return null;
+        case "range":
+            return change.range.schema;
+        case "rls_policy":
+            return change.policy.schema;
+        case "role":
+            return null;
+        case "rule":
+            return change.rule.schema;
+        case "schema":
+            return change.schema.name;
+        case "sequence":
+            return change.sequence.schema;
+        case "subscription":
+            return null;
+        case "table":
+            return change.table.schema;
+        case "trigger":
+            return change.trigger.schema;
+        case "view":
+            return change.view.schema;
+        case "foreign_data_wrapper":
+            return null;
+        case "server":
+            return null;
+        case "user_mapping":
+            return null;
+        case "foreign_table":
+            return change.foreignTable.schema;
+        default: {
+            // exhaustiveness check
+            const _exhaustive = change;
+            return _exhaustive;
+        }
+    }
+}
+function getOwner(change) {
+    switch (change.objectType) {
+        case "aggregate":
+            return change.aggregate.owner;
+        case "collation":
+            return change.collation.owner;
+        case "composite_type":
+            return change.compositeType.owner;
+        case "domain":
+            return change.domain.owner;
+        case "enum":
+            return change.enum.owner;
+        case "event_trigger":
+            return change.eventTrigger.owner;
+        case "extension":
+            return change.extension.owner;
+        case "index":
+            return change.index.owner;
+        case "language":
+            return change.language.owner;
+        case "materialized_view":
+            return change.materializedView.owner;
+        case "procedure":
+            return change.procedure.owner;
+        case "publication":
+            return change.publication.owner;
+        case "range":
+            return change.range.owner;
+        case "rls_policy":
+            return change.policy.owner;
+        case "role":
+            return change.role.name;
+        case "rule":
+            return change.rule.owner;
+        case "schema":
+            return change.schema.owner;
+        case "sequence":
+            return change.sequence.owner;
+        case "subscription":
+            return change.subscription.owner;
+        case "table":
+            return change.table.owner;
+        case "trigger":
+            return change.trigger.owner;
+        case "view":
+            return change.view.owner;
+        case "foreign_data_wrapper":
+            return change.foreignDataWrapper.owner;
+        case "server":
+            return change.server.owner;
+        case "user_mapping":
+            return null;
+        case "foreign_table":
+            return change.foreignTable.owner;
+        default: {
+            // exhaustiveness check
+            const _exhaustive = change;
+            return _exhaustive;
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { Change } from "../../change.types.ts";
+export type ChangeFilter = (change: Change) => boolean;

package/dist/core/integrations/filter/filter.types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/integrations/integration-dsl.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Integration DSL - A serializable domain-specific language for integrations.
+ *
+ * Combines filter and serialization DSLs into a single serializable structure.
+ */
+import type { FilterDSL } from "./filter/dsl.ts";
+import type { SerializeDSL } from "./serialize/dsl.ts";
+/**
+ * Integration DSL - serializable representation of an integration.
+ */
+export type IntegrationDSL = {
+    /**
+     * Filter DSL - determines which changes to include/exclude.
+     * If not provided, all changes are included.
+     */
+    filter?: FilterDSL;
+    /**
+     * Serialization DSL - customizes how changes are serialized.
+     * If not provided, changes are serialized with default options.
+     */
+    serialize?: SerializeDSL;
+};

package/dist/core/integrations/integration-dsl.js

@@ -0,0 +1,6 @@
+/**
+ * Integration DSL - A serializable domain-specific language for integrations.
+ *
+ * Combines filter and serialization DSLs into a single serializable structure.
+ */
+export {};

package/dist/core/integrations/integration.types.d.ts

@@ -0,0 +1,6 @@
+import type { ChangeFilter } from "./filter/filter.types.ts";
+import type { ChangeSerializer } from "./serialize/serialize.types.ts";
+export type Integration = {
+    filter?: ChangeFilter;
+    serialize?: ChangeSerializer;
+};

package/dist/core/integrations/integration.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,58 @@
+/**
+ * Serialization DSL - A serializable domain-specific language for customizing change serialization.
+ *
+ * Reuses the filter pattern matching logic to determine when to apply serialization options.
+ */
+import { type FilterPattern } from "../filter/dsl.ts";
+import type { ChangeSerializer } from "./serialize.types.ts";
+/**
+ * Serialization options that can be passed to change.serialize().
+ */
+type SerializeOptions = {
+    skipAuthorization?: boolean;
+    [key: string]: unknown;
+};
+/**
+ * A serialization rule that applies options when a pattern matches.
+ */
+type SerializeRule = {
+    /**
+     * Pattern to match against changes.
+     * Uses the same pattern matching logic as filters.
+     */
+    when: FilterPattern;
+    /**
+     * Serialization options to apply when the pattern matches.
+     */
+    options: SerializeOptions;
+};
+/**
+ * Serialization DSL - array of rules evaluated in order.
+ * First matching rule's options are applied.
+ */
+export type SerializeDSL = SerializeRule[];
+/**
+ * Compile a Serialization DSL to a ChangeSerializer function.
+ *
+ * Rules are evaluated in order, and the first matching rule's options are applied.
+ * If no rule matches, the change is serialized with default options.
+ *
+ * @param dsl - The serialization DSL
+ * @returns A ChangeSerializer function that applies the rules
+ *
+ * @example
+ * ```ts
+ * const serializer = compileSerializeDSL([
+ *   {
+ *     when: {
+ *       type: "schema",
+ *       operation: "create",
+ *       owner: ["service_role"]
+ *     },
+ *     options: { skipAuthorization: true }
+ *   }
+ * ]);
+ * ```
+ */
+export declare function compileSerializeDSL(dsl: SerializeDSL): ChangeSerializer;
+export {};

package/dist/core/integrations/serialize/dsl.js

@@ -0,0 +1,42 @@
+/**
+ * Serialization DSL - A serializable domain-specific language for customizing change serialization.
+ *
+ * Reuses the filter pattern matching logic to determine when to apply serialization options.
+ */
+import { evaluatePattern } from "../filter/dsl.js";
+/**
+ * Compile a Serialization DSL to a ChangeSerializer function.
+ *
+ * Rules are evaluated in order, and the first matching rule's options are applied.
+ * If no rule matches, the change is serialized with default options.
+ *
+ * @param dsl - The serialization DSL
+ * @returns A ChangeSerializer function that applies the rules
+ *
+ * @example
+ * ```ts
+ * const serializer = compileSerializeDSL([
+ *   {
+ *     when: {
+ *       type: "schema",
+ *       operation: "create",
+ *       owner: ["service_role"]
+ *     },
+ *     options: { skipAuthorization: true }
+ *   }
+ * ]);
+ * ```
+ */
+export function compileSerializeDSL(dsl) {
+    return (change) => {
+        // Find first matching rule
+        for (const rule of dsl) {
+            if (evaluatePattern(rule.when, change)) {
+                // Apply this rule's options
+                return change.serialize(rule.options);
+            }
+        }
+        // No rule matched - use default serialization
+        return change.serialize();
+    };
+}

package/dist/core/integrations/serialize/serialize.types.d.ts

@@ -0,0 +1,2 @@
+import type { Change } from "../../change.types.ts";
+export type ChangeSerializer = (change: Change) => string | undefined;

package/dist/core/integrations/serialize/serialize.types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/integrations/supabase.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Supabase integration - filtering and serialization rules for Supabase databases.
+ *
+ * This integration:
+ * - Filters out Supabase system schemas and roles
+ * - Includes user schemas and extensions
+ * - Skips authorization for schema creates owned by Supabase system roles
+ */
+import type { IntegrationDSL } from "./integration-dsl.ts";
+export declare const supabase: IntegrationDSL;

package/dist/core/integrations/supabase.js

@@ -0,0 +1,114 @@
+/**
+ * Supabase integration - filtering and serialization rules for Supabase databases.
+ *
+ * This integration:
+ * - Filters out Supabase system schemas and roles
+ * - Includes user schemas and extensions
+ * - Skips authorization for schema creates owned by Supabase system roles
+ */
+// Supabase system schemas that should be excluded
+const SUPABASE_SYSTEM_SCHEMAS = [
+    "_analytics",
+    "_realtime",
+    "_supavisor",
+    "auth",
+    "cron",
+    "extensions",
+    "graphql",
+    "graphql_public",
+    "information_schema",
+    "net",
+    "pgbouncer",
+    "pgmq",
+    "pgmq_public",
+    "pgsodium",
+    "pgsodium_masks",
+    "pgtle",
+    "realtime",
+    "storage",
+    "supabase_functions",
+    "supabase_migrations",
+    "vault",
+];
+// Supabase system roles that should be excluded
+const SUPABASE_SYSTEM_ROLES = [
+    "anon",
+    "authenticated",
+    "authenticator",
+    "dashboard_user",
+    "pgbouncer",
+    "pgsodium_keyholder",
+    "pgsodium_keyiduser",
+    "pgsodium_keymaker",
+    "pgtle_admin",
+    "service_role",
+    "supabase_admin",
+    "supabase_auth_admin",
+    "supabase_etl_admin",
+    "supabase_functions_admin",
+    "supabase_read_only_user",
+    "supabase_realtime_admin",
+    "supabase_replication_admin",
+    "supabase_storage_admin",
+];
+export const supabase = {
+    filter: {
+        or: [
+            {
+                and: [
+                    {
+                        type: "schema",
+                        operation: "create",
+                        scope: "object",
+                    },
+                    {
+                        not: {
+                            schema: [...SUPABASE_SYSTEM_SCHEMAS],
+                        },
+                    },
+                ],
+            },
+            {
+                type: "extension",
+                operation: "create",
+                scope: "object",
+            },
+            {
+                not: {
+                    or: [
+                        {
+                            schema: [...SUPABASE_SYSTEM_SCHEMAS],
+                        },
+                        {
+                            owner: [...SUPABASE_SYSTEM_ROLES],
+                        },
+                        {
+                            and: [
+                                {
+                                    type: "role",
+                                    scope: "membership",
+                                },
+                                {
+                                    member: [...SUPABASE_SYSTEM_ROLES],
+                                },
+                            ],
+                        },
+                    ],
+                },
+            },
+        ],
+    },
+    serialize: [
+        {
+            when: {
+                type: "schema",
+                operation: "create",
+                scope: "object",
+                owner: [...SUPABASE_SYSTEM_ROLES],
+            },
+            options: {
+                skipAuthorization: true,
+            },
+        },
+    ],
+};

package/dist/core/objects/aggregate/aggregate.diff.d.ts

@@ -0,0 +1,10 @@
+import type { DefaultPrivilegeState } from "../base.default-privileges.ts";
+import type { Role } from "../role/role.model.ts";
+import type { Aggregate } from "./aggregate.model.ts";
+import type { AggregateChange } from "./changes/aggregate.types.ts";
+export declare function diffAggregates(ctx: {
+    version: number;
+    currentUser: string;
+    defaultPrivilegeState: DefaultPrivilegeState;
+    mainRoles: Record<string, Role>;
+}, main: Record<string, Aggregate>, branch: Record<string, Aggregate>): AggregateChange[];

package/dist/core/objects/aggregate/aggregate.diff.js

@@ -0,0 +1,186 @@
+import { diffObjects } from "../base.diff.js";
+import { diffPrivileges, filterPublicBuiltInDefaults, groupPrivilegesByGrantable, } from "../base.privilege-diff.js";
+import { deepEqual, hasNonAlterableChanges } from "../utils.js";
+import { AlterAggregateChangeOwner } from "./changes/aggregate.alter.js";
+import { CreateCommentOnAggregate, DropCommentOnAggregate, } from "./changes/aggregate.comment.js";
+import { CreateAggregate } from "./changes/aggregate.create.js";
+import { DropAggregate } from "./changes/aggregate.drop.js";
+import { GrantAggregatePrivileges, RevokeAggregatePrivileges, RevokeGrantOptionAggregatePrivileges, } from "./changes/aggregate.privilege.js";
+export function diffAggregates(ctx, main, branch) {
+    const { created, dropped, altered } = diffObjects(main, branch);
+    const changes = [];
+    for (const aggregateId of created) {
+        const aggregate = branch[aggregateId];
+        changes.push(new CreateAggregate({ aggregate }));
+        // OWNER: If the aggregate should be owned by someone other than the current user,
+        // emit ALTER AGGREGATE ... OWNER TO after creation
+        if (aggregate.owner !== ctx.currentUser) {
+            changes.push(new AlterAggregateChangeOwner({
+                aggregate,
+                owner: aggregate.owner,
+            }));
+        }
+        if (aggregate.comment !== null) {
+            changes.push(new CreateCommentOnAggregate({ aggregate }));
+        }
+        // PRIVILEGES: For created objects, compare against default privileges state
+        // The migration script will run ALTER DEFAULT PRIVILEGES before CREATE (via constraint spec),
+        // so objects are created with the default privileges state in effect.
+        // We compare default privileges against desired privileges to generate REVOKE/GRANT statements
+        // needed to reach the final desired state.
+        const effectiveDefaults = ctx.defaultPrivilegeState.getEffectiveDefaults(ctx.currentUser, "aggregate", aggregate.schema ?? "");
+        // Filter out PUBLIC's built-in default EXECUTE privilege (PostgreSQL grants it automatically)
+        // Reference: https://www.postgresql.org/docs/17/ddl-priv.html Table 5.2
+        // This prevents generating unnecessary "GRANT EXECUTE TO PUBLIC" statements
+        const desiredPrivileges = filterPublicBuiltInDefaults("aggregate", aggregate.privileges);
+        // Filter out owner privileges - owner always has ALL privileges implicitly
+        // and shouldn't be compared. Use the aggregate owner as the reference.
+        const privilegeResults = diffPrivileges(effectiveDefaults, desiredPrivileges, aggregate.owner, ctx.mainRoles);
+        // Generate grant changes
+        for (const [grantee, result] of privilegeResults) {
+            if (result.grants.length > 0) {
+                const grantGroups = groupPrivilegesByGrantable(result.grants);
+                for (const [, list] of grantGroups) {
+                    changes.push(new GrantAggregatePrivileges({
+                        aggregate,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            // Generate revoke changes
+            if (result.revokes.length > 0) {
+                const revokeGroups = groupPrivilegesByGrantable(result.revokes);
+                for (const [, list] of revokeGroups) {
+                    changes.push(new RevokeAggregatePrivileges({
+                        aggregate,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            // Generate revoke grant option changes
+            if (result.revokeGrantOption.length > 0) {
+                changes.push(new RevokeGrantOptionAggregatePrivileges({
+                    aggregate,
+                    grantee,
+                    privilegeNames: result.revokeGrantOption,
+                    version: ctx.version,
+                }));
+            }
+        }
+    }
+    for (const aggregateId of dropped) {
+        changes.push(new DropAggregate({ aggregate: main[aggregateId] }));
+    }
+    for (const aggregateId of altered) {
+        const mainAggregate = main[aggregateId];
+        const branchAggregate = branch[aggregateId];
+        const NON_ALTERABLE_FIELDS = [
+            "kind",
+            "aggkind",
+            "num_direct_args",
+            "return_type",
+            "return_type_schema",
+            "parallel_safety",
+            "is_strict",
+            "transition_function",
+            "state_data_type",
+            "state_data_type_schema",
+            "state_data_space",
+            "final_function",
+            "final_function_extra_args",
+            "final_function_modify",
+            "combine_function",
+            "serial_function",
+            "deserial_function",
+            "initial_condition",
+            "moving_transition_function",
+            "moving_inverse_function",
+            "moving_state_data_type",
+            "moving_state_data_type_schema",
+            "moving_state_data_space",
+            "moving_final_function",
+            "moving_final_function_extra_args",
+            "moving_final_function_modify",
+            "moving_initial_condition",
+            "sort_operator",
+            "argument_count",
+            "argument_default_count",
+            "argument_names",
+            "argument_types",
+            "all_argument_types",
+            "argument_modes",
+            "argument_defaults",
+            "identityArguments",
+        ];
+        const nonAlterableChanged = hasNonAlterableChanges(mainAggregate, branchAggregate, NON_ALTERABLE_FIELDS, {
+            argument_names: deepEqual,
+            argument_types: deepEqual,
+            all_argument_types: deepEqual,
+            argument_modes: deepEqual,
+        });
+        if (nonAlterableChanged) {
+            changes.push(new CreateAggregate({ aggregate: branchAggregate, orReplace: true }));
+            continue;
+        }
+        if (mainAggregate.owner !== branchAggregate.owner) {
+            changes.push(new AlterAggregateChangeOwner({
+                aggregate: mainAggregate,
+                owner: branchAggregate.owner,
+            }));
+        }
+        if (mainAggregate.comment !== branchAggregate.comment) {
+            if (branchAggregate.comment === null) {
+                changes.push(new DropCommentOnAggregate({ aggregate: mainAggregate }));
+            }
+            else {
+                changes.push(new CreateCommentOnAggregate({ aggregate: branchAggregate }));
+            }
+        }
+        // PRIVILEGES
+        // Filter out PUBLIC's built-in default EXECUTE privilege from main catalog
+        // (PostgreSQL grants it automatically, so we shouldn't compare it)
+        const mainPrivilegesFiltered = filterPublicBuiltInDefaults("aggregate", mainAggregate.privileges);
+        // Filter out PUBLIC's built-in default EXECUTE privilege from branch catalog
+        const branchPrivilegesFiltered = filterPublicBuiltInDefaults("aggregate", branchAggregate.privileges);
+        // Filter out owner privileges - owner always has ALL privileges implicitly
+        // and shouldn't be compared. Use branch owner as the reference.
+        const privilegeResults = diffPrivileges(mainPrivilegesFiltered, branchPrivilegesFiltered, branchAggregate.owner, ctx.mainRoles);
+        for (const [grantee, result] of privilegeResults) {
+            if (result.grants.length > 0) {
+                const grantGroups = groupPrivilegesByGrantable(result.grants);
+                for (const [, list] of grantGroups) {
+                    changes.push(new GrantAggregatePrivileges({
+                        aggregate: branchAggregate,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            if (result.revokes.length > 0) {
+                const revokeGroups = groupPrivilegesByGrantable(result.revokes);
+                for (const [, list] of revokeGroups) {
+                    changes.push(new RevokeAggregatePrivileges({
+                        aggregate: mainAggregate,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            if (result.revokeGrantOption.length > 0) {
+                changes.push(new RevokeGrantOptionAggregatePrivileges({
+                    aggregate: mainAggregate,
+                    grantee,
+                    privilegeNames: result.revokeGrantOption,
+                    version: ctx.version,
+                }));
+            }
+        }
+    }
+    return changes;
+}