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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/pg-delta",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.11",
   "description": "PostgreSQL migrations made easy",
   "type": "module",
   "sideEffects": false,
@@ -68,6 +68,7 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "check-types": "tsc --noEmit",
+    "docs": "typedoc",
     "format-and-lint": "biome check . --error-on-warnings",
     "knip": "knip",
     "pgdelta": "bun src/cli/bin/cli.ts",
@@ -84,6 +85,7 @@
     "chalk": "^5.6.2",
     "debug": "^4.3.7",
     "pg": "^8.17.2",
+    "picomatch": "^4.0.3",
     "zod": "^4.2.1"
   },
   "devDependencies": {
@@ -94,9 +96,11 @@
     "@types/debug": "^4.1.12",
     "@types/node": "^24.10.4",
     "@types/pg": "^8.11.10",
+    "@types/picomatch": "^4.0.2",
     "dedent": "^1.7.1",
     "knip": "^5.75.2",
     "testcontainers": "^11.10.0",
+    "typedoc": "^0.28.17",
     "typescript": "^5.9.3"
   }
 }

package/src/cli/commands/declarative-export.ts

@@ -6,13 +6,14 @@ import { mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { buildCommand, type CommandContext } from "@stricli/core";
 import chalk from "chalk";
-import type { CatalogSnapshot } from "../../core/catalog.snapshot.ts";
+import { deserializeCatalog } from "../../core/catalog.snapshot.ts";
 import { exportDeclarativeSchema } from "../../core/export/index.ts";
 import type { Grouping, GroupingPattern } from "../../core/export/types.ts";
 import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
-import type { ChangeFilter } from "../../core/integrations/filter/filter.types.ts";
-import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
-import type { ChangeSerializer } from "../../core/integrations/serialize/serialize.types.ts";
+import {
+  compileSerializeDSL,
+  type SerializeDSL,
+} from "../../core/integrations/serialize/dsl.ts";
 import { createPlan } from "../../core/plan/index.ts";
 import type { SqlFormatOptions } from "../../core/plan/sql-format.ts";
 import {
@@ -21,7 +22,7 @@ import {
   computeFileDiff,
   formatExportSummary,
 } from "../utils/export-display.ts";
-import { loadIntegrationDSL } from "../utils/integrations.ts";
+import { resolveIntegrationOptions } from "../utils/integrations.ts";
 import { isPostgresUrl, loadCatalogFromFile } from "../utils/resolve-input.ts";
 
 function parseJsonFlag<T>(label: string, value: string): T {
@@ -185,29 +186,22 @@ After export, a tip is printed with the command to apply the schema to an empty
       verbose?: boolean;
     },
   ) {
-    const { compileSerializeDSL } = await import(
-      "../../core/integrations/serialize/dsl.ts"
-    );
-
-    let filterOption: FilterDSL | ChangeFilter | undefined = flags.filter;
-    let serializeOption: SerializeDSL | ChangeSerializer | undefined =
-      flags.serialize;
-    let integrationEmptyCatalog: CatalogSnapshot | undefined;
-    if (flags.integration) {
-      const integrationDSL = await loadIntegrationDSL(flags.integration);
-      filterOption = filterOption ?? integrationDSL.filter;
-      serializeOption = serializeOption ?? integrationDSL.serialize;
-      integrationEmptyCatalog = integrationDSL.emptyCatalog;
-    }
+    const {
+      filter,
+      serialize,
+      emptyCatalog: integrationEmptyCatalog,
+    } = await resolveIntegrationOptions({
+      filter: flags.filter,
+      serialize: flags.serialize,
+      integration: flags.integration,
+    });
 
     const resolvedSource = flags.source
       ? isPostgresUrl(flags.source)
         ? flags.source
         : await loadCatalogFromFile(flags.source)
       : integrationEmptyCatalog
-        ? (await import("../../core/catalog.snapshot.ts")).deserializeCatalog(
-            integrationEmptyCatalog,
-          )
+        ? deserializeCatalog(integrationEmptyCatalog)
         : null;
 
     const resolvedTarget = isPostgresUrl(flags.target)
@@ -221,8 +215,8 @@ After export, a tip is printed with the command to apply the schema to an empty
     // changes that depend on filtered objects (e.g. RLS policies that
     // reference auth.uid() when the auth schema is filtered out).
     const planResult = await createPlan(resolvedSource, resolvedTarget, {
-      filter: filterOption,
-      serialize: serializeOption,
+      filter,
+      serialize,
       skipDefaultPrivilegeSubtraction: true,
     });
 
@@ -254,9 +248,7 @@ After export, a tip is printed with the command to apply the schema to an empty
     }
 
     const serializeFn =
-      serializeOption !== undefined
-        ? compileSerializeDSL(serializeOption)
-        : undefined;
+      serialize !== undefined ? compileSerializeDSL(serialize) : undefined;
 
     const output = exportDeclarativeSchema(planResult, {
       integration:

package/src/cli/commands/plan.ts

@@ -4,14 +4,13 @@
 
 import { writeFile } from "node:fs/promises";
 import { buildCommand, type CommandContext } from "@stricli/core";
+import { deserializeCatalog } from "../../core/catalog.snapshot.ts";
 import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
-import type { ChangeFilter } from "../../core/integrations/filter/filter.types.ts";
 import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
-import type { ChangeSerializer } from "../../core/integrations/serialize/serialize.types.ts";
 import { createPlan } from "../../core/plan/index.ts";
 import type { SqlFormatOptions } from "../../core/plan/sql-format.ts";
 import { setCommandExitCode } from "../exit-code.ts";
-import { loadIntegrationDSL } from "../utils/integrations.ts";
+import { resolveIntegrationOptions } from "../utils/integrations.ts";
 import { isPostgresUrl, loadCatalogFromFile } from "../utils/resolve-input.ts";
 import { formatPlanForDisplay } from "../utils.ts";
 
@@ -138,27 +137,22 @@ json/sql outputs are available for artifacts or piping.
       "sql-format-options"?: SqlFormatOptions;
     },
   ) {
-    let filterOption: FilterDSL | ChangeFilter | undefined = flags.filter;
-    let serializeOption: SerializeDSL | ChangeSerializer | undefined =
-      flags.serialize;
-    let integrationEmptyCatalog:
-      | import("../../core/catalog.snapshot.ts").CatalogSnapshot
-      | undefined;
-    if (flags.integration) {
-      const integrationDSL = await loadIntegrationDSL(flags.integration);
-      filterOption = filterOption ?? integrationDSL.filter;
-      serializeOption = serializeOption ?? integrationDSL.serialize;
-      integrationEmptyCatalog = integrationDSL.emptyCatalog;
-    }
+    const {
+      filter,
+      serialize,
+      emptyCatalog: integrationEmptyCatalog,
+    } = await resolveIntegrationOptions({
+      filter: flags.filter,
+      serialize: flags.serialize,
+      integration: flags.integration,
+    });
 
     const resolvedSource = flags.source
       ? isPostgresUrl(flags.source)
         ? flags.source
         : await loadCatalogFromFile(flags.source)
       : integrationEmptyCatalog
-        ? (await import("../../core/catalog.snapshot.ts")).deserializeCatalog(
-            integrationEmptyCatalog,
-          )
+        ? deserializeCatalog(integrationEmptyCatalog)
         : null;
 
     const resolvedTarget = isPostgresUrl(flags.target)
@@ -167,8 +161,8 @@ json/sql outputs are available for artifacts or piping.
 
     const planResult = await createPlan(resolvedSource, resolvedTarget, {
       role: flags.role,
-      filter: filterOption,
-      serialize: serializeOption,
+      filter,
+      serialize,
     });
     if (!planResult) {
       this.process.stdout.write("No changes detected.\n");

package/src/cli/commands/sync.ts

@@ -4,12 +4,10 @@
 
 import { buildCommand, type CommandContext } from "@stricli/core";
 import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
-import type { ChangeFilter } from "../../core/integrations/filter/filter.types.ts";
 import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
-import type { ChangeSerializer } from "../../core/integrations/serialize/serialize.types.ts";
 import { applyPlan } from "../../core/plan/apply.ts";
 import { createPlan } from "../../core/plan/index.ts";
-import { loadIntegrationDSL } from "../utils/integrations.ts";
+import { resolveIntegrationOptions } from "../utils/integrations.ts";
 import {
   formatPlanForDisplay,
   handleApplyResult,
@@ -120,22 +118,17 @@ Exit codes:
       integration?: string;
     },
   ) {
-    // Load integration if provided and extract filter/serialize DSL
-    let filterOption: FilterDSL | ChangeFilter | undefined = flags.filter;
-    let serializeOption: SerializeDSL | ChangeSerializer | undefined =
-      flags.serialize;
-    if (flags.integration) {
-      const integrationDSL = await loadIntegrationDSL(flags.integration);
-      // Use integration DSL if explicit flags not provided
-      filterOption = filterOption ?? integrationDSL.filter;
-      serializeOption = serializeOption ?? integrationDSL.serialize;
-    }
+    const { filter, serialize } = await resolveIntegrationOptions({
+      filter: flags.filter,
+      serialize: flags.serialize,
+      integration: flags.integration,
+    });
 
     // 1. Create the plan
     const planResult = await createPlan(flags.source, flags.target, {
       role: flags.role,
-      filter: filterOption,
-      serialize: serializeOption,
+      filter,
+      serialize,
     });
     if (!planResult) {
       this.process.stdout.write("No changes detected.\n");

package/src/cli/utils/integrations.test.ts

@@ -2,7 +2,12 @@ import { describe, expect, test } from "bun:test";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { loadIntegrationDSL } from "./integrations.ts";
+import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
+import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
+import {
+  loadIntegrationDSL,
+  resolveIntegrationOptions,
+} from "./integrations.ts";
 
 describe("loadIntegrationDSL", () => {
   test("loads from .json file path", async () => {
@@ -12,12 +17,12 @@ describe("loadIntegrationDSL", () => {
       await writeFile(
         jsonPath,
         JSON.stringify({
-          filter: { schema: "app" },
+          filter: { "*/schema": "app" },
         }),
       );
       const dsl = await loadIntegrationDSL(jsonPath);
       expect(dsl).toBeDefined();
-      expect(dsl.filter).toEqual({ schema: "app" });
+      expect(dsl.filter).toEqual({ "*/schema": "app" });
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
@@ -42,3 +47,205 @@ describe("loadIntegrationDSL", () => {
     }
   });
 });
+
+describe("extends resolution", () => {
+  test('extends: "supabase" → resolves and merges successfully', async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-extends-"));
+    const jsonPath = path.join(dir, "custom.json");
+    try {
+      await writeFile(
+        jsonPath,
+        JSON.stringify({
+          extends: "supabase",
+          serialize: [
+            {
+              when: { objectType: "table" },
+              options: { skipAuthorization: true },
+            },
+          ],
+        }),
+      );
+      const dsl = await loadIntegrationDSL(jsonPath);
+      expect(dsl).toBeDefined();
+      // Should have the supabase filter merged in
+      expect(dsl.filter).toBeDefined();
+      // Should have both supabase serialize rules and our custom one
+      expect(dsl.serialize).toBeDefined();
+      expect(dsl.serialize?.length).toBeGreaterThan(1);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('extends: "./some-file.json" → throws error about core integrations only', async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-extends-"));
+    const filePath = path.join(dir, "child.json");
+    const parentPath = path.join(dir, "parent.json");
+    try {
+      await writeFile(
+        parentPath,
+        JSON.stringify({ filter: { "*/schema": "app" } }),
+      );
+      await writeFile(
+        filePath,
+        JSON.stringify({
+          extends: parentPath,
+          filter: { "*/schema": "public" },
+        }),
+      );
+      expect(loadIntegrationDSL(filePath)).rejects.toThrow(
+        /extends only supports core integration names/,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('extends: "nonexistent" → throws error about unknown core integration', async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-extends-"));
+    const jsonPath = path.join(dir, "custom.json");
+    try {
+      await writeFile(jsonPath, JSON.stringify({ extends: "nonexistent" }));
+      expect(loadIntegrationDSL(jsonPath)).rejects.toThrow(
+        /Unknown core integration: "nonexistent"/,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("resolveIntegrationOptions", () => {
+  test("no integration, no CLI flags → all undefined", async () => {
+    const result = await resolveIntegrationOptions({});
+    expect(result).toEqual({
+      filter: undefined,
+      serialize: undefined,
+    });
+  });
+
+  test("CLI flags only → passed through unchanged", async () => {
+    const filter: FilterDSL = { "*/schema": "public" };
+    const serialize: SerializeDSL = [
+      { when: { objectType: "schema" }, options: { skipAuthorization: true } },
+    ];
+    const result = await resolveIntegrationOptions({ filter, serialize });
+    expect(result.filter).toEqual(filter);
+    expect(result.serialize).toEqual(serialize);
+    expect(result.emptyCatalog).toBeUndefined();
+  });
+
+  test("integration only → integration values returned", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-resolve-"));
+    const jsonPath = path.join(dir, "int.json");
+    try {
+      await writeFile(
+        jsonPath,
+        JSON.stringify({
+          filter: { "*/schema": "app" },
+          serialize: [{ when: { objectType: "table" }, options: {} }],
+        }),
+      );
+      const result = await resolveIntegrationOptions({
+        integration: jsonPath,
+      });
+      expect(result.filter).toEqual({ "*/schema": "app" });
+      expect(result.serialize).toEqual([
+        { when: { objectType: "table" }, options: {} },
+      ]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("both filter + integration filter → AND-combined", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-resolve-"));
+    const jsonPath = path.join(dir, "int.json");
+    try {
+      await writeFile(
+        jsonPath,
+        JSON.stringify({
+          filter: { "*/schema": "app" },
+        }),
+      );
+      const cliFilter: FilterDSL = { objectType: "table" };
+      const result = await resolveIntegrationOptions({
+        filter: cliFilter,
+        integration: jsonPath,
+      });
+      expect(result.filter).toEqual({
+        and: [{ "*/schema": "app" }, { objectType: "table" }],
+      });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("both serialize + integration serialize → concatenated (integration first)", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-resolve-"));
+    const jsonPath = path.join(dir, "int.json");
+    try {
+      const intSerialize: SerializeDSL = [
+        {
+          when: { objectType: "schema" },
+          options: { skipAuthorization: true },
+        },
+      ];
+      const cliSerialize: SerializeDSL = [
+        { when: { objectType: "table" }, options: {} },
+      ];
+      await writeFile(jsonPath, JSON.stringify({ serialize: intSerialize }));
+      const result = await resolveIntegrationOptions({
+        serialize: cliSerialize,
+        integration: jsonPath,
+      });
+      expect(result.serialize).toEqual([...intSerialize, ...cliSerialize]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("emptyCatalog returned from integration", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-resolve-"));
+    const jsonPath = path.join(dir, "int.json");
+    try {
+      const emptyCatalog = {
+        version: 1,
+        currentUser: "postgres",
+        aggregates: {},
+        collations: {},
+        compositeTypes: {},
+        domains: {},
+        enums: {},
+        extensions: {},
+        procedures: {},
+        indexes: {},
+        materializedViews: {},
+        subscriptions: {},
+        publications: {},
+        rlsPolicies: {},
+        roles: {},
+        schemas: {},
+        sequences: {},
+        tables: {},
+        triggers: {},
+        eventTriggers: {},
+        rules: {},
+        ranges: {},
+        views: {},
+        foreignDataWrappers: {},
+        servers: {},
+        userMappings: {},
+        foreignTables: {},
+        depends: [],
+      };
+      await writeFile(jsonPath, JSON.stringify({ emptyCatalog }));
+      const result = await resolveIntegrationOptions({
+        integration: jsonPath,
+      });
+      expect(result.emptyCatalog).toEqual(emptyCatalog);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/cli/utils/integrations.ts

@@ -3,18 +3,19 @@
  */
 
 import { readFile } from "node:fs/promises";
+import type { CatalogSnapshot } from "../../core/catalog.snapshot.ts";
+import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
 import type { IntegrationDSL } from "../../core/integrations/integration-dsl.ts";
+import { mergeIntegrations } from "../../core/integrations/merge.ts";
+import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
 
 /**
- * Load an integration DSL from a file or core integration.
- * If the path ends with .json, treats it as a JSON file path directly.
- * Otherwise, tries to load from core integrations (TypeScript) first,
- * then falls back to treating as a JSON file path.
+ * Load a raw integration DSL from a file or core integration (without resolving extends).
  *
  * @param nameOrPath - Integration name (e.g., "supabase") or file path (e.g., "./my-integration.json")
- * @returns The loaded IntegrationDSL
+ * @returns The loaded IntegrationDSL (unresolved)
  */
-export async function loadIntegrationDSL(
+async function loadRawIntegrationDSL(
   nameOrPath: string,
 ): Promise<IntegrationDSL> {
   // If path ends with .json, treat it as a JSON file path directly
@@ -40,3 +41,130 @@ export async function loadIntegrationDSL(
   const content = await readFile(nameOrPath, "utf-8");
   return JSON.parse(content) as IntegrationDSL;
 }
+
+/**
+ * Load a core integration DSL by name only (no file path fallback).
+ *
+ * Used for resolving `extends` chains, which only support core integration names
+ * (e.g., "supabase"), not file paths.
+ *
+ * @param name - Core integration name (e.g., "supabase")
+ * @returns The loaded IntegrationDSL (unresolved)
+ */
+async function loadCoreIntegrationDSL(name: string): Promise<IntegrationDSL> {
+  try {
+    const module = await import(`../../core/integrations/${name}.ts`);
+    if (name in module) {
+      return module[name] as IntegrationDSL;
+    }
+  } catch {
+    // Module not found
+  }
+  throw new Error(
+    `Unknown core integration: "${name}". extends only supports core integration names (e.g., "supabase").`,
+  );
+}
+
+/**
+ * Load an integration DSL, recursively resolving `extends` chains.
+ *
+ * When an integration has `extends`, the referenced integration(s) are loaded
+ * and merged: filters are AND-combined, serialize rules concatenated (base first),
+ * and emptyCatalog uses the most-specific value.
+ *
+ * Circular extends are detected and rejected with a descriptive error.
+ *
+ * @param nameOrPath - Integration name (e.g., "supabase") or file path
+ * @returns The fully resolved IntegrationDSL
+ */
+export async function loadIntegrationDSL(
+  nameOrPath: string,
+): Promise<IntegrationDSL> {
+  return resolveIntegration(nameOrPath, new Set());
+}
+
+async function resolveIntegration(
+  nameOrPath: string,
+  visited: Set<string>,
+  preloadedRaw?: IntegrationDSL,
+): Promise<IntegrationDSL> {
+  if (visited.has(nameOrPath)) {
+    throw new Error(
+      `Circular extends detected: ${[...visited, nameOrPath].join(" → ")}`,
+    );
+  }
+  visited.add(nameOrPath);
+
+  const raw = preloadedRaw ?? (await loadRawIntegrationDSL(nameOrPath));
+
+  if (!raw.extends) {
+    return raw;
+  }
+
+  // Resolve base integrations (extends only supports core integration names)
+  const extendsArray = Array.isArray(raw.extends) ? raw.extends : [raw.extends];
+
+  const baseIntegrations: IntegrationDSL[] = [];
+  for (const baseName of extendsArray) {
+    const baseRaw = await loadCoreIntegrationDSL(baseName);
+    baseIntegrations.push(
+      await resolveIntegration(baseName, new Set(visited), baseRaw),
+    );
+  }
+
+  // Remove extends from the current integration before merging
+  const { extends: _, ...current } = raw;
+
+  // Merge: bases first (higher priority serialize), then current (most-specific)
+  return mergeIntegrations([...baseIntegrations, current]);
+}
+
+interface ResolvedIntegrationOptions {
+  filter?: FilterDSL;
+  serialize?: SerializeDSL;
+  emptyCatalog?: CatalogSnapshot;
+}
+
+/**
+ * Load an integration (if provided) and merge its filter/serialize with CLI flags.
+ *
+ * - Filters are AND-combined (integration ∧ CLI flag)
+ * - Serialize rules are concatenated (integration first = higher priority)
+ * - emptyCatalog is extracted from the integration
+ */
+export async function resolveIntegrationOptions(options: {
+  filter?: FilterDSL;
+  serialize?: SerializeDSL;
+  integration?: string;
+}): Promise<ResolvedIntegrationOptions> {
+  if (!options.integration) {
+    return {
+      filter: options.filter,
+      serialize: options.serialize,
+    };
+  }
+
+  const integrationDSL = await loadIntegrationDSL(options.integration);
+
+  // AND-combine integration filter with CLI --filter
+  let filter: FilterDSL | undefined;
+  if (integrationDSL.filter && options.filter) {
+    filter = { and: [integrationDSL.filter, options.filter] };
+  } else {
+    filter = options.filter ?? integrationDSL.filter;
+  }
+
+  // Concatenate serialize rules (integration first = higher priority)
+  let serialize: SerializeDSL | undefined;
+  if (integrationDSL.serialize && options.serialize) {
+    serialize = [...integrationDSL.serialize, ...options.serialize];
+  } else {
+    serialize = options.serialize ?? integrationDSL.serialize;
+  }
+
+  return {
+    filter,
+    serialize,
+    emptyCatalog: integrationDSL.emptyCatalog,
+  };
+}

package/src/core/catalog.snapshot.test.ts

@@ -452,7 +452,11 @@ describe("catalog snapshot serde", () => {
 
     // Filter out auth schema (no cascade): procedure is excluded but policy stays
     const resultNoCascade = await createPlan(null, target, {
-      filter: { not: { schema: ["auth"] } },
+      filter: {
+        not: {
+          or: [{ "*/schema": ["auth"] }, { "schema/name": ["auth"] }],
+        },
+      },
     });
     expect(resultNoCascade).not.toBeNull();
     if (resultNoCascade) {
@@ -464,7 +468,12 @@ describe("catalog snapshot serde", () => {
 
     // Filter out auth schema with cascade: true: policy is also excluded (depends on auth.uid())
     const resultCascade = await createPlan(null, target, {
-      filter: { not: { schema: ["auth"] }, cascade: true },
+      filter: {
+        not: {
+          or: [{ "*/schema": ["auth"] }, { "schema/name": ["auth"] }],
+        },
+        cascade: true,
+      },
     });
     expect(resultCascade).not.toBeNull();
     if (resultCascade) {