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

package/dist/core/export/index.js

@@ -0,0 +1,66 @@
+/**
+ * Declarative schema export.
+ */
+import { buildPlanScopeFingerprint, hashStableIds } from "../fingerprint.js";
+import { resolveIntegration, } from "../integrations/integration.types.js";
+import { DEFAULT_OPTIONS } from "../plan/sql-format/constants.js";
+import { formatSqlScript } from "../plan/statements.js";
+import { createFileMapper } from "./file-mapper.js";
+import { groupChangesByFile } from "./grouper.js";
+/**
+ * Export a declarative schema from a plan result.
+ *
+ * Takes the output of `createPlan()` and generates a declarative schema output
+ * with files grouped by object type. Drop operations are excluded since
+ * declarative mode targets the final desired state.
+ *
+ * Dependency-based filtering (cascading exclusions) is handled by `createPlan`,
+ * so this function only needs to filter out drop operations.
+ *
+ * @param planResult - The result from createPlan() containing plan, sortedChanges, and ctx
+ * @param options - Optional integration for custom serialization
+ * @returns Declarative schema output with grouped files
+ */
+export function exportDeclarativeSchema(planResult, options) {
+    const { ctx, sortedChanges } = planResult;
+    const integration = options?.integration
+        ? resolveIntegration(options?.integration)
+        : {};
+    const formatOptions = options?.formatOptions === null
+        ? undefined
+        : {
+            ...DEFAULT_OPTIONS,
+            maxWidth: 180,
+            keywordCase: "upper",
+            ...options?.formatOptions,
+        };
+    // Drop filtering and dependency cascading are handled upstream by createPlan.
+    const { hash: sourceFingerprint, stableIds } = buildPlanScopeFingerprint(ctx.mainCatalog, sortedChanges);
+    const targetFingerprint = hashStableIds(ctx.branchCatalog, stableIds);
+    const mapper = createFileMapper(options?.grouping, options?.onWarning);
+    const groups = groupChangesByFile(sortedChanges, mapper);
+    const files = groups.map((group, index) => {
+        const statements = group.changes.map((change) => serializeChange(change, integration));
+        return buildFileEntry(group.path, group.metadata, statements, index, formatOptions);
+    });
+    return {
+        version: 1,
+        mode: "declarative",
+        generatedAt: new Date().toISOString(),
+        source: { fingerprint: sourceFingerprint },
+        target: { fingerprint: targetFingerprint },
+        files,
+    };
+}
+function serializeChange(change, integration) {
+    return integration?.serialize?.(change) ?? change.serialize();
+}
+function buildFileEntry(path, metadata, statements, order, formatOptions) {
+    return {
+        path,
+        order,
+        statements: statements.length,
+        sql: formatSqlScript(statements, formatOptions),
+        metadata,
+    };
+}

package/dist/core/export/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Type definitions for declarative schema export.
+ */
+export declare const CATEGORY_PRIORITY: {
+    readonly cluster: 0;
+    readonly schema: 1;
+    readonly extensions: 2;
+    readonly types: 3;
+    readonly sequences: 4;
+    readonly tables: 5;
+    readonly foreign_tables: 6;
+    readonly views: 7;
+    readonly matviews: 8;
+    readonly functions: 9;
+    readonly procedures: 10;
+    readonly aggregates: 11;
+    readonly domains: 12;
+    readonly collations: 13;
+    readonly publications: 14;
+    readonly subscriptions: 15;
+    readonly event_triggers: 16;
+};
+export type FileCategory = keyof typeof CATEGORY_PRIORITY;
+export interface FileMetadata {
+    objectType: string;
+    schemaName?: string;
+    objectName?: string;
+}
+export interface FileEntry {
+    path: string;
+    order: number;
+    statements: number;
+    sql: string;
+    metadata: FileMetadata;
+}
+export interface DeclarativeSchemaOutput {
+    version: 1;
+    mode: "declarative";
+    generatedAt: string;
+    source: {
+        fingerprint: string;
+    };
+    target: {
+        fingerprint: string;
+    };
+    files: FileEntry[];
+}
+/** A regex pattern with a group name used as the directory or file name. */
+export interface GroupingPattern {
+    /** Regex to test against the object name. Strings are compiled to RegExp. */
+    pattern: string | RegExp;
+    /** Group name used as the directory or file name. */
+    name: string;
+}
+export interface Grouping {
+    /** How grouped entities are organized on disk. */
+    mode: "single-file" | "subdirectory";
+    /**
+     * Regex-based patterns to match object names.
+     * First matching pattern wins -- ordering controls priority.
+     *
+     * Examples:
+     * - `{ pattern: /^project/, name: "project" }`  – prefix
+     * - `{ pattern: /organization/, name: "organization" }` – contains
+     * - `{ pattern: /tokens$/, name: "tokens" }` – suffix
+     */
+    groupPatterns?: GroupingPattern[];
+    /**
+     * Automatically detect partitioned tables and group partitions with
+     * their parent table.  Defaults to `true`.
+     */
+    autoGroupPartitions?: boolean;
+    /**
+     * Schemas to flatten: all objects are merged into one file per category.
+     * e.g. `schemas/partman/tables.sql` instead of `schemas/partman/tables/foo.sql`.
+     * Useful for small or extension schemas that don't need per-object files.
+     */
+    flatSchemas?: string[];
+}
+export interface FilePath {
+    path: string;
+    category: FileCategory;
+    metadata: FileMetadata;
+}

package/dist/core/export/types.js

@@ -0,0 +1,25 @@
+/**
+ * Type definitions for declarative schema export.
+ */
+// ============================================================================
+// File Categories
+// ============================================================================
+export const CATEGORY_PRIORITY = {
+    cluster: 0,
+    schema: 1,
+    extensions: 2,
+    types: 3,
+    sequences: 4,
+    tables: 5,
+    foreign_tables: 6,
+    views: 7,
+    matviews: 8,
+    functions: 9,
+    procedures: 10,
+    aggregates: 11,
+    domains: 12,
+    collations: 13,
+    publications: 14,
+    subscriptions: 15,
+    event_triggers: 16,
+};

package/dist/core/fixtures/empty-catalogs/postgres-15-16-baseline.json

@@ -0,0 +1,287 @@
+{
+    "version": 150014,
+    "currentUser": "postgres",
+    "aggregates": {},
+    "collations": {},
+    "compositeTypes": {},
+    "domains": {},
+    "enums": {},
+    "extensions": {
+        "extension:plpgsql": {
+            "name": "plpgsql",
+            "schema": "pg_catalog",
+            "relocatable": false,
+            "version": "1.0",
+            "owner": "postgres",
+            "comment": "PL/pgSQL procedural language",
+            "members": [
+                "procedure:pg_catalog.plpgsql_call_handler()",
+                "procedure:pg_catalog.plpgsql_inline_handler(internal)",
+                "procedure:pg_catalog.plpgsql_validator(oid)"
+            ]
+        }
+    },
+    "procedures": {},
+    "indexes": {},
+    "materializedViews": {},
+    "subscriptions": {},
+    "publications": {},
+    "rlsPolicies": {},
+    "roles": {
+        "role:postgres": {
+            "name": "postgres",
+            "is_superuser": true,
+            "can_inherit": true,
+            "can_create_roles": true,
+            "can_create_databases": true,
+            "can_login": true,
+            "can_replicate": true,
+            "connection_limit": -1,
+            "can_bypass_rls": true,
+            "config": null,
+            "comment": null,
+            "members": [],
+            "default_privileges": [
+                {
+                    "in_schema": null,
+                    "objtype": "S",
+                    "grantee": "postgres",
+                    "privileges": [
+                        {
+                            "privilege": "USAGE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "T",
+                    "grantee": "PUBLIC",
+                    "privileges": [
+                        {
+                            "privilege": "USAGE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "T",
+                    "grantee": "postgres",
+                    "privileges": [
+                        {
+                            "privilege": "USAGE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "f",
+                    "grantee": "PUBLIC",
+                    "privileges": [
+                        {
+                            "privilege": "EXECUTE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "f",
+                    "grantee": "postgres",
+                    "privileges": [
+                        {
+                            "privilege": "EXECUTE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "n",
+                    "grantee": "postgres",
+                    "privileges": [
+                        {
+                            "privilege": "CREATE",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "USAGE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                },
+                {
+                    "in_schema": null,
+                    "objtype": "r",
+                    "grantee": "postgres",
+                    "privileges": [
+                        {
+                            "privilege": "DELETE",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "INSERT",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "REFERENCES",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "SELECT",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "TRIGGER",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "TRUNCATE",
+                            "grantable": false
+                        },
+                        {
+                            "privilege": "UPDATE",
+                            "grantable": false
+                        }
+                    ],
+                    "is_implicit": true
+                }
+            ]
+        }
+    },
+    "schemas": {
+        "schema:public": {
+            "name": "public",
+            "owner": "pg_database_owner",
+            "comment": "standard public schema",
+            "privileges": [
+                {
+                    "grantee": "PUBLIC",
+                    "privilege": "USAGE",
+                    "grantable": false
+                },
+                {
+                    "grantee": "pg_database_owner",
+                    "privilege": "CREATE",
+                    "grantable": false
+                },
+                {
+                    "grantee": "pg_database_owner",
+                    "privilege": "USAGE",
+                    "grantable": false
+                }
+            ]
+        }
+    },
+    "sequences": {},
+    "tables": {},
+    "triggers": {},
+    "eventTriggers": {},
+    "rules": {},
+    "ranges": {},
+    "views": {},
+    "foreignDataWrappers": {},
+    "servers": {},
+    "userMappings": {},
+    "foreignTables": {},
+    "depends": [
+        {
+            "dependent_stable_id": "acl:schema:public::grantee:pg_database_owner",
+            "referenced_stable_id": "role:pg_database_owner",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "acl:schema:public::grantee:pg_database_owner",
+            "referenced_stable_id": "schema:public",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "acl:schema:public::grantee:PUBLIC",
+            "referenced_stable_id": "role:PUBLIC",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "acl:schema:public::grantee:PUBLIC",
+            "referenced_stable_id": "schema:public",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "comment:extension:plpgsql",
+            "referenced_stable_id": "extension:plpgsql",
+            "deptype": "a"
+        },
+        {
+            "dependent_stable_id": "comment:language:plpgsql",
+            "referenced_stable_id": "language:plpgsql",
+            "deptype": "a"
+        },
+        {
+            "dependent_stable_id": "comment:language:sql",
+            "referenced_stable_id": "language:sql",
+            "deptype": "a"
+        },
+        {
+            "dependent_stable_id": "language:plpgsql",
+            "referenced_stable_id": "procedure:pg_catalog.plpgsql_call_handler()",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "language:plpgsql",
+            "referenced_stable_id": "procedure:pg_catalog.plpgsql_inline_handler(internal)",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "language:plpgsql",
+            "referenced_stable_id": "procedure:pg_catalog.plpgsql_validator(oid)",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "language:plpgsql",
+            "referenced_stable_id": "role:postgres",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_read_all_settings->pg_monitor",
+            "referenced_stable_id": "role:pg_monitor",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_read_all_settings->pg_monitor",
+            "referenced_stable_id": "role:pg_read_all_settings",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_read_all_stats->pg_monitor",
+            "referenced_stable_id": "role:pg_monitor",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_read_all_stats->pg_monitor",
+            "referenced_stable_id": "role:pg_read_all_stats",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_stat_scan_tables->pg_monitor",
+            "referenced_stable_id": "role:pg_monitor",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "membership:pg_stat_scan_tables->pg_monitor",
+            "referenced_stable_id": "role:pg_stat_scan_tables",
+            "deptype": "n"
+        },
+        {
+            "dependent_stable_id": "schema:public",
+            "referenced_stable_id": "role:pg_database_owner",
+            "deptype": "n"
+        }
+    ]
+}

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

@@ -1,72 +1,113 @@
 /**
  * Filter DSL - A serializable domain-specific language for change filtering.
+ *
+ * Uses wildcard-based path matching on flattened change properties.
+ * Path patterns as keys, values as matchers. Multiple keys in one object = AND.
+ *
+ * Path convention:
+ * - Top-level change properties are bare keys: `objectType`, `operation`, `scope`, `member`, `grantee`
+ * - Model sub-object properties use `<objectType>/<field>`: `table/schema`, `role/name`
+ * - Wildcard `*` matches any single path segment: `* /schema` → `table/schema`, `view/schema`, etc.
+ * - Separator is `/`
+ *
+ * Value matching:
+ * - string → exact equality
+ * - string[] → value must be in array (inclusion)
+ * - boolean → exact equality
+ * - number → exact equality
+ * - { op: "regex", value: string | string[] } → regex test
+ *
+ * When the flat value is an array (e.g. `requires`), match succeeds if any element satisfies.
  */
 import type { Change } from "../../change.types.ts";
 import type { ChangeFilter } from "./filter.types.ts";
 /**
- * Core properties that all changes have.
+ * Regex operator for advanced value matching.
  */
-type CoreProperties = {
-    type?: Change["objectType"];
-    operation?: "create" | "alter" | "drop";
-    scope?: Change["scope"];
+type RegexOperator = {
+    op: "regex";
+    value: string | string[];
 };
 /**
- * Extracted properties that are extracted from changes via extractor functions.
- * String value = exact match, Array value = value must be in array
+ * A value matcher for a path pattern key.
  */
-type ExtractedProperties = {
-    schema?: string | string[];
-    owner?: string | string[];
-    member?: string | string[];
-};
+type ValueMatcher = string | string[] | boolean | number | RegexOperator;
 /**
- * Property pattern - matches against change properties.
- * Multiple properties are combined with AND (all must match).
+ * Path pattern — matches against flattened change properties.
+ * Keys are path patterns (with optional wildcards), values are matchers.
+ * Multiple keys are combined with AND (all must match).
+ *
+ * Reserved keys: `and`, `or`, `not`, `cascade`.
+ *
+ * @example
+ * ```json
+ * { "objectType": "table", "operation": "create" }
+ * ```
+ *
+ * @example Wildcard path matching any object's schema
+ * ```json
+ * { "* /schema": "public" }
+ * ```
+ *
+ * @category Filter DSL
  */
-type PropertyPattern = CoreProperties & ExtractedProperties & {
+export type PathPattern = {
+    [path: string]: ValueMatcher;
+} & {
+    cascade?: boolean;
     and?: never;
     or?: never;
     not?: never;
 };
 /**
  * Composition pattern - combines other patterns using logical operators.
- * Composition operators are exclusive - cannot be mixed with properties.
+ * Composition operators are exclusive - cannot be mixed with path keys.
  */
-type CompositionPattern = ({
+type CompositionPattern = {
     and: FilterPattern[];
+    cascade?: boolean;
     or?: never;
     not?: never;
-} & {
-    [K in keyof CoreProperties]?: never;
-} & {
-    [K in keyof ExtractedProperties]?: never;
-}) | ({
+} | {
     or: FilterPattern[];
+    cascade?: boolean;
     and?: never;
     not?: never;
-} & {
-    [K in keyof CoreProperties]?: never;
-} & {
-    [K in keyof ExtractedProperties]?: never;
-}) | ({
+} | {
     not: FilterPattern;
+    cascade?: boolean;
     and?: never;
     or?: never;
-} & {
-    [K in keyof CoreProperties]?: never;
-} & {
-    [K in keyof ExtractedProperties]?: never;
-});
+};
 /**
- * Filter pattern DSL.
- * Either a property pattern (matches against change properties) or
- * a composition pattern (combines other patterns using logical operators).
- * Composition operators are exclusive - cannot be mixed with properties.
+ * A single filter expression: either a {@link PathPattern} that matches against
+ * flattened change properties, or a composition pattern that combines other
+ * patterns using `and` / `or` / `not` logical operators.
+ *
+ * @example Exclude all changes in pg_catalog
+ * ```json
+ * { "not": { "* /schema": "pg_catalog" } }
+ * ```
+ *
+ * @category Filter DSL
  */
-export type FilterPattern = PropertyPattern | CompositionPattern;
+export type FilterPattern = PathPattern | CompositionPattern;
 /**
- * Filter DSL - a single pattern expression.
+ * Top-level Filter DSL type — a single {@link FilterPattern} expression that
+ * determines which changes an integration includes or excludes.
+ *
+ * @example Include only table and view creates in public
+ * ```json
+ * {
+ *   "and": [
+ *     { "objectType": ["table", "view"] },
+ *     { "operation": "create" },
+ *     { "* /schema": "public" }
+ *   ]
+ * }
+ * ```
+ *
+ * @category Filter DSL
  */
 export type FilterDSL = FilterPattern;
 /**
@@ -84,11 +125,11 @@ export declare function evaluatePattern(pattern: FilterPattern, change: Change):
  * @returns A ChangeFilter function that evaluates the pattern
  *
  * @example
- * ```ts
+ * ```
  * const filter = compileFilterDSL({
  *   or: [
- *     { type: "schema", operation: "create" },
- *     { schema: "public" }
+ *     { objectType: "schema", operation: "create" },
+ *     { "table/schema": "public" }
  *   ]
  * });
  * ```