appwrite-utils-cli 1.5.1 → 1.6.0

package/dist/shared/operationsTable.js

@@ -0,0 +1,286 @@
+import { logger } from "./logging.js";
+import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
+import { Query, ID } from "node-appwrite";
+import { OPERATIONS_TABLE_ID, OPERATIONS_TABLE_NAME, 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, databaseId) {
+    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, databaseId) {
+    // 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, databaseId, operationType, params) {
+    // 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];
+        }
+    }
+    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",
+        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;
+}
+/**
+ * Updates an existing operation record
+ */
+export async function updateOperation(db, databaseId, operationId, updates) {
+    // Prepare update data (exclude system fields like $id, $createdAt, $updatedAt)
+    const updateData = {};
+    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;
+    }
+    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, databaseId, operationId) {
+    try {
+        const result = await db.getRow({
+            databaseId,
+            tableId: OPERATIONS_TABLE_ID,
+            id: operationId,
+        });
+        return result.data;
+    }
+    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, databaseId, olderThan) {
+    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/dist/shared/operationsTableSchema.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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;
+    targetCollection?: string;
+    status: OperationStatus;
+    progress: number;
+    total: number;
+    data?: any;
+    error?: string;
+}
+export type OperationStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+export declare const OPERATION_STATUSES: readonly ["pending", "in_progress", "completed", "failed", "cancelled"];
+export declare const OperationStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    in_progress: "in_progress";
+    completed: "completed";
+    cancelled: "cancelled";
+    failed: "failed";
+}>;
+export declare const OperationRecordSchema: z.ZodObject<{
+    $id: z.ZodString;
+    $createdAt: z.ZodString;
+    $updatedAt: z.ZodString;
+    operationType: z.ZodString;
+    targetCollection: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        in_progress: "in_progress";
+        completed: "completed";
+        cancelled: "cancelled";
+        failed: "failed";
+    }>;
+    progress: z.ZodNumber;
+    total: z.ZodNumber;
+    data: z.ZodOptional<z.ZodAny>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const OPERATIONS_TABLE_ID = "_appwrite_operations";
+export declare const OPERATIONS_TABLE_NAME = "Operations Tracking";

package/dist/shared/operationsTableSchema.js

@@ -0,0 +1,35 @@
+/**
+ * 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 const OPERATION_STATUSES = [
+    'pending',
+    'in_progress',
+    'completed',
+    'failed',
+    'cancelled'
+];
+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/dist/shared/relationshipExtractor.d.ts

@@ -0,0 +1,56 @@
+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 declare function resolveCollectionName(config: AppwriteConfig, idOrName: string): string;
+/**
+ * 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 declare function isArrayRelationship(relationType: string): boolean;
+/**
+ * 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 declare function extractTwoWayRelationships(config: AppwriteConfig): Map<string, RelationshipDetail[]>;
+/**
+ * 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 declare function extractSimpleRelationships(config: AppwriteConfig): Map<string, SimpleRelationship[]>;
+/**
+ * Extracts all relationship attributes from a collection's attributes
+ * @param attributes - Array of collection attributes
+ * @returns Array of relationship attributes only
+ */
+export declare function filterRelationshipAttributes(attributes: Attribute[]): RelationshipAttribute[];

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/schemaGenerator.d.ts

@@ -7,11 +7,29 @@ export declare class SchemaGenerator {
     private resolveCollectionName;
     updateYamlCollections(): void;
     updateTsSchemas(): void;
+    /**
+     * Determines the appropriate directory for collections/tables based on API mode
+     * Uses version detection or config hints to choose between 'collections' and 'tables'
+     */
+    private getVersionAwareCollectionsDirectory;
+    /**
+     * Get directory for a specific API mode (legacy or tablesdb)
+     * @param apiMode - The API mode to get directory for
+     * @returns The directory name for the specified API mode
+     */
+    getDirectoryForApiMode(apiMode: 'legacy' | 'tablesdb'): string;
+    /**
+     * Get both directory paths for dual API support
+     * @returns Object with both collectionsDirectory and tablesDirectory paths
+     */
+    getDualDirectoryConfiguration(): {
+        collectionsDirectory: string;
+        tablesDirectory: string;
+    };
     updateConfig(config: AppwriteConfig, isYamlConfig?: boolean): Promise<void>;
     private updateYamlConfig;
     private updateTypeScriptConfig;
     private extractRelationships;
-    private addRelationship;
     generateSchemas(options?: {
         format?: "zod" | "json" | "both";
         verbose?: boolean;