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

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

@@ -0,0 +1,150 @@
+/**
+ * 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 type { Change } from "../../change.types.ts";
+import { OBJECT_TYPE_TO_PROPERTY_KEY } from "../../change.types.ts";
+import { getSchema } from "../../change-utils.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>;
+
+/**
+ * WeakMap cache to avoid re-flattening the same Change instance.
+ */
+const flattenCache = new WeakMap<Change, Record<string, FlatValue>>();
+
+/**
+ * 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: unknown): FlatValue | undefined {
+  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: unknown) => typeof v === "string" || typeof v === "number")
+  ) {
+    return value as Array<string | number>;
+  }
+  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: Change): Record<string, FlatValue> {
+  const cached = flattenCache.get(change);
+  if (cached) return cached;
+
+  const flat: Record<string, FlatValue> = {};
+
+  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 as Record<string, unknown>,
+      )) {
+        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: string): (path: string) => boolean {
+  return picomatch(pattern, { dot: true });
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Integration DSL - A serializable domain-specific language for integrations.
+ *
+ * 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";
+
+/**
+ * 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.
+   */
+  filter?: FilterDSL;
+  /**
+   * Serialization DSL - customizes how changes are serialized.
+   * 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/src/core/integrations/integration.types.ts

@@ -0,0 +1,65 @@
+import { compileFilterDSL, type FilterDSL } from "./filter/dsl.ts";
+import type { ChangeFilter } from "./filter/filter.types.ts";
+import { compileSerializeDSL, type SerializeDSL } from "./serialize/dsl.ts";
+import type { ChangeSerializer } from "./serialize/serialize.types.ts";
+
+/**
+ * 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 function resolveIntegration(
+  integration: Integration,
+): ResolvedIntegration | undefined {
+  // 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 as FilterDSL) : undefined;
+  const serializeDSL = isSerializeDSL
+    ? (integration.serialize as SerializeDSL)
+    : 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/src/core/integrations/merge.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, test } from "bun:test";
+import type { IntegrationDSL } from "./integration-dsl.ts";
+import { mergeIntegrations } from "./merge.ts";
+
+describe("mergeIntegrations", () => {
+  test("empty list returns empty object", () => {
+    expect(mergeIntegrations([])).toEqual({});
+  });
+
+  test("single integration is returned as-is", () => {
+    const integration: IntegrationDSL = {
+      filter: { objectType: "table" },
+      serialize: [
+        {
+          when: { objectType: "schema" },
+          options: { skipAuthorization: true },
+        },
+      ],
+    };
+    expect(mergeIntegrations([integration])).toBe(integration);
+  });
+
+  test("filters are AND-combined", () => {
+    const base: IntegrationDSL = {
+      filter: { "*/schema": "public" },
+    };
+    const ext: IntegrationDSL = {
+      filter: { objectType: "table" },
+    };
+
+    const merged = mergeIntegrations([base, ext]);
+    expect(merged.filter).toEqual({
+      and: [{ "*/schema": "public" }, { objectType: "table" }],
+    });
+  });
+
+  test("single filter is not wrapped in and", () => {
+    const base: IntegrationDSL = {};
+    const ext: IntegrationDSL = {
+      filter: { objectType: "table" },
+    };
+
+    const merged = mergeIntegrations([base, ext]);
+    expect(merged.filter).toEqual({ objectType: "table" });
+  });
+
+  test("serialize rules are concatenated (base first)", () => {
+    const base: IntegrationDSL = {
+      serialize: [
+        {
+          when: { objectType: "schema" },
+          options: { skipAuthorization: true },
+        },
+      ],
+    };
+    const ext: IntegrationDSL = {
+      serialize: [
+        {
+          when: { objectType: "table" },
+          options: { skipAuthorization: false },
+        },
+      ],
+    };
+
+    const merged = mergeIntegrations([base, ext]);
+    expect(merged.serialize).toEqual([
+      { when: { objectType: "schema" }, options: { skipAuthorization: true } },
+      { when: { objectType: "table" }, options: { skipAuthorization: false } },
+    ]);
+  });
+
+  test("emptyCatalog: most-specific (last) wins", () => {
+    const baseCatalog = {
+      version: 15,
+      schemas: {},
+    } as IntegrationDSL["emptyCatalog"];
+    const extCatalog = {
+      version: 16,
+      schemas: {},
+    } as IntegrationDSL["emptyCatalog"];
+
+    const base: IntegrationDSL = { emptyCatalog: baseCatalog };
+    const ext: IntegrationDSL = { emptyCatalog: extCatalog };
+
+    const merged = mergeIntegrations([base, ext]);
+    expect(merged.emptyCatalog).toBe(extCatalog);
+  });
+
+  test("emptyCatalog: falls back to base if most-specific is undefined", () => {
+    const baseCatalog = {
+      version: 15,
+      schemas: {},
+    } as IntegrationDSL["emptyCatalog"];
+
+    const base: IntegrationDSL = { emptyCatalog: baseCatalog };
+    const ext: IntegrationDSL = {};
+
+    const merged = mergeIntegrations([base, ext]);
+    expect(merged.emptyCatalog).toBe(baseCatalog);
+  });
+
+  test("full merge combines all fields", () => {
+    const base: IntegrationDSL = {
+      filter: { "*/schema": "public" },
+      serialize: [
+        {
+          when: { objectType: "schema" },
+          options: { skipAuthorization: true },
+        },
+      ],
+    };
+    const ext: IntegrationDSL = {
+      filter: { not: { objectType: "role" } },
+      serialize: [
+        {
+          when: { objectType: "table" },
+          options: { skipAuthorization: false },
+        },
+      ],
+    };
+
+    const merged = mergeIntegrations([base, ext]);
+    expect(merged.filter).toEqual({
+      and: [{ "*/schema": "public" }, { not: { objectType: "role" } }],
+    });
+    expect(merged.serialize).toHaveLength(2);
+  });
+});

package/src/core/integrations/merge.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 { FilterDSL } from "./filter/dsl.ts";
+import type { IntegrationDSL } from "./integration-dsl.ts";
+import type { SerializeDSL } from "./serialize/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 function mergeIntegrations(
+  integrations: IntegrationDSL[],
+): IntegrationDSL {
+  if (integrations.length === 0) return {};
+  if (integrations.length === 1) return integrations[0];
+
+  // Collect all filters
+  const filters: FilterDSL[] = [];
+  for (const integration of integrations) {
+    if (integration.filter) {
+      filters.push(integration.filter);
+    }
+  }
+
+  // Collect all serialize rules (base first = higher priority)
+  const serializeRules: SerializeDSL = [];
+  for (const integration of integrations) {
+    if (integration.serialize) {
+      serializeRules.push(...integration.serialize);
+    }
+  }
+
+  // emptyCatalog: most-specific (last) non-undefined wins
+  let emptyCatalog: IntegrationDSL["emptyCatalog"];
+  for (let i = integrations.length - 1; i >= 0; i--) {
+    if (integrations[i].emptyCatalog !== undefined) {
+      emptyCatalog = integrations[i].emptyCatalog;
+      break;
+    }
+  }
+
+  const merged: IntegrationDSL = {};
+
+  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/src/core/integrations/serialize/dsl.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "../../change.types.ts";
+import { compileSerializeDSL } from "./dsl.ts";
+import type { SerializeOptions } from "./serialize.types.ts";
+
+function makeChange(
+  type: string,
+  operation: string,
+  serializeFn: (opts?: SerializeOptions) => string,
+): Change {
+  return {
+    objectType: type,
+    operation,
+    scope: "object",
+    schema: { name: "test" },
+    extension: { schema: "pgmq" },
+    serialize: serializeFn,
+  } as unknown as Change;
+}
+
+describe("compileSerializeDSL", () => {
+  test("matching extension rule can skip schema serialization", () => {
+    const serializer = compileSerializeDSL([
+      {
+        when: { objectType: "extension", operation: "create" },
+        options: { skipSchema: true },
+      },
+    ]);
+
+    const change = makeChange("extension", "create", (opts) =>
+      opts?.skipSchema
+        ? "CREATE EXTENSION pgmq"
+        : "CREATE EXTENSION pgmq WITH SCHEMA pgmq",
+    );
+
+    expect(serializer(change)).toBe("CREATE EXTENSION pgmq");
+  });
+
+  test("matching rule applies its options", () => {
+    const serializer = compileSerializeDSL([
+      {
+        when: { objectType: "schema", operation: "create" },
+        options: { skipAuthorization: true },
+      },
+    ]);
+
+    const change = makeChange("schema", "create", (opts) =>
+      opts?.skipAuthorization
+        ? "CREATE SCHEMA test"
+        : "CREATE SCHEMA test AUTHORIZATION owner",
+    );
+
+    expect(serializer(change)).toBe("CREATE SCHEMA test");
+  });
+
+  test("no matching rule uses default serialization", () => {
+    const serializer = compileSerializeDSL([
+      {
+        when: { objectType: "table" },
+        options: { skipAuthorization: true },
+      },
+    ]);
+
+    const change = makeChange("schema", "create", (opts) =>
+      opts?.skipAuthorization
+        ? "CREATE SCHEMA test"
+        : "CREATE SCHEMA test AUTHORIZATION owner",
+    );
+
+    expect(serializer(change)).toBe("CREATE SCHEMA test AUTHORIZATION owner");
+  });
+
+  test("first matching rule wins", () => {
+    const serializer = compileSerializeDSL([
+      {
+        when: { objectType: "schema" },
+        options: { skipAuthorization: true },
+      },
+      {
+        when: { objectType: "schema" },
+        options: { skipAuthorization: false },
+      },
+    ]);
+
+    const change = makeChange("schema", "create", (opts) =>
+      opts?.skipAuthorization ? "WITHOUT AUTH" : "WITH AUTH",
+    );
+
+    expect(serializer(change)).toBe("WITHOUT AUTH");
+  });
+
+  test("skips non-matching first rule and applies second", () => {
+    const serializer = compileSerializeDSL([
+      {
+        when: { objectType: "table" },
+        options: { skipAuthorization: true },
+      },
+      {
+        when: { objectType: "schema" },
+        options: { skipAuthorization: false },
+      },
+    ]);
+
+    const change = makeChange("schema", "create", (opts) =>
+      opts?.skipAuthorization ? "WITHOUT AUTH" : "WITH AUTH",
+    );
+
+    expect(serializer(change)).toBe("WITH AUTH");
+  });
+});

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

@@ -0,0 +1,71 @@
+/**
+ * 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, SerializeOptions } from "./serialize.types.ts";
+
+/**
+ * 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;
+};
+
+/**
+ * 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[];
+
+/**
+ * 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: {
+ *       objectType: "schema",
+ *       operation: "create",
+ *       "schema/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,40 @@
+import type { Change } from "../../change.types.ts";
+
+/**
+ * Shared serialization options passed to `change.serialize(options)`.
+ *
+ * This is the global source of truth for serialize-option flags used by the
+ * integration serialization DSL and concrete change serializers.
+ *
+ * @category Integration
+ */
+export type SerializeOptions = {
+  /** Skip `AUTHORIZATION` when serializing schema creation. */
+  skipAuthorization?: boolean;
+  /** Skip `WITH SCHEMA ...` when serializing extension creation. */
+  skipSchema?: boolean;
+};
+
+/**
+ * Schema-specific view of {@link SerializeOptions}.
+ *
+ * @category Integration
+ */
+export type SchemaSerializeOptions = Pick<
+  SerializeOptions,
+  "skipAuthorization"
+>;
+
+/**
+ * Extension-specific view of {@link SerializeOptions}.
+ *
+ * @category Integration
+ */
+export type ExtensionSerializeOptions = Pick<SerializeOptions, "skipSchema">;
+
+/**
+ * Compiled serializer function used during plan/declarative export rendering.
+ *
+ * @category Integration
+ */
+export type ChangeSerializer = (change: Change) => string | undefined;