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

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

@@ -0,0 +1,204 @@
+/**
+ * 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[];
+};
+
+/**
+ * Property pattern - matches against change properties.
+ * Multiple properties are combined with AND (all must match).
+ */
+type PropertyPattern = CoreProperties &
+  ExtractedProperties & {
+    // 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[];
+      or?: never;
+      not?: never;
+    } & {
+      [K in keyof CoreProperties]?: never;
+    } & {
+      [K in keyof ExtractedProperties]?: never;
+    })
+  | ({
+      or: FilterPattern[];
+      and?: never;
+      not?: never;
+    } & {
+      [K in keyof CoreProperties]?: never;
+    } & {
+      [K in keyof ExtractedProperties]?: never;
+    })
+  | ({
+      not: FilterPattern;
+      and?: never;
+      or?: never;
+    } & {
+      [K in keyof CoreProperties]?: never;
+    } & {
+      [K in keyof ExtractedProperties]?: 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 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)) {
+      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.ts

@@ -0,0 +1,145 @@
+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;
+  },
+};
+
+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;

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

@@ -0,0 +1,24 @@
+/**
+ * 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/src/core/integrations/integration.types.ts

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

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

@@ -0,0 +1,77 @@
+/**
+ * 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 { 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;
+};
+
+/**
+ * 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 function compileSerializeDSL(dsl: SerializeDSL): ChangeSerializer {
+  return (change: Change): string | undefined => {
+    // 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/src/core/integrations/serialize/serialize.types.ts

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

package/src/core/integrations/supabase.ts

@@ -0,0 +1,121 @@
+/**
+ * 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";
+
+// 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",
+] as const;
+
+// Supabase system roles that should be excluded
+const SUPABASE_SYSTEM_ROLES = [
+  "anon",
+  "authenticated",
+  "authenticator",
+  "cli_login_postgres",
+  "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",
+  "supabase_superuser",
+] as const;
+
+export const supabase: IntegrationDSL = {
+  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,
+      },
+    },
+  ],
+};