@supabase/pg-delta 1.0.0-alpha.2 → 1.0.0-alpha.20

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

@@ -0,0 +1,305 @@
+/**
+ * Filter DSL - A serializable domain-specific language for change filtering.
+ *
+ * Uses wildcard-based path matching on flattened change properties.
+ * Path patterns as keys, values as matchers. Multiple keys in one object = AND.
+ *
+ * Path convention:
+ * - Top-level change properties are bare keys: `objectType`, `operation`, `scope`, `member`, `grantee`
+ * - Model sub-object properties use `<objectType>/<field>`: `table/schema`, `role/name`
+ * - Wildcard `*` matches any single path segment: `* /schema` → `table/schema`, `view/schema`, etc.
+ * - Separator is `/`
+ *
+ * Value matching:
+ * - string → exact equality
+ * - string[] → value must be in array (inclusion)
+ * - boolean → exact equality
+ * - number → exact equality
+ * - { op: "regex", value: string | string[] } → regex test
+ *
+ * When the flat value is an array (e.g. `requires`), match succeeds if any element satisfies.
+ */
+
+import type { Change } from "../../change.types.ts";
+import type { ChangeFilter } from "./filter.types.ts";
+import { compileWildcard, type FlatValue, flattenChange } from "./flatten.ts";
+
+/**
+ * Regex operator for advanced value matching.
+ */
+type RegexOperator = {
+  op: "regex";
+  value: string | string[];
+};
+
+/**
+ * A value matcher for a path pattern key.
+ */
+type ValueMatcher = string | string[] | boolean | number | RegexOperator;
+
+/**
+ * Path pattern — matches against flattened change properties.
+ * Keys are path patterns (with optional wildcards), values are matchers.
+ * Multiple keys are combined with AND (all must match).
+ *
+ * Reserved keys: `and`, `or`, `not`, `cascade`.
+ *
+ * @example
+ * ```json
+ * { "objectType": "table", "operation": "create" }
+ * ```
+ *
+ * @example Wildcard path matching any object's schema
+ * ```json
+ * { "* /schema": "public" }
+ * ```
+ *
+ * @category Filter DSL
+ */
+export type PathPattern = {
+  [path: string]: ValueMatcher;
+} & {
+  cascade?: boolean;
+  and?: never;
+  or?: never;
+  not?: never;
+};
+
+/**
+ * Composition pattern - combines other patterns using logical operators.
+ * Composition operators are exclusive - cannot be mixed with path keys.
+ */
+type CompositionPattern =
+  | {
+      and: FilterPattern[];
+      cascade?: boolean;
+      or?: never;
+      not?: never;
+    }
+  | {
+      or: FilterPattern[];
+      cascade?: boolean;
+      and?: never;
+      not?: never;
+    }
+  | {
+      not: FilterPattern;
+      cascade?: boolean;
+      and?: never;
+      or?: never;
+    };
+
+/**
+ * A single filter expression: either a {@link PathPattern} that matches against
+ * flattened change properties, or a composition pattern that combines other
+ * patterns using `and` / `or` / `not` logical operators.
+ *
+ * @example Exclude all changes in pg_catalog
+ * ```json
+ * { "not": { "* /schema": "pg_catalog" } }
+ * ```
+ *
+ * @category Filter DSL
+ */
+export type FilterPattern = PathPattern | CompositionPattern;
+
+/**
+ * Top-level Filter DSL type — a single {@link FilterPattern} expression that
+ * determines which changes an integration includes or excludes.
+ *
+ * @example Include only table and view creates in public
+ * ```json
+ * {
+ *   "and": [
+ *     { "objectType": ["table", "view"] },
+ *     { "operation": "create" },
+ *     { "* /schema": "public" }
+ *   ]
+ * }
+ * ```
+ *
+ * @category Filter DSL
+ */
+export type FilterDSL = FilterPattern;
+
+// Reserved keys that are not path patterns
+const RESERVED_KEYS = new Set(["and", "or", "not", "cascade"]);
+
+/**
+ * Match a flat value against a value matcher.
+ *
+ * When the flat value is an array, the match succeeds if any element satisfies.
+ */
+function matchValue(actual: FlatValue, expected: ValueMatcher): boolean {
+  if (actual === null || actual === undefined) {
+    return false;
+  }
+
+  // String matcher → exact equality
+  if (typeof expected === "string") {
+    if (Array.isArray(actual)) {
+      return actual.some((v) => v === expected);
+    }
+    return actual === expected;
+  }
+
+  // Boolean matcher → exact equality
+  if (typeof expected === "boolean") {
+    return actual === expected;
+  }
+
+  // Number matcher → exact equality
+  if (typeof expected === "number") {
+    return actual === expected;
+  }
+
+  // Array matcher → inclusion (value must be in array)
+  if (Array.isArray(expected)) {
+    if (Array.isArray(actual)) {
+      return actual.some((v) =>
+        (expected as ReadonlyArray<string | number>).includes(v),
+      );
+    }
+    return typeof actual === "string" && expected.includes(actual);
+  }
+
+  // Regex operator
+  if (
+    typeof expected === "object" &&
+    expected !== null &&
+    "op" in expected &&
+    expected.op === "regex"
+  ) {
+    const patterns = Array.isArray(expected.value)
+      ? expected.value
+      : [expected.value];
+    if (Array.isArray(actual)) {
+      return actual.some((a) =>
+        patterns.some((p) => new RegExp(p).test(String(a))),
+      );
+    }
+    return patterns.some((p) => new RegExp(p).test(String(actual)));
+  }
+
+  return false;
+}
+
+/**
+ * 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 ("not" in pattern && pattern.not) {
+    return !evaluatePattern(pattern.not, change);
+  }
+
+  // AND operator - all patterns must match
+  if ("and" in pattern && pattern.and) {
+    return pattern.and.every((p) => evaluatePattern(p, change));
+  }
+
+  // OR operator - any pattern must match
+  if ("or" in pattern && pattern.or) {
+    return pattern.or.some((p) => evaluatePattern(p, change));
+  }
+
+  // Path pattern matching: flatten the change, then for each key in the pattern,
+  // wildcard-match against flat map paths and compare values.
+  const flat = flattenChange(change);
+
+  for (const [patternKey, matcher] of Object.entries(pattern)) {
+    if (RESERVED_KEYS.has(patternKey)) continue;
+
+    const wildcardMatcher = compileWildcard(patternKey);
+
+    // Find all flat keys that match this wildcard pattern
+    const matchingKeys = Object.keys(flat).filter((k) => wildcardMatcher(k));
+
+    if (matchingKeys.length === 0) {
+      // No flat keys match this wildcard → pattern key not satisfied
+      return false;
+    }
+
+    // At least one matching key must satisfy the value matcher
+    const anyMatch = matchingKeys.some((k) =>
+      matchValue(flat[k], matcher as ValueMatcher),
+    );
+    if (!anyMatch) return false;
+  }
+
+  // All pattern keys satisfied
+  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
+ * ```
+ * const filter = compileFilterDSL({
+ *   or: [
+ *     { objectType: "schema", operation: "create" },
+ *     { "table/schema": "public" }
+ *   ]
+ * });
+ * ```
+ */
+export function compileFilterDSL(dsl: FilterDSL): ChangeFilter {
+  validateRegexPatterns(dsl);
+  return (change: Change): boolean => {
+    return evaluatePattern(dsl, change);
+  };
+}
+
+/**
+ * Walk the pattern tree and validate all regex patterns at compile time.
+ * Throws a descriptive error if any regex pattern is invalid.
+ */
+function validateRegexPatterns(pattern: FilterPattern): void {
+  if ("not" in pattern && pattern.not) {
+    validateRegexPatterns(pattern.not);
+    return;
+  }
+  if ("and" in pattern && pattern.and) {
+    for (const p of pattern.and) validateRegexPatterns(p);
+    return;
+  }
+  if ("or" in pattern && pattern.or) {
+    for (const p of pattern.or) validateRegexPatterns(p);
+    return;
+  }
+
+  for (const [key, value] of Object.entries(pattern)) {
+    if (RESERVED_KEYS.has(key)) continue;
+    if (
+      typeof value === "object" &&
+      value !== null &&
+      !Array.isArray(value) &&
+      "op" in value &&
+      value.op === "regex"
+    ) {
+      const patterns = Array.isArray(value.value) ? value.value : [value.value];
+      for (const p of patterns) {
+        try {
+          new RegExp(p);
+        } catch (e) {
+          throw new Error(
+            `Invalid regex pattern "${p}" in filter DSL: ${(e as Error).message}`,
+          );
+        }
+      }
+    }
+  }
+}

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;

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

@@ -0,0 +1,282 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "../../change.types.ts";
+import { compileWildcard, flattenChange } from "./flatten.ts";
+
+describe("flattenChange", () => {
+  test("flattens top-level scalar properties", () => {
+    const change = {
+      objectType: "table",
+      operation: "create",
+      scope: "object",
+      table: { schema: "public", name: "users" },
+      requires: ["schema:public"],
+      creates: ["table:public.users"],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat.objectType).toBe("table");
+    expect(flat.operation).toBe("create");
+    expect(flat.scope).toBe("object");
+  });
+
+  test("flattens array properties", () => {
+    const change = {
+      objectType: "table",
+      operation: "create",
+      scope: "object",
+      table: { schema: "public", name: "users" },
+      requires: ["schema:public", "role:postgres"],
+      creates: ["table:public.users"],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat.requires).toEqual(["schema:public", "role:postgres"]);
+    expect(flat.creates).toEqual(["table:public.users"]);
+  });
+
+  test("flattens model sub-object properties with objectType prefix", () => {
+    const change = {
+      objectType: "table",
+      operation: "create",
+      scope: "object",
+      table: {
+        schema: "public",
+        name: "users",
+        owner: "postgres",
+        is_partition: false,
+        persistence: "p",
+      },
+      requires: [],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat["table/schema"]).toBe("public");
+    expect(flat["table/name"]).toBe("users");
+    expect(flat["table/owner"]).toBe("postgres");
+    expect(flat["table/is_partition"]).toBe(false);
+    expect(flat["table/persistence"]).toBe("p");
+  });
+
+  test("includes member when present", () => {
+    const change = {
+      objectType: "role",
+      operation: "create",
+      scope: "membership",
+      member: "app_user",
+      role: { name: "admin" },
+      requires: [],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat.member).toBe("app_user");
+  });
+
+  test("includes grantee when present", () => {
+    const change = {
+      objectType: "table",
+      operation: "create",
+      scope: "privilege",
+      grantee: "reader",
+      table: { schema: "public", name: "users" },
+      requires: [],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat.grantee).toBe("reader");
+  });
+
+  test("skips nested objects", () => {
+    const change = {
+      objectType: "table",
+      operation: "create",
+      scope: "object",
+      table: {
+        schema: "public",
+        name: "users",
+        columns: [{ name: "id", type: "integer" }],
+        constraints: { pk: { type: "primary_key" } },
+      },
+      requires: [],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat["table/columns"]).toBeUndefined();
+    expect(flat["table/constraints"]).toBeUndefined();
+  });
+
+  test("handles null model property values", () => {
+    const change = {
+      objectType: "procedure",
+      operation: "create",
+      scope: "object",
+      procedure: {
+        schema: "public",
+        name: "my_func",
+        binary_path: null,
+        language: "plpgsql",
+      },
+      requires: [],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat["procedure/binary_path"]).toBeNull();
+    expect(flat["procedure/language"]).toBe("plpgsql");
+  });
+
+  test("defaults requires/creates/drops to empty arrays", () => {
+    const change = {
+      objectType: "role",
+      operation: "create",
+      scope: "object",
+      role: { name: "admin" },
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat.requires).toEqual([]);
+    expect(flat.creates).toEqual([]);
+    expect(flat.drops).toEqual([]);
+  });
+
+  test("normalizes schema/schema for schema changes", () => {
+    const change = {
+      objectType: "schema",
+      operation: "create",
+      scope: "object",
+      schema: { name: "auth" },
+      requires: [],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat["schema/name"]).toBe("auth");
+    expect(flat["schema/schema"]).toBe("auth");
+  });
+
+  test("normalizes event_trigger/schema from function_schema", () => {
+    const change = {
+      objectType: "event_trigger",
+      operation: "create",
+      scope: "object",
+      eventTrigger: {
+        name: "my_trigger",
+        function_schema: "public",
+        function_name: "my_func",
+      },
+      requires: [],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat["event_trigger/function_schema"]).toBe("public");
+    expect(flat["event_trigger/schema"]).toBe("public");
+  });
+
+  test("flattens rls_policy model properties (camelCase mapping)", () => {
+    const change = {
+      objectType: "rls_policy",
+      operation: "create",
+      scope: "object",
+      policy: { schema: "public", table: "users", name: "select_policy" },
+      requires: [],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat["rls_policy/schema"]).toBe("public");
+    expect(flat["rls_policy/table"]).toBe("users");
+    expect(flat["rls_policy/name"]).toBe("select_policy");
+  });
+
+  test("flattens all top-level scalar properties systematically", () => {
+    const change = {
+      objectType: "role",
+      operation: "create",
+      scope: "membership",
+      member: "app_user",
+      role: { name: "admin" },
+      requires: [],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat.member).toBe("app_user");
+  });
+
+  test("flattens inSchema for default_privilege changes", () => {
+    const change = {
+      objectType: "role",
+      operation: "create",
+      scope: "default_privilege",
+      inSchema: "public",
+      objtype: "table",
+      role: { name: "admin" },
+      requires: [],
+    } as unknown as Change;
+
+    const flat = flattenChange(change);
+    expect(flat.inSchema).toBe("public");
+    expect(flat.objtype).toBe("table");
+    expect(flat["role/schema"]).toBe("public");
+  });
+
+  test("caches results (returns same reference)", () => {
+    const change = {
+      objectType: "table",
+      operation: "create",
+      scope: "object",
+      table: { schema: "public", name: "t" },
+      requires: [],
+    } as unknown as Change;
+
+    const flat1 = flattenChange(change);
+    const flat2 = flattenChange(change);
+    expect(flat1).toBe(flat2);
+  });
+});
+
+describe("compileWildcard", () => {
+  test("exact match on bare key", () => {
+    const matcher = compileWildcard("objectType");
+    expect(matcher("objectType")).toBe(true);
+    expect(matcher("operation")).toBe(false);
+    expect(matcher("table/objectType")).toBe(false);
+  });
+
+  test("exact match on path key", () => {
+    const matcher = compileWildcard("table/schema");
+    expect(matcher("table/schema")).toBe(true);
+    expect(matcher("view/schema")).toBe(false);
+    expect(matcher("table/name")).toBe(false);
+  });
+
+  test("wildcard matches any single segment", () => {
+    const matcher = compileWildcard("*/schema");
+    expect(matcher("table/schema")).toBe(true);
+    expect(matcher("view/schema")).toBe(true);
+    expect(matcher("aggregate/schema")).toBe(true);
+    expect(matcher("schema")).toBe(false);
+    expect(matcher("a/b/schema")).toBe(false);
+  });
+
+  test("does not match different segment count", () => {
+    const matcher = compileWildcard("*/schema");
+    expect(matcher("objectType")).toBe(false);
+  });
+
+  test("brace expansion matches multiple alternatives", () => {
+    const matcher = compileWildcard("{table,view}/schema");
+    expect(matcher("table/schema")).toBe(true);
+    expect(matcher("view/schema")).toBe(true);
+    expect(matcher("role/schema")).toBe(false);
+  });
+
+  test("partial wildcard matches prefix", () => {
+    const matcher = compileWildcard("table/is_*");
+    expect(matcher("table/is_partition")).toBe(true);
+    expect(matcher("table/is_typed")).toBe(true);
+    expect(matcher("table/name")).toBe(false);
+  });
+
+  test("extglob negation excludes specific segment", () => {
+    const matcher = compileWildcard("!(role)/schema");
+    expect(matcher("table/schema")).toBe(true);
+    expect(matcher("view/schema")).toBe(true);
+    expect(matcher("role/schema")).toBe(false);
+  });
+});