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

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 { 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.
  */
-import { PROPERTY_EXTRACTORS } from "./extractors.js";
+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,76 +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 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)) {
+    // 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;
-        }
-        // 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) {
+        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;
 }
 /**
@@ -91,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,129 @@
+/**
+ * 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 if (key === "securityLabel" &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            // Security labels are change-level metadata, so expose provider/label as
+            // bare keys for filters like { scope: "security_label", provider: "..." }.
+            for (const [subKey, subValue] of Object.entries(value)) {
+                const flatVal = toFlatValue(subValue);
+                if (flatVal !== undefined) {
+                    flat[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

@@ -3,12 +3,29 @@
  *
  * 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";
 /**
- * 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.
@@ -19,4 +36,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;
 };

package/dist/core/integrations/integration.types.d.ts

@@ -1,6 +1,31 @@
+import { type FilterDSL } from "./filter/dsl.ts";
 import type { ChangeFilter } from "./filter/filter.types.ts";
+import { type SerializeDSL } from "./serialize/dsl.ts";
 import type { ChangeSerializer } from "./serialize/serialize.types.ts";
-export type Integration = {
+/**
+ * A resolved integration is an integration that has been compiled to a function.
+ */
+export type ResolvedIntegration = {
     filter?: ChangeFilter;
     serialize?: ChangeSerializer;
 };
+/**
+ * A raw integration is an integration that has not been compiled to a function.
+ */
+export type IntegrationDSL = {
+    filter?: FilterDSL;
+    serialize?: SerializeDSL;
+};
+/**
+ * An integration is a raw integration that has not been compiled to a function.
+ */
+export type Integration = {
+    filter?: ResolvedIntegration["filter"] | IntegrationDSL["filter"];
+    serialize?: ResolvedIntegration["serialize"] | IntegrationDSL["serialize"];
+};
+/**
+ * Resolve an integration either DSL or already resovled into a ResolvedIntegration.
+ * @param integration - The integration to resolve.
+ * @returns The resolved integration.
+ */
+export declare function resolveIntegration(integration: Integration): ResolvedIntegration | undefined;

package/dist/core/integrations/integration.types.js

@@ -1 +1,31 @@
-export {};
+import { compileFilterDSL } from "./filter/dsl.js";
+import { compileSerializeDSL } from "./serialize/dsl.js";
+/**
+ * Resolve an integration either DSL or already resovled into a ResolvedIntegration.
+ * @param integration - The integration to resolve.
+ * @returns The resolved integration.
+ */
+export function resolveIntegration(integration) {
+    // Determine if filter/serialize are DSL or functions, and extract DSL for storage
+    const isFilterDSL = integration.filter && typeof integration.filter !== "function";
+    const isSerializeDSL = integration.serialize && typeof integration.serialize !== "function";
+    const filterDSL = isFilterDSL ? integration.filter : undefined;
+    const serializeDSL = isSerializeDSL
+        ? integration.serialize
+        : undefined;
+    // Build final integration: compile DSL if needed, use functions directly otherwise
+    if (integration.filter || integration.serialize) {
+        return {
+            filter: typeof integration.filter === "function"
+                ? integration.filter
+                : filterDSL
+                    ? compileFilterDSL(filterDSL)
+                    : undefined,
+            serialize: typeof integration.serialize === "function"
+                ? integration.serialize
+                : serializeDSL
+                    ? compileSerializeDSL(serializeDSL)
+                    : undefined,
+        };
+    }
+}

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;

package/dist/core/integrations/merge.js

@@ -0,0 +1,60 @@
+/**
+ * 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
+ */
+/**
+ * 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 function mergeIntegrations(integrations) {
+    if (integrations.length === 0)
+        return {};
+    if (integrations.length === 1)
+        return integrations[0];
+    // Collect all filters
+    const filters = [];
+    for (const integration of integrations) {
+        if (integration.filter) {
+            filters.push(integration.filter);
+        }
+    }
+    // Collect all serialize rules (base first = higher priority)
+    const serializeRules = [];
+    for (const integration of integrations) {
+        if (integration.serialize) {
+            serializeRules.push(...integration.serialize);
+        }
+    }
+    // emptyCatalog: most-specific (last) non-undefined wins
+    let emptyCatalog;
+    for (let i = integrations.length - 1; i >= 0; i--) {
+        if (integrations[i].emptyCatalog !== undefined) {
+            emptyCatalog = integrations[i].emptyCatalog;
+            break;
+        }
+    }
+    const merged = {};
+    if (filters.length === 1) {
+        merged.filter = filters[0];
+    }
+    else if (filters.length > 1) {
+        merged.filter = { and: filters };
+    }
+    if (serializeRules.length > 0) {
+        merged.serialize = serializeRules;
+    }
+    if (emptyCatalog !== undefined) {
+        merged.emptyCatalog = emptyCatalog;
+    }
+    return merged;
+}

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

@@ -4,14 +4,7 @@
  * Reuses the filter pattern matching logic to determine when to apply serialization options.
  */
 import { 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;
-    [key: string]: unknown;
-};
+import type { ChangeSerializer, SerializeOptions } from "./serialize.types.ts";
 /**
  * A serialization rule that applies options when a pattern matches.
  */
@@ -27,8 +20,11 @@ type SerializeRule = {
     options: SerializeOptions;
 };
 /**
- * Serialization DSL - array of rules evaluated in order.
- * First matching rule's options are applied.
+ * Array of serialization rules evaluated in order. The first matching rule's
+ * options are passed to `change.serialize()`. If no rule matches, default
+ * serialization is used.
+ *
+ * @category Integration
  */
 export type SerializeDSL = SerializeRule[];
 /**
@@ -45,9 +41,9 @@ export type SerializeDSL = SerializeRule[];
  * const serializer = compileSerializeDSL([
  *   {
  *     when: {
- *       type: "schema",
+ *       objectType: "schema",
  *       operation: "create",
- *       owner: ["service_role"]
+ *       "schema/owner": ["service_role"]
  *     },
  *     options: { skipAuthorization: true }
  *   }

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

@@ -18,9 +18,9 @@ import { evaluatePattern } from "../filter/dsl.js";
  * const serializer = compileSerializeDSL([
  *   {
  *     when: {
- *       type: "schema",
+ *       objectType: "schema",
  *       operation: "create",
- *       owner: ["service_role"]
+ *       "schema/owner": ["service_role"]
  *     },
  *     options: { skipAuthorization: true }
  *   }