appwrite-utils-cli/dist/migrations/services/UserMappingService.d.ts

Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.

import { z } from "zod";
import type { AttributeMappings, AppwriteConfig } from "appwrite-utils";
import { AuthUserCreateSchema } from "../../schemas/authUser.js";
import type { DataTransformationService } from "./DataTransformationService.js";
/**
 * Service responsible for user mapping and deduplication during import.
 * Preserves all existing sophisticated user handling logic from DataLoader.
 * Extracted to provide focused, testable user management operations.
 */
export declare class UserMappingService {
    private config;
    private dataTransformationService;
    private emailToUserIdMap;
    private phoneToUserIdMap;
    private userIdSet;
    private mergedUserMap;
    userExistsMap: Map<string, boolean>;
    constructor(config: AppwriteConfig, dataTransformationService: DataTransformationService);
    /**
     * Initializes user maps with existing users from the system.
     * Preserves existing user loading logic from DataLoader.
     *
     * @param existingUsers - Array of existing users from the system
     */
    initializeWithExistingUsers(existingUsers: any[]): void;
    /**
     * Generates a unique ID that doesn't conflict with existing user IDs.
     * Preserves existing unique ID generation logic from DataLoader.
     *
     * @param collectionName - The collection name for context
     * @returns A truly unique ID
     */
    getTrueUniqueUserId(collectionName: string): string;
    /**
     * Prepares user data by checking for duplicates based on email or phone, adding to a duplicate map if found,
     * and then returning the transformed item without user-specific keys.
     *
     * Preserves existing sophisticated user deduplication logic from DataLoader.
     *
     * @param item - The raw item to be processed.
     * @param attributeMappings - The attribute mappings for the item.
     * @param primaryKeyField - The primary key field name
     * @param newId - The proposed new ID for the user
     * @returns Object containing transformed item, existing ID if duplicate, and user data
     */
    prepareUserData(item: any, attributeMappings: AttributeMappings, primaryKeyField: string, newId: string): {
        transformedItem: any;
        existingId: string | undefined;
        userData: {
            rawData: any;
            finalData: z.infer<typeof AuthUserCreateSchema>;
        };
    };
    /**
     * Checks if a collection is the users collection based on configuration.
     *
     * @param collectionName - The collection name to check
     * @returns True if this is the users collection
     */
    isUsersCollection(collectionName: string): boolean;
    /**
     * Helper method to generate a consistent key for collections.
     * Preserves existing logic from DataLoader.
     */
    private getCollectionKey;
    /**
     * Gets merged user mappings for relationship resolution.
     *
     * @returns Map of merged user IDs to arrays of original IDs
     */
    getMergedUserMap(): Map<string, string[]>;
    /**
     * Finds the new user ID for an old user ID, considering merged users.
     * Preserves existing merged user lookup logic from DataLoader.
     *
     * @param oldId - The old user ID to look up
     * @returns The new user ID if found, otherwise the original ID
     */
    findNewUserIdForOldId(oldId: string): string;
    /**
     * Merges user data from duplicate entries.
     * Preserves existing user data merging logic.
     *
     * @param existingUserData - The existing user data
     * @param newUserData - The new user data to merge
     * @returns Merged user data
     */
    mergeUserData(existingUserData: any, newUserData: any): any;
    /**
     * Gets statistics about user mapping operations.
     * Useful for import planning and reporting.
     *
     * @returns User mapping statistics
     */
    getStatistics(): {
        totalExistingUsers: number;
        emailMappings: number;
        phoneMappings: number;
        mergedUsers: number;
        totalMergedOldIds: number;
    };
    /**
     * Validates user mapping configuration.
     * Ensures the user mapping setup is correct before import.
     *
     * @returns Array of validation errors (empty if valid)
     */
    validateConfiguration(): string[];
}