appwrite-utils-cli 1.5.2 → 1.6.0

package/src/shared/operationsTable.ts

@@ -0,0 +1,338 @@
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+import { logger } from "./logging.js";
+import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
+import { Query, ID } from "node-appwrite";
+import {
+	OPERATIONS_TABLE_ID,
+	OPERATIONS_TABLE_NAME,
+	type OperationRecord,
+	type OperationStatus,
+	OperationRecordSchema,
+} from "./operationsTableSchema.js";
+
+/**
+ * Operations Table Manager
+ *
+ * Manages dynamic operations tracking tables in each database.
+ * Creates _appwrite_operations table on-demand for tracking imports, exports, transfers, etc.
+ */
+
+/**
+ * Checks if operations table exists in database
+ */
+async function tableExists(
+	db: DatabaseAdapter,
+	databaseId: string,
+): Promise<boolean> {
+	try {
+		await db.getTable({ databaseId, tableId: OPERATIONS_TABLE_ID });
+		return true;
+	} catch (error) {
+		return false;
+	}
+}
+
+/**
+ * Creates the operations tracking table in the specified database
+ * Table is created with underscore prefix to indicate it's a system table
+ */
+export async function createOperationsTable(
+	db: DatabaseAdapter,
+	databaseId: string,
+): Promise<void> {
+	// Check if table already exists
+	const exists = await tableExists(db, databaseId);
+	if (exists) {
+		logger.debug("Operations table already exists", {
+			databaseId,
+			tableId: OPERATIONS_TABLE_ID,
+		});
+		return;
+	}
+
+	logger.info("Creating operations tracking table", {
+		databaseId,
+		tableId: OPERATIONS_TABLE_ID,
+	});
+
+	// Create table
+	await tryAwaitWithRetry(async () => {
+		await db.createTable({
+			databaseId,
+			id: OPERATIONS_TABLE_ID,
+			name: OPERATIONS_TABLE_NAME,
+		});
+	});
+
+	// Create attributes with retry logic
+	const attributes = [
+		{
+			key: "operationType",
+			type: "string",
+			size: 50,
+			required: true,
+		},
+		{
+			key: "targetCollection",
+			type: "string",
+			size: 50,
+			required: false,
+		},
+		{
+			key: "status",
+			type: "enum",
+			elements: ["pending", "in_progress", "completed", "failed", "cancelled"],
+			required: true,
+			default: "pending",
+		},
+		{
+			key: "progress",
+			type: "integer",
+			required: true,
+			default: 0,
+		},
+		{
+			key: "total",
+			type: "integer",
+			required: true,
+			default: 0,
+		},
+		{
+			key: "data",
+			type: "string",
+			size: 1048576, // 1MB for serialized data
+			required: false,
+		},
+		{
+			key: "error",
+			type: "string",
+			size: 10000,
+			required: false,
+		},
+	];
+
+	for (const attr of attributes) {
+		await tryAwaitWithRetry(async () => {
+			await db.createAttribute({
+				databaseId,
+				tableId: OPERATIONS_TABLE_ID,
+				...attr,
+			});
+		});
+	}
+
+	logger.info("Operations tracking table created successfully", {
+		databaseId,
+		tableId: OPERATIONS_TABLE_ID,
+		attributes: attributes.length,
+	});
+}
+
+/**
+ * Finds an existing operation or creates a new one
+ * Useful for resuming interrupted operations
+ */
+export async function findOrCreateOperation(
+	db: DatabaseAdapter,
+	databaseId: string,
+	operationType: string,
+	params?: Partial<OperationRecord>,
+): Promise<OperationRecord> {
+	// Ensure operations table exists
+	await createOperationsTable(db, databaseId);
+
+	// Try to find existing pending operation
+	try {
+		const queries = [
+			Query.equal("operationType", operationType),
+			Query.equal("status", "pending"),
+		];
+
+		if (params?.targetCollection) {
+			queries.push(Query.equal("targetCollection", params.targetCollection));
+		}
+
+		const response = await db.listRows({
+			databaseId,
+			tableId: OPERATIONS_TABLE_ID,
+			queries,
+		});
+
+		if (response.rows && response.rows.length > 0) {
+			logger.debug("Found existing operation", {
+				operationId: response.rows[0].$id,
+				operationType,
+			});
+			return response.rows[0] as OperationRecord;
+		}
+	} catch (error) {
+		logger.debug("No existing operation found, creating new one", {
+			operationType,
+			error: error instanceof Error ? error.message : String(error),
+		});
+	}
+
+	// Create new operation
+	const newOperation = {
+		operationType,
+		targetCollection: params?.targetCollection,
+		status: "pending" as OperationStatus,
+		progress: params?.progress ?? 0,
+		total: params?.total ?? 0,
+		data: params?.data ? JSON.stringify(params.data) : undefined,
+		error: params?.error,
+	};
+
+	const result = await db.createRow({
+		databaseId,
+		tableId: OPERATIONS_TABLE_ID,
+		id: ID.unique(),
+		data: newOperation,
+	});
+
+	logger.info("Created new operation", {
+		operationId: result.data?.$id,
+		operationType,
+	});
+
+	return result.data as OperationRecord;
+}
+
+/**
+ * Updates an existing operation record
+ */
+export async function updateOperation(
+	db: DatabaseAdapter,
+	databaseId: string,
+	operationId: string,
+	updates: Partial<OperationRecord>,
+): Promise<OperationRecord> {
+	// Prepare update data (exclude system fields like $id, $createdAt, $updatedAt)
+	const updateData: Record<string, any> = {};
+
+	if (updates.operationType !== undefined)
+		updateData.operationType = updates.operationType;
+	if (updates.targetCollection !== undefined)
+		updateData.targetCollection = updates.targetCollection;
+	if (updates.status !== undefined) updateData.status = updates.status;
+	if (updates.progress !== undefined) updateData.progress = updates.progress;
+	if (updates.total !== undefined) updateData.total = updates.total;
+	if (updates.error !== undefined) updateData.error = updates.error;
+	if (updates.data !== undefined) {
+		updateData.data =
+			typeof updates.data === "string"
+				? updates.data
+				: JSON.stringify(updates.data);
+	}
+
+	try {
+		const result = await db.updateRow({
+			databaseId,
+			tableId: OPERATIONS_TABLE_ID,
+			id: operationId,
+			data: updateData,
+		});
+
+		logger.debug("Updated operation", {
+			operationId,
+			updates: Object.keys(updateData),
+		});
+
+		return result.data as OperationRecord;
+	} catch (error) {
+		logger.error("Failed to update operation", {
+			operationId,
+			error: error instanceof Error ? error.message : String(error),
+		});
+		throw error;
+	}
+}
+
+/**
+ * Gets a single operation by ID
+ */
+export async function getOperation(
+	db: DatabaseAdapter,
+	databaseId: string,
+	operationId: string,
+): Promise<OperationRecord | null> {
+	try {
+		const result = await db.getRow({
+			databaseId,
+			tableId: OPERATIONS_TABLE_ID,
+			id: operationId,
+		});
+
+		return result.data as OperationRecord;
+	} catch (error) {
+		logger.debug("Operation not found", {
+			operationId,
+			error: error instanceof Error ? error.message : String(error),
+		});
+		return null;
+	}
+}
+
+/**
+ * Cleans up old completed operations
+ * @param olderThan - Optional date, defaults to operations older than 7 days
+ * @returns Number of operations deleted
+ */
+export async function cleanupOperations(
+	db: DatabaseAdapter,
+	databaseId: string,
+	olderThan?: Date,
+): Promise<number> {
+	const cutoffDate =
+		olderThan || new Date(Date.now() - 7 * 24 * 60 * 60 * 1000); // 7 days ago
+	const cutoffIso = cutoffDate.toISOString();
+
+	try {
+		// Query for completed operations older than cutoff
+		const response = await db.listRows({
+			databaseId,
+			tableId: OPERATIONS_TABLE_ID,
+			queries: [
+				Query.equal("status", ["completed", "failed", "cancelled"]),
+				Query.lessThan("$createdAt", cutoffIso),
+			],
+		});
+
+		if (!response.rows || response.rows.length === 0) {
+			logger.debug("No old operations to clean up", { databaseId });
+			return 0;
+		}
+
+		// Delete in batches
+		let deletedCount = 0;
+		for (const operation of response.rows) {
+			try {
+				await db.deleteRow({
+					databaseId,
+					tableId: OPERATIONS_TABLE_ID,
+					id: operation.$id,
+				});
+				deletedCount++;
+			} catch (error) {
+				logger.warn("Failed to delete operation", {
+					operationId: operation.$id,
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+
+		logger.info("Cleaned up old operations", {
+			databaseId,
+			deletedCount,
+			cutoffDate: cutoffIso,
+		});
+
+		return deletedCount;
+	} catch (error) {
+		logger.error("Failed to cleanup operations", {
+			databaseId,
+			error: error instanceof Error ? error.message : String(error),
+		});
+		return 0;
+	}
+}

package/src/shared/operationsTableSchema.ts

@@ -0,0 +1,60 @@
+/**
+ * Schema for operation tracking table (_appwrite_operations)
+ *
+ * This table is created dynamically in each database to track long-running operations
+ * like imports, exports, transfers, and backups.
+ */
+
+import { z } from "zod";
+
+export interface OperationRecord {
+  $id: string;
+  $createdAt: string;
+  $updatedAt: string;
+  operationType: string;        // 'import', 'export', 'transfer', 'backup', etc.
+  targetCollection?: string;    // Optional: which collection is being operated on
+  status: OperationStatus;
+  progress: number;             // Current progress count
+  total: number;                // Total items to process
+  data?: any;                   // Optional: serialized operation data
+  error?: string;               // Optional: error message if failed
+}
+
+export type OperationStatus =
+  | 'pending'
+  | 'in_progress'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+export const OPERATION_STATUSES = [
+  'pending',
+  'in_progress',
+  'completed',
+  'failed',
+  'cancelled'
+] as const;
+
+export const OperationStatusSchema = z.enum([
+  'pending',
+  'in_progress',
+  'completed',
+  'failed',
+  'cancelled'
+]);
+
+export const OperationRecordSchema = z.object({
+  $id: z.string(),
+  $createdAt: z.string(),
+  $updatedAt: z.string(),
+  operationType: z.string(),
+  targetCollection: z.string().optional(),
+  status: OperationStatusSchema,
+  progress: z.number(),
+  total: z.number(),
+  data: z.any().optional(),
+  error: z.string().optional()
+});
+
+export const OPERATIONS_TABLE_ID = "_appwrite_operations";
+export const OPERATIONS_TABLE_NAME = "Operations Tracking";

package/src/shared/relationshipExtractor.ts

@@ -0,0 +1,214 @@
+import type { AppwriteConfig, Attribute, RelationshipAttribute } from "appwrite-utils";
+
+/**
+ * Represents detailed information about a two-way relationship between collections
+ */
+export interface RelationshipDetail {
+  parentCollection: string;
+  childCollection: string;
+  parentKey: string;
+  childKey: string;
+  isArray: boolean;
+  isChild: boolean;
+}
+
+/**
+ * Represents basic relationship information for JSON schema generation
+ */
+export interface SimpleRelationship {
+  attributeKey: string;
+  relatedCollection: string;
+  relationType: string;
+  isArray: boolean;
+}
+
+/**
+ * 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: AppwriteConfig, idOrName: string): string {
+  const col = config.collections?.find(
+    (c) => c.$id === (idOrName as any) || 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: string): boolean {
+  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: AppwriteConfig
+): Map<string, RelationshipDetail[]> {
+  const relationshipMap = new Map<string, RelationshipDetail[]>();
+
+  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 as RelationshipAttribute;
+
+        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: Map<string, RelationshipDetail[]>,
+  parentCollection: string,
+  childCollection: string,
+  parentKey: string,
+  childKey: string,
+  isArrayParent: boolean,
+  isArrayChild: boolean
+): void {
+  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: AppwriteConfig
+): Map<string, SimpleRelationship[]> {
+  const relationshipMap = new Map<string, SimpleRelationship[]>();
+
+  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: Attribute[]): RelationshipAttribute[] {
+  return attributes.filter(
+    (attr): attr is RelationshipAttribute => attr.type === "relationship"
+  );
+}