appwrite-utils-cli 1.5.2 → 1.6.1

package/dist/shared/operationLogger.d.ts

@@ -1,3 +1,10 @@
 import type { Databases, Models } from "node-appwrite";
 import type { OperationCreate } from "../storage/schemas.js";
-export declare const logOperation: (db: Databases, dbId: string, operationDetails: OperationCreate, operationId?: string, useMigrations?: boolean) => Promise<Models.Document | null>;
+/**
+ * Legacy operation logger - deprecated
+ * This function is maintained for backward compatibility but no longer performs any logging.
+ * The operations table system has been refactored to use the dynamic adapter pattern.
+ *
+ * @deprecated This function will be removed in a future version
+ */
+export declare const logOperation: (db: Databases, dbId: string, operationDetails: OperationCreate, operationId?: string) => Promise<Models.Document | null>;

package/dist/shared/operationLogger.js

@@ -1,25 +1,12 @@
-import { tryAwaitWithRetry } from "appwrite-utils";
-import { ulid } from "ulidx";
-export const logOperation = async (db, dbId, operationDetails, operationId, useMigrations = true) => {
-    if (!useMigrations) {
-        console.log("Migrations disabled, skipping operation logging");
-        return null;
-    }
-    try {
-        let operation;
-        if (operationId) {
-            // Update existing operation log
-            operation = await tryAwaitWithRetry(async () => await db.updateDocument("migrations", "currentOperations", operationId, operationDetails));
-        }
-        else {
-            // Create new operation log
-            operation = await db.createDocument("migrations", "currentOperations", ulid(), operationDetails);
-        }
-        console.log(`Operation logged: ${operation.$id}`);
-        return operation;
-    }
-    catch (error) {
-        console.error(`Error logging operation: ${error}`);
-        throw error;
-    }
+/**
+ * Legacy operation logger - deprecated
+ * This function is maintained for backward compatibility but no longer performs any logging.
+ * The operations table system has been refactored to use the dynamic adapter pattern.
+ *
+ * @deprecated This function will be removed in a future version
+ */
+export const logOperation = async (db, dbId, operationDetails, operationId) => {
+    // No-op: Operations logging has been moved to the new operations table system
+    // Callers should migrate to using operationsTable.ts functions directly
+    return null;
 };

package/dist/shared/operationQueue.d.ts

@@ -1,5 +1,6 @@
 import { type Databases, type Models } from "node-appwrite";
 import type { Attribute } from "appwrite-utils";
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
 export interface QueuedOperation {
     type: "attribute";
     collectionId?: string;
@@ -9,5 +10,31 @@ export interface QueuedOperation {
 }
 export declare const queuedOperations: QueuedOperation[];
 export declare const nameToIdMapping: Map<string, string>;
+export declare const processedCollections: Set<string>;
+export declare const processedAttributes: Set<string>;
 export declare const enqueueOperation: (operation: QueuedOperation) => void;
-export declare const processQueue: (db: Databases, dbId: string) => Promise<void>;
+/**
+ * Clear all caches and processing state - use between operations
+ */
+export declare const clearProcessingState: () => void;
+/**
+ * Check if a collection has already been fully processed
+ */
+export declare const isCollectionProcessed: (collectionId: string) => boolean;
+/**
+ * Mark a collection as fully processed
+ */
+export declare const markCollectionProcessed: (collectionId: string, collectionName?: string) => void;
+/**
+ * Check if a specific attribute has been processed
+ */
+export declare const isAttributeProcessed: (collectionId: string, attributeKey: string) => boolean;
+/**
+ * Mark a specific attribute as processed
+ */
+export declare const markAttributeProcessed: (collectionId: string, attributeKey: string) => void;
+/**
+ * Process only specific attributes in the queue, not entire collections
+ * This prevents triggering full collection re-processing cycles
+ */
+export declare const processQueue: (db: Databases | DatabaseAdapter, dbId: string) => Promise<void>;

package/dist/shared/operationQueue.js

@@ -2,100 +2,302 @@ import { Query } from "node-appwrite";
 import { createOrUpdateAttributeWithStatusCheck } from "../collections/attributes.js";
 import { fetchAndCacheCollectionByName } from "../collections/methods.js";
 import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
-import chalk from "chalk";
+import { logger } from "../shared/logging.js";
+import { MessageFormatter } from "../shared/messageFormatter.js";
+// Global state management
 export const queuedOperations = [];
 export const nameToIdMapping = new Map();
+export const processedCollections = new Set();
+export const processedAttributes = new Set(); // format: "collectionId:attributeKey"
 export const enqueueOperation = (operation) => {
+    // Avoid duplicate queue entries for same attribute
+    const attributeKey = operation.attribute?.key;
+    const collectionId = operation.collectionId;
+    logger.info('Enqueueing operation', {
+        type: operation.type,
+        attributeKey,
+        collectionId,
+        dependencies: operation.dependencies,
+        queueSizeBefore: queuedOperations.length,
+        operation: 'enqueueOperation'
+    });
+    if (attributeKey && collectionId) {
+        const duplicateIndex = queuedOperations.findIndex((op) => op.collectionId === collectionId && op.attribute?.key === attributeKey);
+        if (duplicateIndex !== -1) {
+            MessageFormatter.info(`Replacing existing queue entry for attribute: ${attributeKey}`);
+            logger.info('Replacing duplicate queue entry', {
+                attributeKey,
+                collectionId,
+                duplicateIndex,
+                operation: 'enqueueOperation'
+            });
+            queuedOperations[duplicateIndex] = operation;
+            return;
+        }
+    }
     queuedOperations.push(operation);
+    logger.debug('Operation enqueued successfully', {
+        attributeKey,
+        collectionId,
+        queueSizeAfter: queuedOperations.length,
+        operation: 'enqueueOperation'
+    });
+};
+/**
+ * Clear all caches and processing state - use between operations
+ */
+export const clearProcessingState = () => {
+    const sizeBefore = {
+        collections: processedCollections.size,
+        attributes: processedAttributes.size,
+        nameMapping: nameToIdMapping.size
+    };
+    processedCollections.clear();
+    processedAttributes.clear();
+    nameToIdMapping.clear();
+    MessageFormatter.success("Cleared processing state caches");
+    logger.info('Processing state cleared', {
+        sizeBefore,
+        operation: 'clearProcessingState'
+    });
+};
+/**
+ * Check if a collection has already been fully processed
+ */
+export const isCollectionProcessed = (collectionId) => {
+    return processedCollections.has(collectionId);
+};
+/**
+ * Mark a collection as fully processed
+ */
+export const markCollectionProcessed = (collectionId, collectionName) => {
+    processedCollections.add(collectionId);
+    const logData = {
+        collectionId,
+        collectionName,
+        totalProcessedCollections: processedCollections.size,
+        operation: 'markCollectionProcessed'
+    };
+    if (collectionName) {
+        MessageFormatter.success(`Marked collection '${collectionName}' (${collectionId}) as processed`);
+    }
+    logger.info('Collection marked as processed', logData);
+};
+/**
+ * Check if a specific attribute has been processed
+ */
+export const isAttributeProcessed = (collectionId, attributeKey) => {
+    return processedAttributes.has(`${collectionId}:${attributeKey}`);
 };
+/**
+ * Mark a specific attribute as processed
+ */
+export const markAttributeProcessed = (collectionId, attributeKey) => {
+    const identifier = `${collectionId}:${attributeKey}`;
+    processedAttributes.add(identifier);
+    logger.debug('Attribute marked as processed', {
+        collectionId,
+        attributeKey,
+        identifier,
+        totalProcessedAttributes: processedAttributes.size,
+        operation: 'markAttributeProcessed'
+    });
+};
+/**
+ * Process only specific attributes in the queue, not entire collections
+ * This prevents triggering full collection re-processing cycles
+ */
 export const processQueue = async (db, dbId) => {
-    console.log("---------------------------------");
-    console.log(`Starting Queue processing of ${dbId}`);
-    console.log("---------------------------------");
+    const startTime = Date.now();
+    if (queuedOperations.length === 0) {
+        MessageFormatter.info("No queued operations to process");
+        logger.info('Queue processing skipped - no operations', {
+            dbId,
+            operation: 'processQueue'
+        });
+        return;
+    }
+    MessageFormatter.section(`Starting surgical queue processing of ${queuedOperations.length} operations for ${dbId}`);
+    logger.info('Starting queue processing', {
+        dbId,
+        queueSize: queuedOperations.length,
+        operations: queuedOperations.map(op => ({
+            type: op.type,
+            attributeKey: op.attribute?.key,
+            collectionId: op.collectionId,
+            dependencies: op.dependencies
+        })),
+        operation: 'processQueue'
+    });
     let progress = true;
-    while (progress) {
+    let attempts = 0;
+    const maxAttempts = 3; // Prevent infinite loops
+    while (progress && attempts < maxAttempts) {
         progress = false;
-        console.log("Processing queued operations:");
-        for (let i = 0; i < queuedOperations.length; i++) {
+        attempts++;
+        MessageFormatter.info(`Queue processing attempt ${attempts}/${maxAttempts}`);
+        logger.info('Queue processing attempt started', {
+            attempt: attempts,
+            maxAttempts,
+            remainingOperations: queuedOperations.length,
+            dbId,
+            operation: 'processQueue'
+        });
+        for (let i = queuedOperations.length - 1; i >= 0; i--) {
             const operation = queuedOperations[i];
-            let collectionFound;
-            // Handle relationship attribute operations
-            if (operation.attribute?.type === "relationship") {
-                // Attempt to resolve the collection directly if collectionId is specified
-                if (operation.collectionId) {
-                    console.log(`\tFetching collection by ID: ${operation.collectionId}`);
-                    try {
-                        collectionFound = await tryAwaitWithRetry(async () => await db.getCollection(dbId, operation.collectionId));
+            if (!operation.attribute || !operation.collectionId) {
+                MessageFormatter.warning("Invalid operation, removing from queue");
+                queuedOperations.splice(i, 1);
+                continue;
+            }
+            const attributeKey = operation.attribute.key;
+            const collectionId = operation.collectionId;
+            // Skip if this specific attribute was already processed
+            if (isAttributeProcessed(collectionId, attributeKey)) {
+                MessageFormatter.debug(`Attribute '${attributeKey}' already processed, removing from queue`);
+                logger.debug('Removing already processed attribute from queue', {
+                    attributeKey,
+                    collectionId,
+                    queueIndex: i,
+                    operation: 'processQueue'
+                });
+                queuedOperations.splice(i, 1);
+                continue;
+            }
+            let targetCollection;
+            // Resolve the target collection (where the attribute will be created)
+            try {
+                targetCollection = await tryAwaitWithRetry(async () => {
+                    if ('getMetadata' in db && typeof db.getMetadata === 'function') {
+                        // DatabaseAdapter
+                        return (await db.getTable({ databaseId: dbId, tableId: collectionId })).data;
                     }
-                    catch (e) {
-                        console.log(`\tCollection not found by ID: ${operation.collectionId}`);
+                    else {
+                        // Legacy Databases
+                        return await db.getCollection(dbId, collectionId);
                     }
-                }
-                // Attempt to resolve related collection if specified and not already found
-                if (!collectionFound && operation.attribute?.relatedCollection) {
-                    // First, try treating relatedCollection as an ID
+                });
+            }
+            catch (e) {
+                const errorMessage = e instanceof Error ? e.message : String(e);
+                MessageFormatter.error(`Target collection ${collectionId} not found, removing from queue`);
+                logger.error('Target collection not found during queue processing', {
+                    collectionId,
+                    attributeKey,
+                    error: errorMessage,
+                    operation: 'processQueue'
+                });
+                queuedOperations.splice(i, 1);
+                continue;
+            }
+            // For relationship attributes, ensure the related collection exists
+            let canProcess = true;
+            if (operation.attribute.type === "relationship") {
+                const relatedCollection = operation.attribute.relatedCollection;
+                if (relatedCollection) {
+                    // Try to resolve related collection by ID first, then by name
+                    let relatedFound = false;
                     try {
-                        const relAttr = operation.attribute;
-                        const byId = await tryAwaitWithRetry(async () => await db.getCollection(dbId, relAttr.relatedCollection));
-                        // We still need the target collection (operation.collectionId) to create the attribute on,
-                        // so only use this branch to warm caches/mappings and continue to dependency checks.
-                        // Do not override collectionFound with the related collection.
+                        await tryAwaitWithRetry(async () => {
+                            if ('getMetadata' in db && typeof db.getMetadata === 'function') {
+                                // DatabaseAdapter
+                                return (await db.getTable({ databaseId: dbId, tableId: relatedCollection })).data;
+                            }
+                            else {
+                                // Legacy Databases
+                                return await db.getCollection(dbId, relatedCollection);
+                            }
+                        });
+                        relatedFound = true;
+                        nameToIdMapping.set(relatedCollection, relatedCollection); // Cache the ID mapping
                     }
                     catch (_) {
-                        // Not an ID or not found; fall back to name-based cache
+                        // Try by name lookup
+                        const cachedId = nameToIdMapping.get(relatedCollection);
+                        if (cachedId) {
+                            try {
+                                await tryAwaitWithRetry(async () => {
+                                    if ('getMetadata' in db && typeof db.getMetadata === 'function') {
+                                        // DatabaseAdapter
+                                        return (await db.getTable({ databaseId: dbId, tableId: cachedId })).data;
+                                    }
+                                    else {
+                                        // Legacy Databases
+                                        return await db.getCollection(dbId, cachedId);
+                                    }
+                                });
+                                relatedFound = true;
+                            }
+                            catch (_) {
+                                nameToIdMapping.delete(relatedCollection); // Remove stale cache
+                            }
+                        }
+                        if (!relatedFound) {
+                            // Final attempt: search by name
+                            try {
+                                const collections = 'getMetadata' in db && typeof db.getMetadata === 'function'
+                                    ? await db.listTables({ databaseId: dbId, queries: [Query.equal("name", relatedCollection)] })
+                                    : await db.listCollections(dbId, [Query.equal("name", relatedCollection)]);
+                                if (collections.total && collections.total > 0) {
+                                    const firstCollection = 'getMetadata' in db && typeof db.getMetadata === 'function'
+                                        ? collections.tables?.[0]
+                                        : collections.collections?.[0];
+                                    nameToIdMapping.set(relatedCollection, firstCollection.$id);
+                                    relatedFound = true;
+                                }
+                            }
+                            catch (_) {
+                                // Related collection truly doesn't exist yet
+                            }
+                        }
                     }
-                    // Warm cache by name (used by attribute creation path), but do not use as target collection
-                    const relAttr = operation.attribute;
-                    await fetchAndCacheCollectionByName(db, dbId, relAttr.relatedCollection);
-                }
-                // Handle dependencies if collection still not found
-                if (!collectionFound) {
-                    for (const dep of operation.dependencies || []) {
-                        collectionFound = await fetchAndCacheCollectionByName(db, dbId, dep);
-                        if (collectionFound)
-                            break; // Break early if collection is found
+                    if (!relatedFound) {
+                        MessageFormatter.warning(`Related collection '${relatedCollection}' not ready for attribute '${attributeKey}', keeping in queue`);
+                        canProcess = false;
                     }
                 }
             }
-            else if (operation.collectionId) {
-                // Handle non-relationship operations with a specified collectionId
-                console.log(`\tFetching collection by ID: ${operation.collectionId}`);
-                try {
-                    collectionFound = await tryAwaitWithRetry(async () => await db.getCollection(dbId, operation.collectionId));
-                }
-                catch (e) {
-                    console.log(`\tCollection not found by ID: ${operation.collectionId}`);
-                }
-            }
-            // Process the operation if the collection is found
-            if (collectionFound && operation.attribute) {
-                console.log(chalk.cyan(`\t📋 Queue processing relationship attribute: ${operation.attribute.key} for collection: ${collectionFound.name}`));
-                const success = await createOrUpdateAttributeWithStatusCheck(db, dbId, collectionFound, operation.attribute);
+            if (canProcess && targetCollection) {
+                MessageFormatter.progress(`Processing queued ${operation.attribute.type} attribute: '${attributeKey}' for collection: '${targetCollection.name}'`);
+                const success = await createOrUpdateAttributeWithStatusCheck(db, dbId, targetCollection, operation.attribute);
                 if (success) {
-                    console.log(chalk.green(`\t✅ Successfully processed queued attribute: ${operation.attribute.key}`));
+                    MessageFormatter.success(`Successfully processed queued attribute: '${attributeKey}'`);
+                    logger.info('Queued attribute processed successfully', {
+                        attributeKey,
+                        collectionId,
+                        targetCollectionName: targetCollection.name,
+                        operation: 'processQueue'
+                    });
+                    markAttributeProcessed(collectionId, attributeKey);
                     queuedOperations.splice(i, 1);
-                    i--; // Adjust index since we're modifying the array
                     progress = true;
                 }
                 else {
-                    console.log(chalk.red(`\t❌ Failed to process queued attribute: ${operation.attribute.key}, removing from queue`));
+                    MessageFormatter.error(`Failed to process queued attribute: '${attributeKey}', removing from queue`);
+                    logger.error('Failed to process queued attribute', {
+                        attributeKey,
+                        collectionId,
+                        targetCollectionName: targetCollection.name,
+                        operation: 'processQueue'
+                    });
                     queuedOperations.splice(i, 1);
-                    i--; // Adjust index since we're modifying the array
                 }
             }
-            else {
-                console.log(chalk.yellow(`\t⚠️ Collection not found for queued operation, removing from queue: ${operation.attribute?.key || 'unknown'}`));
-                queuedOperations.splice(i, 1);
-                i--; // Adjust index since we're modifying the array
-            }
         }
-        console.log(`\tFinished processing queued operations`);
+        if (queuedOperations.length === 0) {
+            break;
+        }
+        MessageFormatter.info(`Remaining operations after attempt ${attempts}: ${queuedOperations.length}`);
     }
     if (queuedOperations.length > 0) {
-        console.error("Unresolved operations remain due to unmet dependencies.");
-        console.log(queuedOperations);
+        MessageFormatter.warning(`${queuedOperations.length} operations remain unresolved after ${maxAttempts} attempts:`);
+        queuedOperations.forEach((op, index) => {
+            MessageFormatter.warning(`  ${index + 1}. ${op.attribute?.type} attribute '${op.attribute?.key}' for collection ${op.collectionId}`);
+        });
+        MessageFormatter.warning("These may have unmet dependencies or require manual intervention");
+    }
+    else {
+        MessageFormatter.success("All queued operations processed successfully");
     }
-    console.log("---------------------------------");
-    console.log(`Queue processing complete for ${dbId}`);
-    console.log("---------------------------------");
+    MessageFormatter.section(`Surgical queue processing complete for ${dbId}`);
 };

package/dist/shared/operationsTable.d.ts

@@ -0,0 +1,26 @@
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+import { type OperationRecord } from "./operationsTableSchema.js";
+/**
+ * Creates the operations tracking table in the specified database
+ * Table is created with underscore prefix to indicate it's a system table
+ */
+export declare function createOperationsTable(db: DatabaseAdapter, databaseId: string): Promise<void>;
+/**
+ * Finds an existing operation or creates a new one
+ * Useful for resuming interrupted operations
+ */
+export declare function findOrCreateOperation(db: DatabaseAdapter, databaseId: string, operationType: string, params?: Partial<OperationRecord>): Promise<OperationRecord>;
+/**
+ * Updates an existing operation record
+ */
+export declare function updateOperation(db: DatabaseAdapter, databaseId: string, operationId: string, updates: Partial<OperationRecord>): Promise<OperationRecord>;
+/**
+ * Gets a single operation by ID
+ */
+export declare function getOperation(db: DatabaseAdapter, databaseId: string, operationId: string): Promise<OperationRecord | null>;
+/**
+ * Cleans up old completed operations
+ * @param olderThan - Optional date, defaults to operations older than 7 days
+ * @returns Number of operations deleted
+ */
+export declare function cleanupOperations(db: DatabaseAdapter, databaseId: string, olderThan?: Date): Promise<number>;