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

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);
+  });
+});

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

@@ -9,9 +9,25 @@ 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/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;
+}