appwrite-utils-cli 1.11.0 → 1.12.0

package/dist/shared/relationshipExtractor.js

@@ -0,0 +1,138 @@
+/**
+ * Helper function to resolve collection name from ID or name
+ * @param config - Appwrite configuration containing collections
+ * @param idOrName - Collection ID or name to resolve
+ * @returns Resolved collection name, or the original input if not found
+ */
+export function resolveCollectionName(config, idOrName) {
+    const col = config.collections?.find((c) => c.$id === idOrName || c.name === idOrName);
+    return col?.name ?? idOrName;
+}
+/**
+ * Determines if a relationship type results in an array
+ * @param relationType - The type of relationship (oneToOne, oneToMany, manyToOne, manyToMany)
+ * @returns true if the relationship results in an array
+ */
+export function isArrayRelationship(relationType) {
+    return relationType === "oneToMany" || relationType === "manyToMany";
+}
+/**
+ * Extracts two-way relationship details from collections for Zod schema generation
+ * This handles complex bidirectional relationships with parent-child tracking
+ *
+ * @param config - Appwrite configuration containing collections
+ * @returns Map of collection names to their relationship details
+ */
+export function extractTwoWayRelationships(config) {
+    const relationshipMap = new Map();
+    if (!config.collections) {
+        return relationshipMap;
+    }
+    config.collections.forEach((collection) => {
+        if (!collection.attributes) {
+            return;
+        }
+        collection.attributes.forEach((attr) => {
+            if (attr.type === "relationship" && attr.twoWay && attr.twoWayKey) {
+                const relationshipAttr = attr;
+                let isArrayParent = false;
+                let isArrayChild = false;
+                switch (relationshipAttr.relationType) {
+                    case "oneToMany":
+                        isArrayParent = true;
+                        isArrayChild = false;
+                        break;
+                    case "manyToMany":
+                        isArrayParent = true;
+                        isArrayChild = true;
+                        break;
+                    case "oneToOne":
+                        isArrayParent = false;
+                        isArrayChild = false;
+                        break;
+                    case "manyToOne":
+                        isArrayParent = false;
+                        isArrayChild = true;
+                        break;
+                    default:
+                        break;
+                }
+                const relatedCollectionName = resolveCollectionName(config, relationshipAttr.relatedCollection);
+                addTwoWayRelationship(relationshipMap, collection.name, relatedCollectionName, attr.key, relationshipAttr.twoWayKey, isArrayParent, isArrayChild);
+                console.log(`Extracted relationship: ${attr.key}\n\t${collection.name} -> ${relationshipAttr.relatedCollection}, databaseId: ${collection.databaseId}`);
+            }
+        });
+    });
+    return relationshipMap;
+}
+/**
+ * Helper to add two-way relationship details to both parent and child collections
+ * @param relationshipMap - The map to add relationships to
+ * @param parentCollection - Parent collection name
+ * @param childCollection - Child collection name
+ * @param parentKey - Attribute key in parent collection
+ * @param childKey - Attribute key in child collection
+ * @param isArrayParent - Whether parent side is an array
+ * @param isArrayChild - Whether child side is an array
+ */
+function addTwoWayRelationship(relationshipMap, parentCollection, childCollection, parentKey, childKey, isArrayParent, isArrayChild) {
+    const relationshipsChild = relationshipMap.get(childCollection) || [];
+    const relationshipsParent = relationshipMap.get(parentCollection) || [];
+    relationshipsParent.push({
+        parentCollection,
+        childCollection,
+        parentKey,
+        childKey,
+        isArray: isArrayParent,
+        isChild: false,
+    });
+    relationshipsChild.push({
+        parentCollection,
+        childCollection,
+        parentKey,
+        childKey,
+        isArray: isArrayChild,
+        isChild: true,
+    });
+    relationshipMap.set(childCollection, relationshipsChild);
+    relationshipMap.set(parentCollection, relationshipsParent);
+}
+/**
+ * Extracts simple relationship information from collections for JSON schema generation
+ * This handles one-way and basic relationship tracking
+ *
+ * @param config - Appwrite configuration containing collections
+ * @returns Map of collection names to their simple relationships
+ */
+export function extractSimpleRelationships(config) {
+    const relationshipMap = new Map();
+    if (!config.collections) {
+        return relationshipMap;
+    }
+    config.collections.forEach((collection) => {
+        if (!collection.attributes) {
+            return;
+        }
+        collection.attributes.forEach((attr) => {
+            if (attr.type === "relationship" && attr.relatedCollection) {
+                const relationships = relationshipMap.get(collection.name) || [];
+                relationships.push({
+                    attributeKey: attr.key,
+                    relatedCollection: resolveCollectionName(config, attr.relatedCollection),
+                    relationType: attr.relationType || "oneToOne",
+                    isArray: isArrayRelationship(attr.relationType || "oneToOne")
+                });
+                relationshipMap.set(collection.name, relationships);
+            }
+        });
+    });
+    return relationshipMap;
+}
+/**
+ * Extracts all relationship attributes from a collection's attributes
+ * @param attributes - Array of collection attributes
+ * @returns Array of relationship attributes only
+ */
+export function filterRelationshipAttributes(attributes) {
+    return attributes.filter((attr) => attr.type === "relationship");
+}

package/dist/shared/selectionDialogs.d.ts

@@ -0,0 +1,220 @@
+import type { Models } from "node-appwrite";
+/**
+ * Interface for sync selection summary
+ */
+export interface SyncSelectionSummary {
+    databases: DatabaseSelection[];
+    buckets: BucketSelection[];
+    totalDatabases: number;
+    totalTables: number;
+    totalBuckets: number;
+    newItems: {
+        databases: number;
+        tables: number;
+        buckets: number;
+    };
+    existingItems: {
+        databases: number;
+        tables: number;
+        buckets: number;
+    };
+}
+/**
+ * Database selection with associated tables
+ */
+export interface DatabaseSelection {
+    databaseId: string;
+    databaseName: string;
+    tableIds: string[];
+    tableNames: string[];
+    isNew: boolean;
+}
+/**
+ * Bucket selection with associated database
+ */
+export interface BucketSelection {
+    bucketId: string;
+    bucketName: string;
+    databaseId?: string;
+    databaseName?: string;
+    isNew: boolean;
+}
+/**
+ * Options for database selection
+ */
+export interface DatabaseSelectionOptions {
+    showSelectAll?: boolean;
+    allowNewOnly?: boolean;
+    defaultSelected?: string[];
+}
+/**
+ * Options for table selection
+ */
+export interface TableSelectionOptions {
+    showSelectAll?: boolean;
+    allowNewOnly?: boolean;
+    defaultSelected?: string[];
+    showDatabaseContext?: boolean;
+}
+/**
+ * Options for bucket selection
+ */
+export interface BucketSelectionOptions {
+    showSelectAll?: boolean;
+    allowNewOnly?: boolean;
+    defaultSelected?: string[];
+    groupByDatabase?: boolean;
+}
+/**
+ * Response from existing config prompt
+ */
+export interface ExistingConfigResponse {
+    syncExisting: boolean;
+    modifyConfiguration: boolean;
+}
+/**
+ * Comprehensive selection dialog system for enhanced sync flow
+ *
+ * This class provides interactive dialogs for selecting databases, tables/collections,
+ * and storage buckets during sync operations. It supports both new and existing
+ * configurations with visual indicators and comprehensive confirmation flows.
+ *
+ * @example
+ * ```typescript
+ * import { SelectionDialogs } from './shared/selectionDialogs.js';
+ * import type { Models } from 'node-appwrite';
+ *
+ * // Example usage in a sync command
+ * const availableDatabases: Models.Database[] = await getAvailableDatabases();
+ * const configuredDatabases = config.databases || [];
+ *
+ * // Prompt about existing configuration
+ * const { syncExisting, modifyConfiguration } = await SelectionDialogs.promptForExistingConfig(configuredDatabases);
+ *
+ * if (modifyConfiguration) {
+ *   // Select databases
+ *   const selectedDatabaseIds = await SelectionDialogs.selectDatabases(
+ *     availableDatabases,
+ *     configuredDatabases,
+ *     { showSelectAll: true, allowNewOnly: !syncExisting }
+ *   );
+ *
+ *   // For each database, select tables
+ *   const tableSelectionsMap = new Map<string, string[]>();
+ *   const availableTablesMap = new Map<string, any[]>();
+ *
+ *   for (const databaseId of selectedDatabaseIds) {
+ *     const database = availableDatabases.find(db => db.$id === databaseId)!;
+ *     const availableTables = await getTablesForDatabase(databaseId);
+ *     const configuredTables = getConfiguredTablesForDatabase(databaseId);
+ *
+ *     availableTablesMap.set(databaseId, availableTables);
+ *
+ *     const selectedTableIds = await SelectionDialogs.selectTablesForDatabase(
+ *       databaseId,
+ *       database.name,
+ *       availableTables,
+ *       configuredTables,
+ *       { showSelectAll: true, allowNewOnly: !syncExisting }
+ *     );
+ *
+ *     tableSelectionsMap.set(databaseId, selectedTableIds);
+ *   }
+ *
+ *   // Select buckets
+ *   const availableBuckets = await getAvailableBuckets();
+ *   const configuredBuckets = config.buckets || [];
+ *   const selectedBucketIds = await SelectionDialogs.selectBucketsForDatabases(
+ *     selectedDatabaseIds,
+ *     availableBuckets,
+ *     configuredBuckets,
+ *     { showSelectAll: true, groupByDatabase: true }
+ *   );
+ *
+ *   // Create selection objects
+ *   const databaseSelections = SelectionDialogs.createDatabaseSelection(
+ *     selectedDatabaseIds,
+ *     availableDatabases,
+ *     tableSelectionsMap,
+ *     configuredDatabases,
+ *     availableTablesMap
+ *   );
+ *
+ *   const bucketSelections = SelectionDialogs.createBucketSelection(
+ *     selectedBucketIds,
+ *     availableBuckets,
+ *     configuredBuckets,
+ *     availableDatabases
+ *   );
+ *
+ *   // Show final confirmation
+ *   const selectionSummary = SelectionDialogs.createSyncSelectionSummary(
+ *     databaseSelections,
+ *     bucketSelections
+ *   );
+ *
+ *   const confirmed = await SelectionDialogs.confirmSyncSelection(selectionSummary);
+ *
+ *   if (confirmed) {
+ *     // Proceed with sync operation
+ *     await performSync(databaseSelections, bucketSelections);
+ *   }
+ * }
+ * ```
+ */
+export declare class SelectionDialogs {
+    /**
+     * Prompts user about existing configuration
+     */
+    static promptForExistingConfig(configuredItems: any[]): Promise<ExistingConfigResponse>;
+    /**
+     * Shows database selection dialog with indicators for configured vs new databases
+     */
+    static selectDatabases(availableDatabases: Models.Database[], configuredDatabases: any[], options?: DatabaseSelectionOptions): Promise<string[]>;
+    /**
+     * Shows table/collection selection dialog for a specific database
+     */
+    static selectTablesForDatabase(databaseId: string, databaseName: string, availableTables: any[], configuredTables: any[], options?: TableSelectionOptions): Promise<string[]>;
+    /**
+     * Shows bucket selection dialog for selected databases
+     */
+    static selectBucketsForDatabases(selectedDatabaseIds: string[], availableBuckets: any[], configuredBuckets: any[], options?: BucketSelectionOptions): Promise<string[]>;
+    /**
+     * Shows bucket selection for push operations with merged local+remote buckets.
+     * Unlike selectBucketsForDatabases, this shows all buckets as a flat list
+     * with source indicators (Local only, Remote only, Configured).
+     */
+    static selectBucketsForPush(mergedBuckets: any[], configuredBuckets: any[], options?: BucketSelectionOptions): Promise<string[]>;
+    /**
+     * Shows final confirmation dialog with sync selection summary
+     */
+    static confirmSyncSelection(selectionSummary: SyncSelectionSummary, operationType?: 'push' | 'pull' | 'sync'): Promise<boolean>;
+    /**
+     * Creates a sync selection summary from selected items
+     */
+    static createSyncSelectionSummary(databaseSelections: DatabaseSelection[], bucketSelections: BucketSelection[]): SyncSelectionSummary;
+    /**
+     * Helper method to create database selection objects
+     */
+    static createDatabaseSelection(selectedDatabaseIds: string[], availableDatabases: Models.Database[], tableSelectionsMap: Map<string, string[]>, configuredDatabases: any[], availableTablesMap?: Map<string, any[]>): DatabaseSelection[];
+    /**
+     * Helper method to create bucket selection objects
+     */
+    static createBucketSelection(selectedBucketIds: string[], availableBuckets: any[], configuredBuckets: any[], availableDatabases: Models.Database[]): BucketSelection[];
+    /**
+     * Shows a progress message during selection operations
+     */
+    static showProgress(message: string): void;
+    /**
+     * Shows an error message and handles graceful cancellation
+     */
+    static showError(message: string, error?: Error): void;
+    /**
+     * Shows a warning message
+     */
+    static showWarning(message: string): void;
+    /**
+     * Shows a success message
+     */
+    static showSuccess(message: string): void;
+}