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

package/dist/core/integrations/filter/dsl.d.ts

@@ -1,57 +1,59 @@
 /**
  * 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";
 /**
- * Core properties that all changes have.
+ * Regex operator for advanced value matching.
  */
-type CoreProperties = {
-    type?: Change["objectType"];
-    operation?: "create" | "alter" | "drop";
-    scope?: Change["scope"];
+type RegexOperator = {
+    op: "regex";
+    value: string | string[];
 };
 /**
- * Extracted properties that are extracted from changes via extractor functions.
- * String value = exact match, Array value = value must be in array
+ * A value matcher for a path pattern key.
  */
-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[];
-};
+type ValueMatcher = string | string[] | boolean | number | RegexOperator;
 /**
- * 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).
+ * 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
  */
-type PropertyPattern = CoreProperties & ExtractedProperties & SpecialProperties & {
-    /**
-     * When true, exclusions from this filter cascade to dependents (requires/pg_depend).
-     * Default false for DSL filters (opt-in).
-     */
+export type PathPattern = {
+    [path: string]: ValueMatcher;
+} & {
     cascade?: boolean;
     and?: never;
     or?: never;
@@ -59,51 +61,53 @@ type PropertyPattern = CoreProperties & ExtractedProperties & SpecialProperties
 };
 /**
  * Composition pattern - combines other patterns using logical operators.
- * Composition operators are exclusive - cannot be mixed with properties.
+ * Composition operators are exclusive - cannot be mixed with path keys.
  */
-type CompositionPattern = ({
+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.
+ * 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 = PropertyPattern | CompositionPattern;
+export type FilterPattern = PathPattern | CompositionPattern;
 /**
- * Filter DSL - a single pattern expression.
+ * 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;
 /**
@@ -121,11 +125,11 @@ export declare function evaluatePattern(pattern: FilterPattern, change: Change):
  * @returns A ChangeFilter function that evaluates the pattern
  *
  * @example
- * ```ts
+ * ```
  * const filter = compileFilterDSL({
  *   or: [
- *     { type: "schema", operation: "create" },
- *     { schema: "public" }
+ *     { objectType: "schema", operation: "create" },
+ *     { "table/schema": "public" }
  *   ]
  * });
  * ```

package/dist/core/integrations/filter/dsl.js

@@ -1,7 +1,73 @@
 /**
  * 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 { PROPERTY_EXTRACTORS } from "./extractors.js";
+import { compileWildcard, flattenChange } from "./flatten.js";
+// 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, expected) {
+    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.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.
  *
@@ -12,94 +78,36 @@ import { PROPERTY_EXTRACTORS } from "./extractors.js";
 export function evaluatePattern(pattern, change) {
     // Handle composition operators first (they take precedence)
     // NOT operator - negate the result
-    if (pattern.not) {
+    if ("not" in pattern && pattern.not) {
         return !evaluatePattern(pattern.not, change);
     }
     // AND operator - all patterns must match
-    if (pattern.and) {
+    if ("and" in pattern && pattern.and) {
         return pattern.and.every((p) => evaluatePattern(p, change));
     }
     // OR operator - any pattern must match
-    if (pattern.or) {
+    if ("or" in pattern && 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
+    // 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;
-        }
-        // 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) {
+        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;
         }
-        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
+        // At least one matching key must satisfy the value matcher
+        const anyMatch = matchingKeys.some((k) => matchValue(flat[k], matcher));
+        if (!anyMatch)
             return false;
-        }
     }
-    // All checks passed
+    // All pattern keys satisfied
     return true;
 }
 /**
@@ -109,17 +117,57 @@ export function evaluatePattern(pattern, change) {
  * @returns A ChangeFilter function that evaluates the pattern
  *
  * @example
- * ```ts
+ * ```
  * const filter = compileFilterDSL({
  *   or: [
- *     { type: "schema", operation: "create" },
- *     { schema: "public" }
+ *     { objectType: "schema", operation: "create" },
+ *     { "table/schema": "public" }
  *   ]
  * });
  * ```
  */
 export function compileFilterDSL(dsl) {
+    validateRegexPatterns(dsl);
     return (change) => {
         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) {
+    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.message}`);
+                }
+            }
+        }
+    }
+}

package/dist/core/integrations/filter/flatten.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Change flattening and wildcard path matching for the filter DSL.
+ *
+ * Each Change is flattened into a Record<string, FlatValue> where top-level
+ * scalar properties become bare keys and model sub-object properties become
+ * `<objectType>/<field>` paths. Wildcard patterns (e.g. `* /schema`) match
+ * against these flat paths.
+ */
+import type { Change } from "../../change.types.ts";
+/**
+ * A flat value extracted from a Change: scalar types or arrays of scalars.
+ *
+ * The filter DSL flattens every {@link Change} into a
+ * `Record<string, FlatValue>` before pattern matching. Only these primitive
+ * types survive the flattening step; nested objects are expanded into
+ * `<objectType>/<field>` paths.
+ *
+ * @category Filter DSL
+ */
+export type FlatValue = string | number | boolean | null | Array<string | number>;
+/**
+ * Flatten a Change into a Record<string, FlatValue>.
+ *
+ * A Change object has two kinds of properties:
+ *
+ *   1. **Top-level properties** — scalars and arrays directly on the object.
+ *      These become bare keys in the flat record.
+ *
+ *   2. **Model sub-object** — a single nested object whose JS property name is
+ *      given by OBJECT_TYPE_TO_PROPERTY_KEY. Its scalar fields are flattened
+ *      with an `<objectType>/` prefix.
+ *
+ * After the main loop, a schema normalization step ensures that
+ * `<objectType>/schema` exists for every change that logically belongs to
+ * a schema — even when the model stores the schema under a different name.
+ *
+ * Results are cached per Change instance (WeakMap) so repeated calls are free.
+ */
+export declare function flattenChange(change: Change): Record<string, FlatValue>;
+/**
+ * Compile a glob pattern string into a matcher function.
+ *
+ * Uses picomatch for full glob support:
+ * - `objectType` matches only `objectType`
+ * - `table/schema` matches only `table/schema`
+ * - `* /schema` matches `table/schema`, `view/schema`, etc.
+ * - `{table,view}/schema` matches `table/schema` and `view/schema`
+ * - `table/is_*` matches `table/is_partition`, `table/is_typed`, etc.
+ * - `!(role)/schema` matches any objectType's schema except `role`
+ */
+export declare function compileWildcard(pattern: string): (path: string) => boolean;

package/dist/core/integrations/filter/flatten.js

@@ -0,0 +1,116 @@
+/**
+ * Change flattening and wildcard path matching for the filter DSL.
+ *
+ * Each Change is flattened into a Record<string, FlatValue> where top-level
+ * scalar properties become bare keys and model sub-object properties become
+ * `<objectType>/<field>` paths. Wildcard patterns (e.g. `* /schema`) match
+ * against these flat paths.
+ */
+import picomatch from "picomatch";
+import { OBJECT_TYPE_TO_PROPERTY_KEY } from "../../change.types.js";
+import { getSchema } from "../../change-utils.js";
+/**
+ * WeakMap cache to avoid re-flattening the same Change instance.
+ */
+const flattenCache = new WeakMap();
+/**
+ * Convert an unknown value to a FlatValue if it's a supported type.
+ *
+ * Supported types (kept in the flat record):
+ *   - null / undefined  → null   (missing or explicitly null)
+ *   - string, number, boolean    → as-is
+ *   - Array where every element is string or number → as-is
+ *
+ * Anything else (nested objects, arrays of objects, functions, …) is NOT
+ * representable as a flat value, so we return `undefined` to signal
+ * "skip this entry".
+ */
+function toFlatValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean")
+        return value;
+    if (Array.isArray(value) &&
+        value.every((v) => typeof v === "string" || typeof v === "number")) {
+        return value;
+    }
+    return undefined;
+}
+/**
+ * Flatten a Change into a Record<string, FlatValue>.
+ *
+ * A Change object has two kinds of properties:
+ *
+ *   1. **Top-level properties** — scalars and arrays directly on the object.
+ *      These become bare keys in the flat record.
+ *
+ *   2. **Model sub-object** — a single nested object whose JS property name is
+ *      given by OBJECT_TYPE_TO_PROPERTY_KEY. Its scalar fields are flattened
+ *      with an `<objectType>/` prefix.
+ *
+ * After the main loop, a schema normalization step ensures that
+ * `<objectType>/schema` exists for every change that logically belongs to
+ * a schema — even when the model stores the schema under a different name.
+ *
+ * Results are cached per Change instance (WeakMap) so repeated calls are free.
+ */
+export function flattenChange(change) {
+    const cached = flattenCache.get(change);
+    if (cached)
+        return cached;
+    const flat = {};
+    const modelKey = OBJECT_TYPE_TO_PROPERTY_KEY[change.objectType];
+    const prefix = change.objectType;
+    for (const [key, value] of Object.entries(change)) {
+        if (key === modelKey &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            for (const [subKey, subValue] of Object.entries(value)) {
+                const flatVal = toFlatValue(subValue);
+                if (flatVal !== undefined) {
+                    flat[`${prefix}/${subKey}`] = flatVal;
+                }
+            }
+        }
+        else {
+            const flatVal = toFlatValue(value);
+            if (flatVal !== undefined) {
+                flat[key] = flatVal;
+            }
+        }
+    }
+    // requires/creates/drops are prototype getters (not own properties),
+    // so Object.entries() above won't see them. Access them explicitly.
+    flat.requires = change.requires ?? [];
+    flat.creates = change.creates ?? [];
+    flat.drops = change.drops ?? [];
+    // Schema normalization: ensure <objectType>/schema exists for all changes
+    // that have a schema. Handles: schema objects (name→schema), event triggers
+    // (function_schema→schema), default_privilege scope (inSchema→schema).
+    const schemaKey = `${prefix}/schema`;
+    if (!(schemaKey in flat)) {
+        const schemaValue = getSchema(change);
+        if (schemaValue !== null) {
+            flat[schemaKey] = schemaValue;
+        }
+    }
+    flattenCache.set(change, flat);
+    return flat;
+}
+/**
+ * Compile a glob pattern string into a matcher function.
+ *
+ * Uses picomatch for full glob support:
+ * - `objectType` matches only `objectType`
+ * - `table/schema` matches only `table/schema`
+ * - `* /schema` matches `table/schema`, `view/schema`, etc.
+ * - `{table,view}/schema` matches `table/schema` and `view/schema`
+ * - `table/is_*` matches `table/is_partition`, `table/is_typed`, etc.
+ * - `!(role)/schema` matches any objectType's schema except `role`
+ */
+export function compileWildcard(pattern) {
+    return picomatch(pattern, { dot: true });
+}

package/dist/core/integrations/integration-dsl.d.ts

@@ -7,9 +7,25 @@ import type { CatalogSnapshot } from "../catalog.snapshot.ts";
 import type { FilterDSL } from "./filter/dsl.ts";
 import type { SerializeDSL } from "./serialize/dsl.ts";
 /**
- * Integration DSL - serializable representation of an integration.
+ * Serializable representation of a pg-delta integration.
+ *
+ * An integration combines a {@link FilterDSL} (which changes to include) with a
+ * {@link SerializeDSL} (how to render them as SQL) and an optional baseline
+ * catalog snapshot.
+ *
+ * @category Integration
  */
 export type IntegrationDSL = {
+    /**
+     * Base integration(s) to extend. Filters are AND-combined, serialize rules
+     * are concatenated (base rules first, higher priority in first-match-wins),
+     * and the most specific emptyCatalog wins.
+     *
+     * Only core integration names are accepted (e.g., "supabase").
+     * Can be a single name or an array of names.
+     * Circular extends are detected and rejected.
+     */
+    extends?: string | string[];
     /**
      * Filter DSL - determines which changes to include/exclude.
      * If not provided, all changes are included.

package/dist/core/integrations/merge.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Integration merging — combines multiple IntegrationDSL objects.
+ *
+ * - Filters are AND-combined
+ * - Serialize rules are concatenated (earlier integrations first = higher priority)
+ * - emptyCatalog: most-specific (last) integration's value wins
+ */
+import type { IntegrationDSL } from "./integration-dsl.ts";
+/**
+ * Merge an ordered list of integrations into a single IntegrationDSL.
+ *
+ * Integrations are ordered from base (first) to most-specific (last).
+ * - Filters: AND-combined (all must pass)
+ * - Serialize: concatenated (base rules first → higher priority, first-match-wins)
+ * - emptyCatalog: most-specific non-undefined value wins
+ *
+ * @param integrations - Ordered list of integrations (base first, most-specific last)
+ * @returns A single merged IntegrationDSL
+ */
+export declare function mergeIntegrations(integrations: IntegrationDSL[]): IntegrationDSL;