@supabase/pg-delta 1.0.0-alpha.10 → 1.0.0-alpha.12

package/src/core/integrations/serialize/dsl.test.ts

@@ -1,26 +1,45 @@
 import { describe, expect, test } from "bun:test";
 import type { Change } from "../../change.types.ts";
 import { compileSerializeDSL } from "./dsl.ts";
+import type { SerializeOptions } from "./serialize.types.ts";
 
 function makeChange(
   type: string,
   operation: string,
-  serializeFn: (opts?: Record<string, unknown>) => string,
+  serializeFn: (opts?: SerializeOptions) => string,
 ): Change {
   return {
     objectType: type,
     operation,
     scope: "object",
     schema: { name: "test" },
+    extension: { schema: "pgmq" },
     serialize: serializeFn,
   } as unknown as Change;
 }
 
 describe("compileSerializeDSL", () => {
+  test("matching extension rule can skip schema serialization", () => {
+    const serializer = compileSerializeDSL([
+      {
+        when: { objectType: "extension", operation: "create" },
+        options: { skipSchema: true },
+      },
+    ]);
+
+    const change = makeChange("extension", "create", (opts) =>
+      opts?.skipSchema
+        ? "CREATE EXTENSION pgmq"
+        : "CREATE EXTENSION pgmq WITH SCHEMA pgmq",
+    );
+
+    expect(serializer(change)).toBe("CREATE EXTENSION pgmq");
+  });
+
   test("matching rule applies its options", () => {
     const serializer = compileSerializeDSL([
       {
-        when: { type: "schema" as const, operation: "create" as const },
+        when: { objectType: "schema", operation: "create" },
         options: { skipAuthorization: true },
       },
     ]);
@@ -37,7 +56,7 @@ describe("compileSerializeDSL", () => {
   test("no matching rule uses default serialization", () => {
     const serializer = compileSerializeDSL([
       {
-        when: { type: "table" as const },
+        when: { objectType: "table" },
         options: { skipAuthorization: true },
       },
     ]);
@@ -54,11 +73,11 @@ describe("compileSerializeDSL", () => {
   test("first matching rule wins", () => {
     const serializer = compileSerializeDSL([
       {
-        when: { type: "schema" as const },
+        when: { objectType: "schema" },
         options: { skipAuthorization: true },
       },
       {
-        when: { type: "schema" as const },
+        when: { objectType: "schema" },
         options: { skipAuthorization: false },
       },
     ]);
@@ -73,11 +92,11 @@ describe("compileSerializeDSL", () => {
   test("skips non-matching first rule and applies second", () => {
     const serializer = compileSerializeDSL([
       {
-        when: { type: "table" as const },
+        when: { objectType: "table" },
         options: { skipAuthorization: true },
       },
       {
-        when: { type: "schema" as const },
+        when: { objectType: "schema" },
         options: { skipAuthorization: false },
       },
     ]);

package/src/core/integrations/serialize/dsl.ts

@@ -6,16 +6,7 @@
 
 import type { Change } from "../../change.types.ts";
 import { evaluatePattern, 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;
-  // Can be extended with more options in the future
-  [key: string]: unknown;
-};
+import type { ChangeSerializer, SerializeOptions } from "./serialize.types.ts";
 
 /**
  * A serialization rule that applies options when a pattern matches.
@@ -33,8 +24,11 @@ type SerializeRule = {
 };
 
 /**
- * Serialization DSL - array of rules evaluated in order.
- * First matching rule's options are applied.
+ * Array of serialization rules evaluated in order. The first matching rule's
+ * options are passed to `change.serialize()`. If no rule matches, default
+ * serialization is used.
+ *
+ * @category Integration
  */
 export type SerializeDSL = SerializeRule[];
 
@@ -52,9 +46,9 @@ export type SerializeDSL = SerializeRule[];
  * const serializer = compileSerializeDSL([
  *   {
  *     when: {
- *       type: "schema",
+ *       objectType: "schema",
  *       operation: "create",
- *       owner: ["service_role"]
+ *       "schema/owner": ["service_role"]
  *     },
  *     options: { skipAuthorization: true }
  *   }

package/src/core/integrations/serialize/serialize.types.ts

@@ -1,3 +1,40 @@
 import type { Change } from "../../change.types.ts";
 
+/**
+ * Shared serialization options passed to `change.serialize(options)`.
+ *
+ * This is the global source of truth for serialize-option flags used by the
+ * integration serialization DSL and concrete change serializers.
+ *
+ * @category Integration
+ */
+export type SerializeOptions = {
+  /** Skip `AUTHORIZATION` when serializing schema creation. */
+  skipAuthorization?: boolean;
+  /** Skip `WITH SCHEMA ...` when serializing extension creation. */
+  skipSchema?: boolean;
+};
+
+/**
+ * Schema-specific view of {@link SerializeOptions}.
+ *
+ * @category Integration
+ */
+export type SchemaSerializeOptions = Pick<
+  SerializeOptions,
+  "skipAuthorization"
+>;
+
+/**
+ * Extension-specific view of {@link SerializeOptions}.
+ *
+ * @category Integration
+ */
+export type ExtensionSerializeOptions = Pick<SerializeOptions, "skipSchema">;
+
+/**
+ * Compiled serializer function used during plan/declarative export rendering.
+ *
+ * @category Integration
+ */
 export type ChangeSerializer = (change: Change) => string | undefined;

package/src/core/integrations/supabase.ts

@@ -70,38 +70,59 @@ export const supabase: IntegrationDSL = {
   // TODO: emptyCatalog: undefined -- populate by running catalog-export on a clean Supabase container
   filter: {
     or: [
+      // Include user schema CREATE operations (only schemas not in system list)
       {
         and: [
           {
-            type: "schema",
+            objectType: "schema",
             operation: "create",
             scope: "object",
           },
           {
             not: {
-              schema: [...SUPABASE_SYSTEM_SCHEMAS],
+              // Schema objects have name, not schema — use schema/name
+              "schema/name": [...SUPABASE_SYSTEM_SCHEMAS],
             },
           },
         ],
       },
+      // Include extension CREATEs
       {
-        type: "extension",
+        objectType: "extension",
         operation: "create",
         scope: "object",
       },
+      // Include extension DROPs used to disable some extensions (eg: pg-net)
+      {
+        objectType: "extension",
+        operation: "drop",
+        scope: "object",
+      },
+      // Exclude system objects
       {
         not: {
           or: [
+            // Objects in system schemas (*/schema matches table/schema, view/schema, etc.)
+            {
+              "*/schema": [...SUPABASE_SYSTEM_SCHEMAS],
+            },
+            // Schema objects whose own name is a system schema
+            {
+              "schema/name": [...SUPABASE_SYSTEM_SCHEMAS],
+            },
+            // Objects owned by system roles (*/owner matches table/owner, schema/owner, etc.)
             {
-              schema: [...SUPABASE_SYSTEM_SCHEMAS],
+              "*/owner": [...SUPABASE_SYSTEM_ROLES],
             },
+            // Role objects whose own name is a system role
             {
-              owner: [...SUPABASE_SYSTEM_ROLES],
+              "role/name": [...SUPABASE_SYSTEM_ROLES],
             },
+            // Membership changes for system roles
             {
               and: [
                 {
-                  type: "role",
+                  objectType: "role",
                   scope: "membership",
                 },
                 {
@@ -117,14 +138,27 @@ export const supabase: IntegrationDSL = {
   serialize: [
     {
       when: {
-        type: "schema",
+        objectType: "schema",
         operation: "create",
         scope: "object",
-        owner: [...SUPABASE_SYSTEM_ROLES],
+        "schema/owner": [...SUPABASE_SYSTEM_ROLES],
       },
       options: {
         skipAuthorization: true,
       },
     },
+    // pgmq extensions creates it's own schema on install doing a `CREATE EXTENSION pgmq WITH SCHEMA pgmq;`
+    // will cause an error because the schema will create extension and extension refer to unexisting schema
+    {
+      when: {
+        objectType: "extension",
+        operation: "create",
+        scope: "object",
+        "extension/schema": ["pgmq"],
+      },
+      options: {
+        skipSchema: true,
+      },
+    },
   ],
 };

package/src/core/objects/aggregate/changes/aggregate.alter.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import type { Aggregate } from "../aggregate.model.ts";
 import { AlterAggregateChange } from "./aggregate.base.ts";
 
@@ -23,7 +24,7 @@ export class AlterAggregateChangeOwner extends AlterAggregateChange {
     return [this.aggregate.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const signature = this.aggregate.identityArguments;
     const qualifiedName = `${this.aggregate.schema}.${this.aggregate.name}`;
     const withArgs = signature.length > 0 ? `(${signature})` : "()";

package/src/core/objects/aggregate/changes/aggregate.comment.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import { quoteLiteral } from "../../base.change.ts";
 import { stableId } from "../../utils.ts";
 import type { Aggregate } from "../aggregate.model.ts";
@@ -27,7 +28,7 @@ export class CreateCommentOnAggregate extends CreateAggregateChange {
     return [this.aggregate.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const signature = this.aggregate.identityArguments;
     const qualifiedName = `${this.aggregate.schema}.${this.aggregate.name}`;
     const withArgs = signature.length > 0 ? `(${signature})` : "()";
@@ -53,7 +54,7 @@ export class DropCommentOnAggregate extends DropAggregateChange {
     return [stableId.comment(this.aggregate.stableId), this.aggregate.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const signature = this.aggregate.identityArguments;
     const qualifiedName = `${this.aggregate.schema}.${this.aggregate.name}`;
     const withArgs = signature.length > 0 ? `(${signature})` : "()";

package/src/core/objects/aggregate/changes/aggregate.create.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import { quoteLiteral } from "../../base.change.ts";
 import {
   parseProcedureReference,
@@ -166,7 +167,7 @@ export class CreateAggregate extends CreateAggregateChange {
     return Array.from(dependencies);
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const signature = this.aggregate.identityArguments;
     const qualifiedName = `${this.aggregate.schema}.${this.aggregate.name}`;
     const head = [

package/src/core/objects/aggregate/changes/aggregate.drop.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import type { Aggregate } from "../aggregate.model.ts";
 import { DropAggregateChange } from "./aggregate.base.ts";
 
@@ -23,7 +24,7 @@ export class DropAggregate extends DropAggregateChange {
     return [this.aggregate.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const signature = this.aggregate.identityArguments;
     const qualifiedName = `${this.aggregate.schema}.${this.aggregate.name}`;
     const withArgs = signature.length > 0 ? `(${signature})` : "(*)";

package/src/core/objects/aggregate/changes/aggregate.privilege.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import {
   formatObjectPrivilegeList,
   getObjectKindPrefix,
@@ -39,7 +40,7 @@ export class GrantAggregatePrivileges extends AlterAggregateChange {
     return [this.aggregate.stableId, stableId.role(this.grantee)];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const hasGrantable = this.privileges.some((p) => p.grantable);
     const hasBase = this.privileges.some((p) => !p.grantable);
     if (hasGrantable && hasBase) {
@@ -92,7 +93,7 @@ export class RevokeAggregatePrivileges extends AlterAggregateChange {
     ];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const kindPrefix = getObjectKindPrefix("FUNCTION");
     const list = this.privileges.map((p) => p.privilege);
     const privSql = formatObjectPrivilegeList("FUNCTION", list, this.version);
@@ -131,7 +132,7 @@ export class RevokeGrantOptionAggregatePrivileges extends AlterAggregateChange {
     ];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const kindPrefix = getObjectKindPrefix("FUNCTION");
     const privSql = formatObjectPrivilegeList(
       "FUNCTION",

package/src/core/objects/aggregate/changes/aggregate.types.ts

@@ -4,6 +4,7 @@ import type { CreateAggregate } from "./aggregate.create.ts";
 import type { DropAggregate } from "./aggregate.drop.ts";
 import type { AggregatePrivilege } from "./aggregate.privilege.ts";
 
+/** Union of all aggregate-related change variants (`objectType: "aggregate"`). @category Change Types */
 export type AggregateChange =
   | AlterAggregate
   | CommentAggregate

package/src/core/objects/base.change.ts

@@ -1,5 +1,17 @@
+import type { SerializeOptions } from "../integrations/serialize/serialize.types.ts";
+
 type ChangeOperation = "create" | "alter" | "drop";
 
+/**
+ * Abstract base class for all change objects.
+ *
+ * Every concrete change (e.g. `CreateTable`, `AlterView`) extends this class and
+ * provides an `operation`, `objectType`, and `scope`. The filter DSL flattens
+ * these properties — along with the model sub-object — into path/value pairs
+ * for pattern matching.
+ *
+ * @category Base
+ */
 export abstract class BaseChange {
   /**
    * The operation of the change.
@@ -51,7 +63,7 @@ export abstract class BaseChange {
   /**
    * Serialize the change into a single SQL statement.
    */
-  abstract serialize(options?: Record<string, unknown>): string;
+  abstract serialize(options?: SerializeOptions): string;
 }
 
 /**

package/src/core/objects/base.model.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { BasePgModel } from "./base.model.ts";
+
+class NormalizedTestModel extends BasePgModel {
+  private readonly id: string;
+  private readonly values: string[];
+
+  constructor(id: string, values: string[]) {
+    super();
+    this.id = id;
+    this.values = values;
+  }
+
+  get stableId() {
+    return this.id;
+  }
+
+  get identityFields() {
+    return { id: this.id };
+  }
+
+  get dataFields() {
+    return { values: this.values };
+  }
+
+  override stableSnapshot() {
+    return {
+      identity: this.identityFields,
+      data: {
+        values: [...this.values].sort(),
+      },
+    };
+  }
+}
+
+describe("BasePgModel.equals", () => {
+  test("uses stable snapshots for normalized equality", () => {
+    const main = new NormalizedTestModel("same", ["b", "a"]);
+    const branch = new NormalizedTestModel("same", ["a", "b"]);
+
+    expect(main.equals(branch)).toBe(true);
+  });
+});

package/src/core/objects/base.model.ts

@@ -60,12 +60,15 @@ export abstract class BasePgModel {
   abstract get dataFields(): Record<string, unknown>;
 
   /**
-   * Compare this object with another BasePgModel for equality based on stableId and dataFields.
+   * Compare this object with another BasePgModel for equality based on the stableId and
+   * the data portion of the stable snapshot. By default, the snapshot's `data` comes
+   * from {@link dataFields}, but subclasses may override {@link stableSnapshot} to
+   * normalize or otherwise transform the data used for equality.
    */
   equals(other: BasePgModel): boolean {
     return (
       this.stableId === other.stableId &&
-      deepEqual(this.dataFields, other.dataFields)
+      deepEqual(this.stableSnapshot().data, other.stableSnapshot().data)
     );
   }
 

package/src/core/objects/collation/changes/collation.alter.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import type { Collation } from "../collation.model.ts";
 import { AlterCollationChange } from "./collation.base.ts";
 
@@ -36,7 +37,7 @@ export class AlterCollationChangeOwner extends AlterCollationChange {
     return [this.collation.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return [
       "ALTER COLLATION",
       `${this.collation.schema}.${this.collation.name}`,
@@ -62,7 +63,7 @@ export class AlterCollationRefreshVersion extends AlterCollationChange {
     return [this.collation.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return [
       "ALTER COLLATION",
       `${this.collation.schema}.${this.collation.name}`,

package/src/core/objects/collation/changes/collation.comment.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import { quoteLiteral } from "../../base.change.ts";
 import { stableId } from "../../utils.ts";
 import type { Collation } from "../collation.model.ts";
@@ -30,7 +31,7 @@ export class CreateCommentOnCollation extends CreateCollationChange {
     return [this.collation.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return [
       "COMMENT ON COLLATION",
       `${this.collation.schema}.${this.collation.name}`,
@@ -58,7 +59,7 @@ export class DropCommentOnCollation extends DropCollationChange {
     return [stableId.comment(this.collation.stableId)];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return [
       "COMMENT ON COLLATION",
       `${this.collation.schema}.${this.collation.name}`,

package/src/core/objects/collation/changes/collation.create.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import { quoteLiteral } from "../../base.change.ts";
 import { stableId } from "../../utils.ts";
 import type { Collation } from "../collation.model.ts";
@@ -48,7 +49,7 @@ export class CreateCollation extends CreateCollationChange {
     return Array.from(dependencies);
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const parts: string[] = ["CREATE COLLATION"];
 
     // Add schema and name (already quoted in model extraction)

package/src/core/objects/collation/changes/collation.drop.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import type { Collation } from "../collation.model.ts";
 import { DropCollationChange } from "./collation.base.ts";
 
@@ -28,7 +29,7 @@ export class DropCollation extends DropCollationChange {
     return [this.collation.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return [
       "DROP COLLATION",
       `${this.collation.schema}.${this.collation.name}`,

package/src/core/objects/collation/changes/collation.types.ts

@@ -3,6 +3,7 @@ import type { CommentCollation } from "./collation.comment.ts";
 import type { CreateCollation } from "./collation.create.ts";
 import type { DropCollation } from "./collation.drop.ts";
 
+/** Union of all collation-related change variants (`objectType: "collation"`). @category Change Types */
 export type CollationChange =
   | AlterCollation
   | CommentCollation

package/src/core/objects/domain/changes/domain.alter.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import { stableId } from "../../utils.ts";
 import type { Domain, DomainConstraintProps } from "../domain.model.ts";
 import { AlterDomainChange, DropDomainChange } from "./domain.base.ts";
@@ -63,7 +64,7 @@ export class AlterDomainSetDefault extends AlterDomainChange {
     return [this.domain.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return `ALTER DOMAIN ${this.domain.schema}.${this.domain.name} SET DEFAULT ${this.defaultValue}`;
   }
 }
@@ -84,7 +85,7 @@ export class AlterDomainDropDefault extends AlterDomainChange {
     return [this.domain.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return `ALTER DOMAIN ${this.domain.schema}.${this.domain.name} DROP DEFAULT`;
   }
 }
@@ -105,7 +106,7 @@ export class AlterDomainSetNotNull extends AlterDomainChange {
     return [this.domain.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return `ALTER DOMAIN ${this.domain.schema}.${this.domain.name} SET NOT NULL`;
   }
 }
@@ -126,7 +127,7 @@ export class AlterDomainDropNotNull extends AlterDomainChange {
     return [this.domain.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return `ALTER DOMAIN ${this.domain.schema}.${this.domain.name} DROP NOT NULL`;
   }
 }
@@ -149,7 +150,7 @@ export class AlterDomainChangeOwner extends AlterDomainChange {
     return [this.domain.stableId, stableId.role(this.owner)];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return `ALTER DOMAIN ${this.domain.schema}.${this.domain.name} OWNER TO ${this.owner}`;
   }
 }
@@ -182,7 +183,7 @@ export class AlterDomainAddConstraint extends AlterDomainChange {
     return [this.domain.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const domainName = `${this.domain.schema}.${this.domain.name}`;
     const parts: string[] = [
       "ALTER DOMAIN",
@@ -235,7 +236,7 @@ export class AlterDomainDropConstraint extends DropDomainChange {
     ];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const domainName = `${this.domain.schema}.${this.domain.name}`;
     return [
       "ALTER DOMAIN",
@@ -274,7 +275,7 @@ export class AlterDomainValidateConstraint extends AlterDomainChange {
     ];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     const domainName = `${this.domain.schema}.${this.domain.name}`;
     return [
       "ALTER DOMAIN",

package/src/core/objects/domain/changes/domain.comment.ts

@@ -1,3 +1,4 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
 import { quoteLiteral } from "../../base.change.ts";
 import { stableId } from "../../utils.ts";
 import type { Domain } from "../domain.model.ts";
@@ -25,7 +26,7 @@ export class CreateCommentOnDomain extends CreateDomainChange {
     return [this.domain.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return [
       "COMMENT ON DOMAIN",
       `${this.domain.schema}.${this.domain.name}`,
@@ -49,7 +50,7 @@ export class DropCommentOnDomain extends DropDomainChange {
     return [stableId.comment(this.domain.stableId), this.domain.stableId];
   }
 
-  serialize(): string {
+  serialize(_options?: SerializeOptions): string {
     return [
       "COMMENT ON DOMAIN",
       `${this.domain.schema}.${this.domain.name}`,