@supabase/pg-delta 0.0.0 → 1.0.0-alpha.0

package/dist/core/objects/foreign-data-wrapper/server/server.diff.js

@@ -0,0 +1,209 @@
+import { diffObjects } from "../../base.diff.js";
+import { diffPrivileges, filterPublicBuiltInDefaults, groupPrivilegesByGrantable, } from "../../base.privilege-diff.js";
+import { AlterServerChangeOwner, AlterServerSetOptions, AlterServerSetVersion, } from "./changes/server.alter.js";
+import { CreateCommentOnServer, DropCommentOnServer, } from "./changes/server.comment.js";
+import { CreateServer } from "./changes/server.create.js";
+import { DropServer } from "./changes/server.drop.js";
+import { GrantServerPrivileges, RevokeGrantOptionServerPrivileges, RevokeServerPrivileges, } from "./changes/server.privilege.js";
+/**
+ * Diff two sets of servers from main and branch catalogs.
+ *
+ * @param ctx - Context containing version, currentUser, and defaultPrivilegeState
+ * @param main - The servers in the main catalog.
+ * @param branch - The servers in the branch catalog.
+ * @returns A list of changes to apply to main to make it match branch.
+ */
+export function diffServers(ctx, main, branch) {
+    const { created, dropped, altered } = diffObjects(main, branch);
+    const changes = [];
+    for (const serverId of created) {
+        const createdServer = branch[serverId];
+        changes.push(new CreateServer({ server: createdServer }));
+        // OWNER: If the server should be owned by someone other than the current user,
+        // emit ALTER SERVER ... OWNER TO after creation
+        if (createdServer.owner !== ctx.currentUser) {
+            changes.push(new AlterServerChangeOwner({
+                server: createdServer,
+                owner: createdServer.owner,
+            }));
+        }
+        if (createdServer.comment !== null) {
+            changes.push(new CreateCommentOnServer({ server: createdServer }));
+        }
+        // PRIVILEGES: Servers don't have default privileges
+        const effectiveDefaults = [];
+        const desiredPrivileges = filterPublicBuiltInDefaults("server", createdServer.privileges);
+        const privilegeResults = diffPrivileges(effectiveDefaults, desiredPrivileges, createdServer.owner, ctx.mainRoles);
+        // Generate grant changes
+        for (const [grantee, result] of privilegeResults) {
+            if (result.grants.length > 0) {
+                const grantGroups = groupPrivilegesByGrantable(result.grants);
+                for (const [grantable, list] of grantGroups) {
+                    void grantable;
+                    changes.push(new GrantServerPrivileges({
+                        server: createdServer,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            // Generate revoke changes
+            if (result.revokes.length > 0) {
+                const revokeGroups = groupPrivilegesByGrantable(result.revokes);
+                for (const [grantable, list] of revokeGroups) {
+                    void grantable;
+                    changes.push(new RevokeServerPrivileges({
+                        server: createdServer,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            // Generate revoke grant option changes
+            if (result.revokeGrantOption.length > 0) {
+                changes.push(new RevokeGrantOptionServerPrivileges({
+                    server: createdServer,
+                    grantee,
+                    privilegeNames: result.revokeGrantOption,
+                    version: ctx.version,
+                }));
+            }
+        }
+    }
+    for (const serverId of dropped) {
+        changes.push(new DropServer({ server: main[serverId] }));
+    }
+    for (const serverId of altered) {
+        const mainServer = main[serverId];
+        const branchServer = branch[serverId];
+        // OWNER
+        if (mainServer.owner !== branchServer.owner) {
+            changes.push(new AlterServerChangeOwner({
+                server: mainServer,
+                owner: branchServer.owner,
+            }));
+        }
+        // TYPE - if changed, need to recreate (not directly alterable)
+        if (mainServer.type !== branchServer.type) {
+            changes.push(new DropServer({ server: mainServer }));
+            changes.push(new CreateServer({ server: branchServer }));
+            if (branchServer.comment !== null) {
+                changes.push(new CreateCommentOnServer({ server: branchServer }));
+            }
+            continue;
+        }
+        // VERSION
+        if (mainServer.version !== branchServer.version) {
+            changes.push(new AlterServerSetVersion({
+                server: mainServer,
+                version: branchServer.version,
+            }));
+        }
+        // OPTIONS
+        const optionsChanged = diffOptions(mainServer.options, branchServer.options);
+        if (optionsChanged.length > 0) {
+            changes.push(new AlterServerSetOptions({
+                server: mainServer,
+                options: optionsChanged,
+            }));
+        }
+        // COMMENT
+        if (mainServer.comment !== branchServer.comment) {
+            if (branchServer.comment === null) {
+                changes.push(new DropCommentOnServer({ server: mainServer }));
+            }
+            else {
+                changes.push(new CreateCommentOnServer({ server: branchServer }));
+            }
+        }
+        // PRIVILEGES
+        const mainPrivilegesFiltered = filterPublicBuiltInDefaults("server", mainServer.privileges);
+        const branchPrivilegesFiltered = filterPublicBuiltInDefaults("server", branchServer.privileges);
+        const privilegeResults = diffPrivileges(mainPrivilegesFiltered, branchPrivilegesFiltered, branchServer.owner, ctx.mainRoles);
+        for (const [grantee, result] of privilegeResults) {
+            // Generate grant changes
+            if (result.grants.length > 0) {
+                const grantGroups = groupPrivilegesByGrantable(result.grants);
+                for (const [grantable, list] of grantGroups) {
+                    void grantable;
+                    changes.push(new GrantServerPrivileges({
+                        server: branchServer,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            // Generate revoke changes
+            if (result.revokes.length > 0) {
+                const revokeGroups = groupPrivilegesByGrantable(result.revokes);
+                for (const [grantable, list] of revokeGroups) {
+                    void grantable;
+                    changes.push(new RevokeServerPrivileges({
+                        server: mainServer,
+                        grantee,
+                        privileges: list,
+                        version: ctx.version,
+                    }));
+                }
+            }
+            // Generate revoke grant option changes
+            if (result.revokeGrantOption.length > 0) {
+                changes.push(new RevokeGrantOptionServerPrivileges({
+                    server: mainServer,
+                    grantee,
+                    privilegeNames: result.revokeGrantOption,
+                    version: ctx.version,
+                }));
+            }
+        }
+        // Note: Server renaming would also use ALTER SERVER ... RENAME TO ...
+        // But since our Server model uses 'name' as the identity field,
+        // a name change would be handled as drop + create by diffObjects()
+    }
+    return changes;
+}
+/**
+ * Diff options arrays to determine ADD/SET/DROP operations.
+ * Options are stored as [key1, value1, key2, value2, ...]
+ */
+function diffOptions(mainOptions, branchOptions) {
+    const mainMap = new Map();
+    const branchMap = new Map();
+    // Parse main options
+    if (mainOptions) {
+        for (let i = 0; i < mainOptions.length; i += 2) {
+            if (i + 1 < mainOptions.length) {
+                mainMap.set(mainOptions[i], mainOptions[i + 1]);
+            }
+        }
+    }
+    // Parse branch options
+    if (branchOptions) {
+        for (let i = 0; i < branchOptions.length; i += 2) {
+            if (i + 1 < branchOptions.length) {
+                branchMap.set(branchOptions[i], branchOptions[i + 1]);
+            }
+        }
+    }
+    const changes = [];
+    // Find options to ADD or SET
+    for (const [key, value] of branchMap) {
+        const mainValue = mainMap.get(key);
+        if (mainValue === undefined) {
+            changes.push({ action: "ADD", option: key, value });
+        }
+        else if (mainValue !== value) {
+            changes.push({ action: "SET", option: key, value });
+        }
+    }
+    // Find options to DROP
+    for (const [key] of mainMap) {
+        if (!branchMap.has(key)) {
+            changes.push({ action: "DROP", option: key });
+        }
+    }
+    return changes;
+}

package/dist/core/objects/foreign-data-wrapper/server/server.model.d.ts

@@ -0,0 +1,62 @@
+import type { Sql } from "postgres";
+import z from "zod";
+import { BasePgModel } from "../../base.model.ts";
+import { type PrivilegeProps } from "../../base.privilege-diff.ts";
+/**
+ * All properties exposed by CREATE SERVER statement are included in diff output.
+ * https://www.postgresql.org/docs/17/sql-createserver.html
+ *
+ * ALTER SERVER statement can be generated for changes to the following properties:
+ *  - owner, type, version, options
+ * https://www.postgresql.org/docs/17/sql-alterserver.html
+ *
+ * Servers are not schema-qualified (no schema property).
+ */
+declare const serverPropsSchema: z.ZodObject<{
+    name: z.ZodString;
+    owner: z.ZodString;
+    foreign_data_wrapper: z.ZodString;
+    type: z.ZodNullable<z.ZodString>;
+    version: z.ZodNullable<z.ZodString>;
+    options: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    comment: z.ZodNullable<z.ZodString>;
+    privileges: z.ZodArray<z.ZodObject<{
+        grantee: z.ZodString;
+        privilege: z.ZodString;
+        grantable: z.ZodBoolean;
+        columns: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    }, z.z.core.$strip>>;
+}, z.z.core.$strip>;
+type ServerPrivilegeProps = PrivilegeProps;
+export type ServerProps = z.infer<typeof serverPropsSchema>;
+export declare class Server extends BasePgModel {
+    readonly name: ServerProps["name"];
+    readonly owner: ServerProps["owner"];
+    readonly foreign_data_wrapper: ServerProps["foreign_data_wrapper"];
+    readonly type: ServerProps["type"];
+    readonly version: ServerProps["version"];
+    readonly options: ServerProps["options"];
+    readonly comment: ServerProps["comment"];
+    readonly privileges: ServerPrivilegeProps[];
+    constructor(props: ServerProps);
+    get stableId(): `server:${string}`;
+    get identityFields(): {
+        name: string;
+    };
+    get dataFields(): {
+        owner: string;
+        foreign_data_wrapper: string;
+        type: string | null;
+        version: string | null;
+        options: string[] | null;
+        comment: string | null;
+        privileges: {
+            grantee: string;
+            privilege: string;
+            grantable: boolean;
+            columns?: string[] | null | undefined;
+        }[];
+    };
+}
+export declare function extractServers(sql: Sql): Promise<Server[]>;
+export {};

package/dist/core/objects/foreign-data-wrapper/server/server.model.js

@@ -0,0 +1,118 @@
+import z from "zod";
+import { BasePgModel } from "../../base.model.js";
+import { privilegePropsSchema, } from "../../base.privilege-diff.js";
+/**
+ * All properties exposed by CREATE SERVER statement are included in diff output.
+ * https://www.postgresql.org/docs/17/sql-createserver.html
+ *
+ * ALTER SERVER statement can be generated for changes to the following properties:
+ *  - owner, type, version, options
+ * https://www.postgresql.org/docs/17/sql-alterserver.html
+ *
+ * Servers are not schema-qualified (no schema property).
+ */
+const serverPropsSchema = z.object({
+    name: z.string(),
+    owner: z.string(),
+    foreign_data_wrapper: z.string(),
+    type: z.string().nullable(),
+    version: z.string().nullable(),
+    options: z.array(z.string()).nullable(),
+    comment: z.string().nullable(),
+    privileges: z.array(privilegePropsSchema),
+});
+export class Server extends BasePgModel {
+    name;
+    owner;
+    foreign_data_wrapper;
+    type;
+    version;
+    options;
+    comment;
+    privileges;
+    constructor(props) {
+        super();
+        // Identity fields
+        this.name = props.name;
+        // Data fields
+        this.owner = props.owner;
+        this.foreign_data_wrapper = props.foreign_data_wrapper;
+        this.type = props.type;
+        this.version = props.version;
+        this.options = props.options;
+        this.comment = props.comment;
+        this.privileges = props.privileges;
+    }
+    get stableId() {
+        return `server:${this.name}`;
+    }
+    get identityFields() {
+        return {
+            name: this.name,
+        };
+    }
+    get dataFields() {
+        return {
+            owner: this.owner,
+            foreign_data_wrapper: this.foreign_data_wrapper,
+            type: this.type,
+            version: this.version,
+            options: this.options,
+            comment: this.comment,
+            privileges: this.privileges,
+        };
+    }
+}
+export async function extractServers(sql) {
+    return sql.begin(async (sql) => {
+        await sql `set search_path = ''`;
+        const serverRows = await sql `
+      select
+        quote_ident(srv.srvname) as name,
+        srv.srvowner::regrole::text as owner,
+        quote_ident(fdw.fdwname) as foreign_data_wrapper,
+        srv.srvtype as type,
+        srv.srvversion as version,
+        coalesce(srv.srvoptions, array[]::text[]) as options,
+        obj_description(srv.oid, 'pg_foreign_server') as comment,
+        coalesce(
+          (
+            select json_agg(
+              json_build_object(
+                'grantee', case when x.grantee = 0 then 'PUBLIC' else x.grantee::regrole::text end,
+                'privilege', x.privilege_type,
+                'grantable', x.is_grantable
+              )
+              order by x.grantee, x.privilege_type
+            )
+            from lateral aclexplode(srv.srvacl) as x(grantor, grantee, privilege_type, is_grantable)
+          ), '[]'
+        ) as privileges
+      from
+        pg_catalog.pg_foreign_server srv
+        inner join pg_catalog.pg_foreign_data_wrapper fdw on fdw.oid = srv.srvfdw
+      where
+        not fdw.fdwname like any(array['pg\\_%'])
+      order by
+        srv.srvname;
+    `;
+        // Validate and parse each row using the Zod schema
+        const validatedRows = serverRows.map((row) => {
+            const parsed = serverPropsSchema.parse(row);
+            // Parse options from PostgreSQL format ['key=value'] to ['key', 'value']
+            if (parsed.options && parsed.options.length > 0) {
+                const parsedOptions = [];
+                for (const opt of parsed.options) {
+                    const eqIndex = opt.indexOf("=");
+                    if (eqIndex > 0) {
+                        parsedOptions.push(opt.substring(0, eqIndex));
+                        parsedOptions.push(opt.substring(eqIndex + 1));
+                    }
+                }
+                parsed.options = parsedOptions.length > 0 ? parsedOptions : null;
+            }
+            return parsed;
+        });
+        return validatedRows.map((row) => new Server(row));
+    });
+}

package/dist/core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.alter.d.ts

@@ -0,0 +1,37 @@
+import type { UserMapping } from "../user-mapping.model.ts";
+import { AlterUserMappingChange } from "./user-mapping.base.ts";
+/**
+ * Alter a user mapping.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-alterusermapping.html
+ *
+ * Synopsis
+ * ```sql
+ * ALTER USER MAPPING FOR { user_name | USER | CURRENT_ROLE | CURRENT_USER | PUBLIC | SESSION_USER }
+ *     SERVER server_name
+ *     OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] )
+ * ```
+ */
+export type AlterUserMapping = AlterUserMappingSetOptions;
+/**
+ * ALTER USER MAPPING ... OPTIONS ( ADD | SET | DROP ... )
+ */
+export declare class AlterUserMappingSetOptions extends AlterUserMappingChange {
+    readonly userMapping: UserMapping;
+    readonly options: Array<{
+        action: "ADD" | "SET" | "DROP";
+        option: string;
+        value?: string;
+    }>;
+    readonly scope: "object";
+    constructor(props: {
+        userMapping: UserMapping;
+        options: Array<{
+            action: "ADD" | "SET" | "DROP";
+            option: string;
+            value?: string;
+        }>;
+    });
+    get requires(): `userMapping:${string}:${string}`[];
+    serialize(): string;
+}

package/dist/core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.alter.js

@@ -0,0 +1,38 @@
+import { quoteLiteral } from "../../../base.change.js";
+import { AlterUserMappingChange } from "./user-mapping.base.js";
+/**
+ * ALTER USER MAPPING ... OPTIONS ( ADD | SET | DROP ... )
+ */
+export class AlterUserMappingSetOptions extends AlterUserMappingChange {
+    userMapping;
+    options;
+    scope = "object";
+    constructor(props) {
+        super();
+        this.userMapping = props.userMapping;
+        this.options = props.options;
+    }
+    get requires() {
+        return [this.userMapping.stableId];
+    }
+    serialize() {
+        const optionParts = [];
+        for (const opt of this.options) {
+            if (opt.action === "DROP") {
+                optionParts.push(`DROP ${opt.option}`);
+            }
+            else {
+                const value = opt.value !== undefined ? quoteLiteral(opt.value) : "''";
+                optionParts.push(`${opt.action} ${opt.option} ${value}`);
+            }
+        }
+        return [
+            "ALTER USER MAPPING FOR",
+            this.userMapping.user,
+            "SERVER",
+            this.userMapping.server,
+            "OPTIONS",
+            `(${optionParts.join(", ")})`,
+        ].join(" ");
+    }
+}

package/dist/core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.base.d.ts

@@ -0,0 +1,17 @@
+import { BaseChange } from "../../../base.change.ts";
+import type { UserMapping } from "../user-mapping.model.ts";
+declare abstract class BaseUserMappingChange extends BaseChange {
+    abstract readonly userMapping: UserMapping;
+    abstract readonly scope: "object";
+    readonly objectType: "user_mapping";
+}
+export declare abstract class CreateUserMappingChange extends BaseUserMappingChange {
+    readonly operation: "create";
+}
+export declare abstract class AlterUserMappingChange extends BaseUserMappingChange {
+    readonly operation: "alter";
+}
+export declare abstract class DropUserMappingChange extends BaseUserMappingChange {
+    readonly operation: "drop";
+}
+export {};

package/dist/core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.base.js

@@ -0,0 +1,13 @@
+import { BaseChange } from "../../../base.change.js";
+class BaseUserMappingChange extends BaseChange {
+    objectType = "user_mapping";
+}
+export class CreateUserMappingChange extends BaseUserMappingChange {
+    operation = "create";
+}
+export class AlterUserMappingChange extends BaseUserMappingChange {
+    operation = "alter";
+}
+export class DropUserMappingChange extends BaseUserMappingChange {
+    operation = "drop";
+}

package/dist/core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.create.d.ts

@@ -0,0 +1,24 @@
+import type { UserMapping } from "../user-mapping.model.ts";
+import { CreateUserMappingChange } from "./user-mapping.base.ts";
+/**
+ * Create a user mapping.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-createusermapping.html
+ *
+ * Synopsis
+ * ```sql
+ * CREATE USER MAPPING [ IF NOT EXISTS ] FOR { user_name | USER | CURRENT_ROLE | CURRENT_USER | PUBLIC | SESSION_USER }
+ *     SERVER server_name
+ *     [ OPTIONS ( option 'value' [, ... ] ) ]
+ * ```
+ */
+export declare class CreateUserMapping extends CreateUserMappingChange {
+    readonly userMapping: UserMapping;
+    readonly scope: "object";
+    constructor(props: {
+        userMapping: UserMapping;
+    });
+    get creates(): `userMapping:${string}:${string}`[];
+    get requires(): string[];
+    serialize(): string;
+}

package/dist/core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.create.js

@@ -0,0 +1,52 @@
+import { quoteLiteral } from "../../../base.change.js";
+import { stableId } from "../../../utils.js";
+import { CreateUserMappingChange } from "./user-mapping.base.js";
+/**
+ * Create a user mapping.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-createusermapping.html
+ *
+ * Synopsis
+ * ```sql
+ * CREATE USER MAPPING [ IF NOT EXISTS ] FOR { user_name | USER | CURRENT_ROLE | CURRENT_USER | PUBLIC | SESSION_USER }
+ *     SERVER server_name
+ *     [ OPTIONS ( option 'value' [, ... ] ) ]
+ * ```
+ */
+export class CreateUserMapping extends CreateUserMappingChange {
+    userMapping;
+    scope = "object";
+    constructor(props) {
+        super();
+        this.userMapping = props.userMapping;
+    }
+    get creates() {
+        return [this.userMapping.stableId];
+    }
+    get requires() {
+        const dependencies = new Set();
+        // Server dependency
+        dependencies.add(stableId.server(this.userMapping.server));
+        return Array.from(dependencies);
+    }
+    serialize() {
+        const parts = ["CREATE USER MAPPING FOR"];
+        // Add user (can be CURRENT_USER, PUBLIC, etc.)
+        parts.push(this.userMapping.user);
+        // Add SERVER clause
+        parts.push("SERVER", this.userMapping.server);
+        // Add OPTIONS clause
+        if (this.userMapping.options && this.userMapping.options.length > 0) {
+            const optionPairs = [];
+            for (let i = 0; i < this.userMapping.options.length; i += 2) {
+                if (i + 1 < this.userMapping.options.length) {
+                    optionPairs.push(`${this.userMapping.options[i]} ${quoteLiteral(this.userMapping.options[i + 1])}`);
+                }
+            }
+            if (optionPairs.length > 0) {
+                parts.push(`OPTIONS (${optionPairs.join(", ")})`);
+            }
+        }
+        return parts.join(" ");
+    }
+}

package/dist/core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.drop.d.ts

@@ -0,0 +1,23 @@
+import type { UserMapping } from "../user-mapping.model.ts";
+import { DropUserMappingChange } from "./user-mapping.base.ts";
+/**
+ * Drop a user mapping.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-dropusermapping.html
+ *
+ * Synopsis
+ * ```sql
+ * DROP USER MAPPING [ IF EXISTS ] FOR { user_name | USER | CURRENT_ROLE | CURRENT_USER | PUBLIC | SESSION_USER }
+ *     SERVER server_name
+ * ```
+ */
+export declare class DropUserMapping extends DropUserMappingChange {
+    readonly userMapping: UserMapping;
+    readonly scope: "object";
+    constructor(props: {
+        userMapping: UserMapping;
+    });
+    get drops(): `userMapping:${string}:${string}`[];
+    get requires(): `userMapping:${string}:${string}`[];
+    serialize(): string;
+}

package/dist/core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.drop.js

@@ -0,0 +1,34 @@
+import { DropUserMappingChange } from "./user-mapping.base.js";
+/**
+ * Drop a user mapping.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-dropusermapping.html
+ *
+ * Synopsis
+ * ```sql
+ * DROP USER MAPPING [ IF EXISTS ] FOR { user_name | USER | CURRENT_ROLE | CURRENT_USER | PUBLIC | SESSION_USER }
+ *     SERVER server_name
+ * ```
+ */
+export class DropUserMapping extends DropUserMappingChange {
+    userMapping;
+    scope = "object";
+    constructor(props) {
+        super();
+        this.userMapping = props.userMapping;
+    }
+    get drops() {
+        return [this.userMapping.stableId];
+    }
+    get requires() {
+        return [this.userMapping.stableId];
+    }
+    serialize() {
+        return [
+            "DROP USER MAPPING FOR",
+            this.userMapping.user,
+            "SERVER",
+            this.userMapping.server,
+        ].join(" ");
+    }
+}

package/dist/core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.types.d.ts

@@ -0,0 +1,4 @@
+import type { AlterUserMapping } from "./user-mapping.alter.ts";
+import type { CreateUserMapping } from "./user-mapping.create.ts";
+import type { DropUserMapping } from "./user-mapping.drop.ts";
+export type UserMappingChange = AlterUserMapping | CreateUserMapping | DropUserMapping;

package/dist/core/objects/foreign-data-wrapper/user-mapping/changes/user-mapping.types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/objects/foreign-data-wrapper/user-mapping/user-mapping.diff.d.ts

@@ -0,0 +1,10 @@
+import type { UserMappingChange } from "./changes/user-mapping.types.ts";
+import type { UserMapping } from "./user-mapping.model.ts";
+/**
+ * Diff two sets of user mappings from main and branch catalogs.
+ *
+ * @param main - The user mappings in the main catalog.
+ * @param branch - The user mappings in the branch catalog.
+ * @returns A list of changes to apply to main to make it match branch.
+ */
+export declare function diffUserMappings(main: Record<string, UserMapping>, branch: Record<string, UserMapping>): UserMappingChange[];