@supabase/pg-delta 1.0.0-alpha.3 → 1.0.0-alpha.5

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

@@ -0,0 +1,266 @@
+/**
+ * Filter DSL - A serializable domain-specific language for change filtering.
+ */
+
+import type { Change } from "../../change.types.ts";
+import { PROPERTY_EXTRACTORS } from "./extractors.ts";
+import type { ChangeFilter } from "./filter.types.ts";
+
+/**
+ * Core properties that all changes have.
+ */
+type CoreProperties = {
+  type?: Change["objectType"];
+  operation?: "create" | "alter" | "drop";
+  scope?: Change["scope"];
+};
+
+/**
+ * Extracted properties that are extracted from changes via extractor functions.
+ * String value = exact match, Array value = value must be in array
+ */
+type ExtractedProperties = {
+  schema?: string | string[];
+  owner?: string | string[];
+  member?: string | string[];
+  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[];
+};
+
+/**
+ * Property pattern - matches against change properties.
+ * Multiple properties are combined with AND (all must match).
+ */
+type PropertyPattern = CoreProperties &
+  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;
+    not?: never;
+  };
+
+/**
+ * Composition pattern - combines other patterns using logical operators.
+ * Composition operators are exclusive - cannot be mixed with properties.
+ */
+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;
+    });
+
+/**
+ * Filter pattern DSL.
+ * Either a property pattern (matches against change properties) or
+ * a composition pattern (combines other patterns using logical operators).
+ * Composition operators are exclusive - cannot be mixed with properties.
+ */
+export type FilterPattern = PropertyPattern | CompositionPattern;
+
+/**
+ * Filter DSL - a single pattern expression.
+ */
+export type FilterDSL = FilterPattern;
+
+/**
+ * Evaluate a pattern against a change.
+ *
+ * @param pattern - The pattern to evaluate
+ * @param change - The change to match against
+ * @returns true if the pattern matches, false otherwise
+ */
+export function evaluatePattern(
+  pattern: FilterPattern,
+  change: Change,
+): boolean {
+  // Handle composition operators first (they take precedence)
+
+  // NOT operator - negate the result
+  if (pattern.not) {
+    return !evaluatePattern(pattern.not, change);
+  }
+
+  // AND operator - all patterns must match
+  if (pattern.and) {
+    return pattern.and.every((p) => evaluatePattern(p, change));
+  }
+
+  // OR operator - any pattern must match
+  if (pattern.or) {
+    return pattern.or.some((p) => evaluatePattern(p, change));
+  }
+
+  // Evaluate basic pattern matching
+  // Multiple properties in a pattern are combined with AND (all must match)
+
+  // Match objectType
+  if (pattern.type) {
+    if (change.objectType !== pattern.type) {
+      return false;
+    }
+  }
+
+  // Match operation
+  if (pattern.operation) {
+    if (change.operation !== pattern.operation) {
+      return false;
+    }
+  }
+
+  // Match scope
+  if (pattern.scope) {
+    if (change.scope !== pattern.scope) {
+      return false;
+    }
+  }
+
+  // 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, core properties, special properties, and cascade
+    if (
+      [
+        "and",
+        "or",
+        "not",
+        "type",
+        "operation",
+        "scope",
+        "requiresMatching",
+        "cascade",
+      ].includes(key)
+    ) {
+      continue;
+    }
+
+    // Check if this is a registered property extractor
+    const extractor = PROPERTY_EXTRACTORS[key];
+    if (!extractor) {
+      // Unknown property - ignore
+      continue;
+    }
+
+    // Extract the actual value from the change
+    const actualValue = extractor(change);
+
+    // Property matching rules:
+    // - String value: exact match
+    // - Array value: value must be in array
+    // - Missing properties (null) don't match
+
+    if (actualValue === null) {
+      return false;
+    }
+
+    if (typeof value === "string") {
+      // Exact match
+      if (actualValue !== value) {
+        return false;
+      }
+    } else if (Array.isArray(value)) {
+      // Value must be in array
+      if (!value.includes(actualValue)) {
+        return false;
+      }
+    } else {
+      // Invalid value type - don't match
+      return false;
+    }
+  }
+
+  // All checks passed
+  return true;
+}
+
+/**
+ * Compile a Filter DSL to a ChangeFilter function.
+ *
+ * @param dsl - The filter DSL pattern
+ * @returns A ChangeFilter function that evaluates the pattern
+ *
+ * @example
+ * ```ts
+ * const filter = compileFilterDSL({
+ *   or: [
+ *     { type: "schema", operation: "create" },
+ *     { schema: "public" }
+ *   ]
+ * });
+ * ```
+ */
+export function compileFilterDSL(dsl: FilterDSL): ChangeFilter {
+  return (change: Change): boolean => {
+    return evaluatePattern(dsl, change);
+  };
+}

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

@@ -0,0 +1,187 @@
+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 const PROPERTY_EXTRACTORS: Record<string, PropertyExtractor> = {
+  schema: getSchema,
+  owner: getOwner,
+  member: (change: Change) => {
+    if (change.scope === "membership") {
+      return change.member;
+    }
+    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) {
+  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: never = change;
+      return _exhaustive;
+    }
+  }
+}
+
+function getOwner(change: 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: never = change;
+      return _exhaustive;
+    }
+  }
+}

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

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