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

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

@@ -0,0 +1,211 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "../../change.types.ts";
+import { compileFilterDSL, evaluatePattern } from "./dsl.ts";
+
+const tableCreate = {
+  objectType: "table",
+  operation: "create",
+  scope: "object",
+  table: { schema: "public", name: "t" },
+  requires: ["schema:public"],
+} as unknown as Change;
+
+const viewAlter = {
+  objectType: "view",
+  operation: "alter",
+  scope: "comment",
+  view: { schema: "private", name: "v" },
+  requires: ["schema:private", "type:auth.users"],
+} as unknown as Change;
+
+const roleDrop = {
+  objectType: "role",
+  operation: "drop",
+  scope: "object",
+  role: { name: "admin" },
+  requires: [],
+} as unknown as Change;
+
+describe("evaluatePattern", () => {
+  describe("core properties", () => {
+    test("type match", () => {
+      expect(evaluatePattern({ type: "table" }, tableCreate)).toBe(true);
+    });
+
+    test("type mismatch", () => {
+      expect(evaluatePattern({ type: "view" }, tableCreate)).toBe(false);
+    });
+
+    test("operation match", () => {
+      expect(evaluatePattern({ operation: "create" }, tableCreate)).toBe(true);
+    });
+
+    test("operation mismatch", () => {
+      expect(evaluatePattern({ operation: "drop" }, tableCreate)).toBe(false);
+    });
+
+    test("scope match", () => {
+      expect(evaluatePattern({ scope: "object" }, tableCreate)).toBe(true);
+    });
+
+    test("scope mismatch", () => {
+      expect(evaluatePattern({ scope: "comment" }, tableCreate)).toBe(false);
+    });
+
+    test("multiple core properties AND together", () => {
+      expect(
+        evaluatePattern({ type: "table", operation: "create" }, tableCreate),
+      ).toBe(true);
+      expect(
+        evaluatePattern({ type: "table", operation: "drop" }, tableCreate),
+      ).toBe(false);
+    });
+
+    test("empty pattern matches everything", () => {
+      expect(evaluatePattern({}, tableCreate)).toBe(true);
+      expect(evaluatePattern({}, roleDrop)).toBe(true);
+    });
+  });
+
+  describe("composition patterns", () => {
+    test("not negates a pattern", () => {
+      expect(evaluatePattern({ not: { type: "table" } }, tableCreate)).toBe(
+        false,
+      );
+      expect(evaluatePattern({ not: { type: "view" } }, tableCreate)).toBe(
+        true,
+      );
+    });
+
+    test("and requires all to match", () => {
+      expect(
+        evaluatePattern(
+          { and: [{ type: "table" }, { operation: "create" }] },
+          tableCreate,
+        ),
+      ).toBe(true);
+      expect(
+        evaluatePattern(
+          { and: [{ type: "table" }, { operation: "drop" }] },
+          tableCreate,
+        ),
+      ).toBe(false);
+    });
+
+    test("or requires any to match", () => {
+      expect(
+        evaluatePattern(
+          { or: [{ type: "table" }, { type: "view" }] },
+          tableCreate,
+        ),
+      ).toBe(true);
+      expect(
+        evaluatePattern(
+          { or: [{ type: "role" }, { type: "view" }] },
+          tableCreate,
+        ),
+      ).toBe(false);
+    });
+
+    test("nested composition", () => {
+      expect(
+        evaluatePattern(
+          { not: { or: [{ type: "role" }, { type: "view" }] } },
+          tableCreate,
+        ),
+      ).toBe(true);
+    });
+  });
+
+  describe("requiresMatching", () => {
+    test("prefix match on requires array", () => {
+      expect(
+        evaluatePattern({ requiresMatching: ["schema:public"] }, tableCreate),
+      ).toBe(true);
+      expect(
+        evaluatePattern({ requiresMatching: ["schema:"] }, tableCreate),
+      ).toBe(true);
+    });
+
+    test("no match when prefix absent", () => {
+      expect(
+        evaluatePattern({ requiresMatching: ["type:auth."] }, tableCreate),
+      ).toBe(false);
+    });
+
+    test("matches when any prefix matches any requires entry", () => {
+      expect(
+        evaluatePattern({ requiresMatching: ["type:auth."] }, viewAlter),
+      ).toBe(true);
+    });
+
+    test("no match when requires is empty", () => {
+      expect(evaluatePattern({ requiresMatching: ["schema:"] }, roleDrop)).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("extracted properties", () => {
+    test("schema as string exact match", () => {
+      expect(evaluatePattern({ schema: "public" }, tableCreate)).toBe(true);
+      expect(evaluatePattern({ schema: "private" }, tableCreate)).toBe(false);
+    });
+
+    test("schema as array checks inclusion", () => {
+      expect(
+        evaluatePattern({ schema: ["public", "private"] }, tableCreate),
+      ).toBe(true);
+      expect(
+        evaluatePattern({ schema: ["private", "auth"] }, tableCreate),
+      ).toBe(false);
+    });
+
+    test("null extracted value returns false", () => {
+      expect(evaluatePattern({ schema: "public" }, roleDrop)).toBe(false);
+    });
+
+    test("unknown property key is ignored", () => {
+      const pattern = { unknownKey: "value" } as Record<string, unknown>;
+      expect(
+        evaluatePattern(
+          pattern as Parameters<typeof evaluatePattern>[0],
+          tableCreate,
+        ),
+      ).toBe(true);
+    });
+
+    test("cascade property is ignored and does not affect match", () => {
+      expect(
+        evaluatePattern({ type: "table", cascade: true }, tableCreate),
+      ).toBe(true);
+      expect(
+        evaluatePattern({ type: "table", cascade: false }, tableCreate),
+      ).toBe(true);
+      expect(
+        evaluatePattern(
+          { not: { schema: "auth" }, cascade: true },
+          tableCreate,
+        ),
+      ).toBe(true);
+    });
+  });
+});
+
+describe("compileFilterDSL", () => {
+  test("returns a function that evaluates the pattern", () => {
+    const filter = compileFilterDSL({ type: "table" });
+    expect(typeof filter).toBe("function");
+    expect(filter(tableCreate)).toBe(true);
+    expect(filter(roleDrop)).toBe(false);
+  });
+
+  test("works with composition patterns", () => {
+    const filter = compileFilterDSL({
+      or: [{ type: "table" }, { type: "role" }],
+    });
+    expect(filter(tableCreate)).toBe(true);
+    expect(filter(roleDrop)).toBe(true);
+    expect(filter(viewAlter)).toBe(false);
+  });
+});

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

@@ -23,6 +23,30 @@ type ExtractedProperties = {
   schema?: string | string[];
   owner?: string | string[];
   member?: string | string[];
+  grantee?: string | string[];
+  publication?: string | string[];
+  extension?: string | string[];
+  procedureLanguage?: string | string[];
+  eventTriggerName?: string | string[];
+  procedureBinaryPath?: string | string[];
+  triggerFunctionSchema?: string | string[];
+};
+
+/**
+ * Special properties that use custom matching logic (not extractor-based).
+ */
+type SpecialProperties = {
+  /**
+   * Prefix match on `change.requires`.
+   * Matches when any element of `change.requires` starts with any of the given prefixes.
+   * Useful for excluding changes that depend on specific schemas/types.
+   *
+   * @example Filter out changes that require auth or extensions types:
+   * ```ts
+   * { not: { requiresMatching: ["type:auth.", "type:extensions."] } }
+   * ```
+   */
+  requiresMatching?: string[];
 };
 
 /**
@@ -30,7 +54,13 @@ type ExtractedProperties = {
  * Multiple properties are combined with AND (all must match).
  */
 type PropertyPattern = CoreProperties &
-  ExtractedProperties & {
+  ExtractedProperties &
+  SpecialProperties & {
+    /**
+     * When true, exclusions from this filter cascade to dependents (requires/pg_depend).
+     * Default false for DSL filters (opt-in).
+     */
+    cascade?: boolean;
     // Composition operators are NOT allowed in property patterns
     and?: never;
     or?: never;
@@ -44,30 +74,39 @@ type PropertyPattern = CoreProperties &
 type CompositionPattern =
   | ({
       and: FilterPattern[];
+      cascade?: boolean;
       or?: never;
       not?: never;
     } & {
       [K in keyof CoreProperties]?: never;
     } & {
       [K in keyof ExtractedProperties]?: never;
+    } & {
+      [K in keyof SpecialProperties]?: never;
     })
   | ({
       or: FilterPattern[];
+      cascade?: boolean;
       and?: never;
       not?: never;
     } & {
       [K in keyof CoreProperties]?: never;
     } & {
       [K in keyof ExtractedProperties]?: never;
+    } & {
+      [K in keyof SpecialProperties]?: never;
     })
   | ({
       not: FilterPattern;
+      cascade?: boolean;
       and?: never;
       or?: never;
     } & {
       [K in keyof CoreProperties]?: never;
     } & {
       [K in keyof ExtractedProperties]?: never;
+    } & {
+      [K in keyof SpecialProperties]?: never;
     });
 
 /**
@@ -135,10 +174,33 @@ export function evaluatePattern(
     }
   }
 
+  // Match requiresMatching (special property - prefix match on change.requires)
+  if (pattern.requiresMatching) {
+    const requires = change.requires ?? [];
+    const prefixes = pattern.requiresMatching;
+    const hasMatch = requires.some((r) =>
+      prefixes.some((p) => r.startsWith(p)),
+    );
+    if (!hasMatch) {
+      return false;
+    }
+  }
+
   // Match extracted properties
   for (const [key, value] of Object.entries(pattern)) {
-    // Skip composition operators and core properties
-    if (["and", "or", "not", "type", "operation", "scope"].includes(key)) {
+    // Skip composition operators, core properties, special properties, and cascade
+    if (
+      [
+        "and",
+        "or",
+        "not",
+        "type",
+        "operation",
+        "scope",
+        "requiresMatching",
+        "cascade",
+      ].includes(key)
+    ) {
       continue;
     }
 

package/src/core/integrations/filter/extractors.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "../../change.types.ts";
+import { getSchema, PROPERTY_EXTRACTORS } from "./extractors.ts";
+
+describe("getSchema", () => {
+  test("returns schema for table", () => {
+    const change = {
+      objectType: "table",
+      table: { schema: "public" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("public");
+  });
+
+  test("returns schema for view", () => {
+    const change = {
+      objectType: "view",
+      view: { schema: "app" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("app");
+  });
+
+  test("returns schema for enum", () => {
+    const change = {
+      objectType: "enum",
+      enum: { schema: "types" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("types");
+  });
+
+  test("returns schema.name for schema type", () => {
+    const change = {
+      objectType: "schema",
+      schema: { name: "auth" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("auth");
+  });
+
+  test("returns null for role", () => {
+    const change = {
+      objectType: "role",
+      role: { name: "admin" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+
+  test("returns null for publication", () => {
+    const change = {
+      objectType: "publication",
+      publication: { name: "pub1" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+
+  test("returns null for language", () => {
+    const change = {
+      objectType: "language",
+      language: { name: "plpgsql" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+});
+
+describe("owner extractor", () => {
+  const getOwner = PROPERTY_EXTRACTORS.owner;
+
+  test("returns owner for table", () => {
+    const change = {
+      objectType: "table",
+      table: { owner: "postgres" },
+    } as unknown as Change;
+    expect(getOwner(change)).toBe("postgres");
+  });
+
+  test("returns owner for schema", () => {
+    const change = {
+      objectType: "schema",
+      schema: { owner: "admin" },
+    } as unknown as Change;
+    expect(getOwner(change)).toBe("admin");
+  });
+
+  test("returns role.name for role type", () => {
+    const change = {
+      objectType: "role",
+      role: { name: "supabase_admin" },
+    } as unknown as Change;
+    expect(getOwner(change)).toBe("supabase_admin");
+  });
+
+  test("returns null for user_mapping", () => {
+    const change = { objectType: "user_mapping" } as unknown as Change;
+    expect(getOwner(change)).toBeNull();
+  });
+});
+
+describe("PROPERTY_EXTRACTORS", () => {
+  test("has all expected keys", () => {
+    const expectedKeys = [
+      "schema",
+      "owner",
+      "member",
+      "grantee",
+      "publication",
+      "extension",
+      "procedureLanguage",
+      "eventTriggerName",
+      "procedureBinaryPath",
+      "triggerFunctionSchema",
+    ];
+    expect(Object.keys(PROPERTY_EXTRACTORS).sort()).toEqual(
+      expectedKeys.sort(),
+    );
+  });
+
+  describe("member", () => {
+    test("returns member for membership scope", () => {
+      const change = {
+        scope: "membership",
+        member: "app_user",
+      } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.member(change)).toBe("app_user");
+    });
+
+    test("returns null for non-membership scope", () => {
+      const change = { scope: "object" } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.member(change)).toBeNull();
+    });
+  });
+
+  describe("grantee", () => {
+    test("returns grantee for privilege scope", () => {
+      const change = {
+        scope: "privilege",
+        grantee: "reader",
+      } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.grantee(change)).toBe("reader");
+    });
+
+    test("returns null for non-privilege scope", () => {
+      const change = { scope: "object" } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.grantee(change)).toBeNull();
+    });
+  });
+
+  describe("publication", () => {
+    test("returns name for publication type", () => {
+      const change = {
+        objectType: "publication",
+        publication: { name: "my_pub" },
+      } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.publication(change)).toBe("my_pub");
+    });
+
+    test("returns null for non-publication type", () => {
+      const change = { objectType: "table" } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.publication(change)).toBeNull();
+    });
+  });
+
+  describe("extension", () => {
+    test("returns name for extension type", () => {
+      const change = {
+        objectType: "extension",
+        extension: { name: "pgcrypto" },
+      } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.extension(change)).toBe("pgcrypto");
+    });
+
+    test("returns null for non-extension type", () => {
+      const change = { objectType: "table" } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.extension(change)).toBeNull();
+    });
+  });
+
+  describe("procedureLanguage", () => {
+    test("returns language for procedure type", () => {
+      const change = {
+        objectType: "procedure",
+        procedure: { language: "plpgsql" },
+      } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.procedureLanguage(change)).toBe("plpgsql");
+    });
+
+    test("returns null for non-procedure type", () => {
+      const change = { objectType: "table" } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.procedureLanguage(change)).toBeNull();
+    });
+  });
+
+  describe("eventTriggerName", () => {
+    test("returns name for event_trigger type", () => {
+      const change = {
+        objectType: "event_trigger",
+        eventTrigger: { name: "my_trigger" },
+      } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.eventTriggerName(change)).toBe("my_trigger");
+    });
+
+    test("returns null for non-event_trigger type", () => {
+      const change = { objectType: "table" } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.eventTriggerName(change)).toBeNull();
+    });
+  });
+
+  describe("procedureBinaryPath", () => {
+    test("returns binary_path for procedure type", () => {
+      const change = {
+        objectType: "procedure",
+        procedure: { binary_path: "/usr/bin/pg" },
+      } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.procedureBinaryPath(change)).toBe(
+        "/usr/bin/pg",
+      );
+    });
+
+    test("returns null when binary_path is undefined", () => {
+      const change = {
+        objectType: "procedure",
+        procedure: {},
+      } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.procedureBinaryPath(change)).toBeNull();
+    });
+
+    test("returns null for non-procedure type", () => {
+      const change = { objectType: "table" } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.procedureBinaryPath(change)).toBeNull();
+    });
+  });
+
+  describe("triggerFunctionSchema", () => {
+    test("returns function_schema for trigger type", () => {
+      const change = {
+        objectType: "trigger",
+        trigger: { function_schema: "public" },
+      } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.triggerFunctionSchema(change)).toBe("public");
+    });
+
+    test("returns null for non-trigger type", () => {
+      const change = { objectType: "table" } as unknown as Change;
+      expect(PROPERTY_EXTRACTORS.triggerFunctionSchema(change)).toBeNull();
+    });
+  });
+});

package/src/core/integrations/filter/extractors.ts

@@ -18,6 +18,48 @@ export const PROPERTY_EXTRACTORS: Record<string, PropertyExtractor> = {
     }
     return null;
   },
+  grantee: (change: Change) => {
+    if (change.scope === "privilege" && "grantee" in change) {
+      return change.grantee;
+    }
+    return null;
+  },
+  publication: (change: Change) => {
+    if (change.objectType === "publication") {
+      return change.publication.name;
+    }
+    return null;
+  },
+  extension: (change: Change) => {
+    if (change.objectType === "extension") {
+      return change.extension.name;
+    }
+    return null;
+  },
+  procedureLanguage: (change: Change) => {
+    if (change.objectType === "procedure") {
+      return change.procedure.language;
+    }
+    return null;
+  },
+  eventTriggerName: (change: Change) => {
+    if (change.objectType === "event_trigger") {
+      return change.eventTrigger.name;
+    }
+    return null;
+  },
+  procedureBinaryPath: (change: Change) => {
+    if (change.objectType === "procedure") {
+      return change.procedure.binary_path ?? null;
+    }
+    return null;
+  },
+  triggerFunctionSchema: (change: Change) => {
+    if (change.objectType === "trigger") {
+      return change.trigger.function_schema;
+    }
+    return null;
+  },
 };
 
 export function getSchema(change: Change) {

package/src/core/integrations/integration-dsl.ts

@@ -4,6 +4,7 @@
  * Combines filter and serialization DSLs into a single serializable structure.
  */
 
+import type { CatalogSnapshot } from "../catalog.snapshot.ts";
 import type { FilterDSL } from "./filter/dsl.ts";
 import type { SerializeDSL } from "./serialize/dsl.ts";
 
@@ -21,4 +22,13 @@ export type IntegrationDSL = {
    * If not provided, changes are serialized with default options.
    */
   serialize?: SerializeDSL;
+  /**
+   * Baseline catalog snapshot for this integration.
+   *
+   * When `--source` is omitted, this snapshot is deserialized and used as the
+   * source catalog instead of `createEmptyCatalog`. This lets integrations
+   * define what "empty" means for their platform (e.g. Supabase ships with
+   * pre-existing schemas, extensions, and roles).
+   */
+  emptyCatalog?: CatalogSnapshot;
 };