appwrite-utils-cli 1.5.1 → 1.6.0

package/src/shared/schemaGenerator.ts

@@ -4,6 +4,7 @@ import type {
   Attribute,
   RelationshipAttribute,
 } from "appwrite-utils";
+import { getVersionAwareDirectory, resolveDirectoryForApiMode, getDualDirectoryPaths } from "appwrite-utils";
 import { z } from "zod";
 import fs from "fs";
 import path from "path";
@@ -12,54 +13,60 @@ import { getDatabaseFromConfig } from "../migrations/afterImportActions.js";
 import { ulid } from "ulidx";
 import { JsonSchemaGenerator } from "./jsonSchemaGenerator.js";
 import { collectionToYaml, getCollectionYamlFilename } from "../utils/yamlConverter.js";
+import {
+  extractTwoWayRelationships,
+  resolveCollectionName,
+  type RelationshipDetail
+} from "./relationshipExtractor.js";
+import { resolveSchemaDir } from "../utils/pathResolvers.js";
+import { MessageFormatter } from "./messageFormatter.js";
 
-interface RelationshipDetail {
-  parentCollection: string;
-  childCollection: string;
-  parentKey: string;
-  childKey: string;
-  isArray: boolean;
-  isChild: boolean;
-}
+export class SchemaGenerator {
+  private relationshipMap = new Map<string, RelationshipDetail[]>();
+  private config: AppwriteConfig;
+  private appwriteFolderPath: string;
+
+  constructor(config: AppwriteConfig, appwriteFolderPath: string) {
+    this.config = config;
+    this.appwriteFolderPath = appwriteFolderPath;
+    this.extractRelationships();
+  }
 
-export class SchemaGenerator {
-  private relationshipMap = new Map<string, RelationshipDetail[]>();
-  private config: AppwriteConfig;
-  private appwriteFolderPath: string;
-
-  constructor(config: AppwriteConfig, appwriteFolderPath: string) {
-    this.config = config;
-    this.appwriteFolderPath = appwriteFolderPath;
-    this.extractRelationships();
-  }
-
-  private resolveCollectionName = (idOrName: string): string => {
-    const col = this.config.collections?.find(
-      (c) => c.$id === (idOrName as any) || c.name === idOrName
-    );
-    return col?.name ?? idOrName;
-  };
+  private resolveCollectionName = (idOrName: string): string => {
+    return resolveCollectionName(this.config, idOrName);
+  };
 
   public updateYamlCollections(): void {
     const collections = this.config.collections;
     delete this.config.collections;
 
-    const collectionsDir = path.join(this.appwriteFolderPath, "collections");
+    // Determine output directory based on API mode/version detection
+    const outputDir = this.getVersionAwareCollectionsDirectory();
+    const collectionsDir = path.join(this.appwriteFolderPath, outputDir);
     if (!fs.existsSync(collectionsDir)) {
       fs.mkdirSync(collectionsDir, { recursive: true });
     }
 
     collections?.forEach((collection) => {
-      // Determine schema path based on config
+      // Determine schema path based on config and output directory
       const schemaDir = this.config.schemaConfig?.yamlSchemaDirectory || ".yaml_schemas";
-      const schemaPath = `../${schemaDir}/collection.schema.json`;
-      
-      const yamlContent = collectionToYaml(collection, schemaPath);
+      const isTablesMode = outputDir === "tables";
+      const schemaPath = isTablesMode
+        ? `../${schemaDir}/table.schema.json`
+        : `../${schemaDir}/collection.schema.json`;
+
+      const yamlConfig = {
+        useTableTerminology: isTablesMode,
+        entityType: isTablesMode ? 'table' as const : 'collection' as const,
+        schemaPath
+      };
+
+      const yamlContent = collectionToYaml(collection, yamlConfig);
       const filename = getCollectionYamlFilename(collection);
       const filePath = path.join(collectionsDir, filename);
-      
+
       fs.writeFileSync(filePath, yamlContent, { encoding: "utf-8" });
-      console.log(`Collection YAML written to ${filePath}`);
+      MessageFormatter.success(`${outputDir === "tables" ? "Table" : "Collection"} YAML written to ${filePath}`, { prefix: "Schema" });
     });
   }
 
@@ -120,9 +127,11 @@ export class SchemaGenerator {
   `;
     fs.writeFileSync(configPath, configContent, { encoding: "utf-8" });
 
+    // Determine output directory based on API mode/version detection
+    const outputDir = this.getVersionAwareCollectionsDirectory();
     const collectionsFolderPath = path.join(
       this.appwriteFolderPath,
-      "collections"
+      outputDir
     );
     if (!fs.existsSync(collectionsFolderPath)) {
       fs.mkdirSync(collectionsFolderPath, { recursive: true });
@@ -200,10 +209,35 @@ export class SchemaGenerator {
       fs.writeFileSync(collectionFilePath, collectionContent, {
         encoding: "utf-8",
       });
-      console.log(`Collection schema written to ${collectionFilePath}`);
+      MessageFormatter.success(`${outputDir === "tables" ? "Table" : "Collection"} schema written to ${collectionFilePath}`, { prefix: "Schema" });
     });
   }
 
+  /**
+   * 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(): string {
+    return getVersionAwareDirectory(this.config, this.appwriteFolderPath);
+  }
+
+  /**
+   * 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
+   */
+  public getDirectoryForApiMode(apiMode: 'legacy' | 'tablesdb'): string {
+    return resolveDirectoryForApiMode(this.config, apiMode, this.appwriteFolderPath);
+  }
+
+  /**
+   * Get both directory paths for dual API support
+   * @returns Object with both collectionsDirectory and tablesDirectory paths
+   */
+  public getDualDirectoryConfiguration(): { collectionsDirectory: string; tablesDirectory: string } {
+    return getDualDirectoryPaths(this.config);
+  }
+
   public async updateConfig(config: AppwriteConfig, isYamlConfig: boolean = false): Promise<void> {
     if (isYamlConfig) {
       // User has YAML config - find the config file and update it + generate individual collection files
@@ -213,7 +247,7 @@ export class SchemaGenerator {
       if (yamlConfigPath) {
         await this.updateYamlConfig(config, yamlConfigPath);
       } else {
-        console.warn("⚠️ YAML config expected but not found, falling back to TypeScript");
+        MessageFormatter.warning("YAML config expected but not found, falling back to TypeScript", { prefix: "Schema" });
         this.updateTypeScriptConfig(config);
       }
     } else {
@@ -231,10 +265,10 @@ export class SchemaGenerator {
       
       // Generate individual collection YAML files
       this.updateYamlCollections();
-      
-      console.log("✅ Updated YAML configuration and collection files");
+
+      MessageFormatter.success("Updated YAML configuration and collection files", { prefix: "Schema" });
     } catch (error) {
-      console.error("❌ Error updating YAML config:", error instanceof Error ? error.message : error);
+      MessageFormatter.error("Error updating YAML config", error as Error, { prefix: "Schema" });
       throw error;
     }
   }
@@ -287,87 +321,11 @@ const appwriteConfig: AppwriteConfig = {
 export default appwriteConfig;
 `;
     fs.writeFileSync(configPath, configContent, { encoding: "utf-8" });
-    console.log("✅ Updated TypeScript configuration file");
+    MessageFormatter.success("Updated TypeScript configuration file", { prefix: "Schema" });
   }
 
   private extractRelationships(): void {
-    if (!this.config.collections) {
-      return;
-    }
-    this.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;
-          }
-          this.addRelationship(
-            collection.name,
-            this.resolveCollectionName(relationshipAttr.relatedCollection),
-            attr.key,
-            relationshipAttr.twoWayKey!,
-            isArrayParent,
-            isArrayChild
-          );
-          console.log(
-            `Extracted relationship: ${attr.key}\n\t${collection.name} -> ${relationshipAttr.relatedCollection}, databaseId: ${collection.databaseId}`
-          );
-        }
-      });
-    });
-  }
-
-  private addRelationship(
-    parentCollection: string,
-    childCollection: string,
-    parentKey: string,
-    childKey: string,
-    isArrayParent: boolean,
-    isArrayChild: boolean
-  ): void {
-    const relationshipsChild = this.relationshipMap.get(childCollection) || [];
-    const relationshipsParent =
-      this.relationshipMap.get(parentCollection) || [];
-    relationshipsParent.push({
-      parentCollection,
-      childCollection,
-      parentKey,
-      childKey,
-      isArray: isArrayParent,
-      isChild: false,
-    });
-    relationshipsChild.push({
-      parentCollection,
-      childCollection,
-      parentKey,
-      childKey,
-      isArray: isArrayChild,
-      isChild: true,
-    });
-    this.relationshipMap.set(childCollection, relationshipsChild);
-    this.relationshipMap.set(parentCollection, relationshipsParent);
+    this.relationshipMap = extractTwoWayRelationships(this.config);
   }
 
   public generateSchemas(options: {
@@ -382,7 +340,9 @@ export default appwriteConfig;
     
     // Create schemas directory using config setting
     const outputDir = this.config.schemaConfig?.outputDirectory || "schemas";
-    const schemasPath = path.join(this.appwriteFolderPath, outputDir);
+    const schemasPath = outputDir === "schemas"
+      ? resolveSchemaDir(this.appwriteFolderPath)
+      : path.join(this.appwriteFolderPath, outputDir);
     if (!fs.existsSync(schemasPath)) {
       fs.mkdirSync(schemasPath, { recursive: true });
     }
@@ -390,19 +350,19 @@ export default appwriteConfig;
     // Generate Zod schemas (TypeScript)
     if (format === "zod" || format === "both") {
       this.config.collections.forEach((collection) => {
-        const schemaString = this.createSchemaStringV4(
-          collection.name,
-          collection.attributes || []
-        );
+        const schemaString = this.createSchemaStringV4(
+          collection.name,
+          collection.attributes || []
+        );
         const camelCaseName = toCamelCase(collection.name);
         const schemaPath = path.join(schemasPath, `${camelCaseName}.ts`);
         fs.writeFileSync(schemaPath, schemaString, { encoding: "utf-8" });
         if (verbose) {
-          console.log(`Zod schema written to ${schemaPath}`);
+          MessageFormatter.success(`Zod schema written to ${schemaPath}`, { prefix: "Schema" });
         }
       });
     }
-    
+
     // Generate JSON schemas (all at once)
     if (format === "json" || format === "both") {
       const jsonSchemaGenerator = new JsonSchemaGenerator(this.config, this.appwriteFolderPath);
@@ -412,110 +372,110 @@ export default appwriteConfig;
         verbose: verbose
       });
     }
-    
+
     if (verbose) {
-      console.log(`✓ Schema generation completed (format: ${format})`);
+      MessageFormatter.success(`Schema generation completed (format: ${format})`, { prefix: "Schema" });
     }
-  }
-
-  // Zod v4 recursive getter-based schemas
-  createSchemaStringV4 = (name: string, attributes: Attribute[]): string => {
-    const pascalName = toPascalCase(name);
-    let imports = `import { z } from "zod";\n`;
-
-    // Use the relationshipMap to find related collections
-    const relationshipDetails = this.relationshipMap.get(name) || [];
-    let relatedCollections = relationshipDetails
-      .filter((detail, index, self) => {
-        const uniqueKey = `${detail.parentCollection}-${detail.childCollection}-${detail.parentKey}-${detail.childKey}`;
-        return (
-          index ===
-          self.findIndex(
+  }
+
+  // Zod v4 recursive getter-based schemas
+  createSchemaStringV4 = (name: string, attributes: Attribute[]): string => {
+    const pascalName = toPascalCase(name);
+    let imports = `import { z } from "zod";\n`;
+
+    // Use the relationshipMap to find related collections
+    const relationshipDetails = this.relationshipMap.get(name) || [];
+    let relatedCollections = relationshipDetails
+      .filter((detail, index, self) => {
+        const uniqueKey = `${detail.parentCollection}-${detail.childCollection}-${detail.parentKey}-${detail.childKey}`;
+        return (
+          index ===
+          self.findIndex(
             (obj) =>
               `${obj.parentCollection}-${obj.childCollection}-${obj.parentKey}-${obj.childKey}` ===
               uniqueKey
           )
         );
       })
-      .map((detail) => {
-        const relatedCollectionName = detail.isChild
-          ? detail.parentCollection
-          : detail.childCollection;
-        const key = detail.isChild ? detail.childKey : detail.parentKey;
-        const isArray = detail.isArray ? "array" : "";
-        return [relatedCollectionName, key, isArray];
-      });
-
-    // Include one-way relationship attributes directly (no twoWayKey)
-    const oneWayRels: Array<[string, string, string]> = [];
-    for (const attr of attributes) {
-      if (attr.type === "relationship" && attr.relatedCollection) {
-        const relatedName = this.resolveCollectionName(attr.relatedCollection);
-        const isArray =
-          attr.relationType === "oneToMany" || attr.relationType === "manyToMany"
-            ? "array"
-            : "";
-        oneWayRels.push([relatedName, attr.key, isArray]);
-      }
-    }
-
-    // Merge and dedupe (by relatedName+key)
-    relatedCollections = [...relatedCollections, ...oneWayRels].filter(
-      (item, idx, self) =>
-        idx === self.findIndex((o) => `${o[0]}::${o[1]}` === `${item[0]}::${item[1]}`)
-    );
-
-    const hasRelationships = relatedCollections.length > 0;
-
-    // Build imports for related collections
-    if (hasRelationships) {
-      const importLines = relatedCollections.map((rel) => {
-        const relatedPascalName = toPascalCase(rel[0]);
-        const relatedCamelName = toCamelCase(rel[0]);
-        return `import { ${relatedPascalName}Schema } from "./${relatedCamelName}";`;
-      });
-      const unique = Array.from(new Set(importLines));
-      imports += unique.join("\n") + (unique.length ? "\n" : "");
-    }
-
-    let schemaString = `${imports}\n`;
-
-    // Single object schema with recursive getters (Zod v4)
-    schemaString += `export const ${pascalName}Schema = z.object({\n`;
-    schemaString += `  $id: z.string(),\n`;
-    schemaString += `  $createdAt: z.string(),\n`;
-    schemaString += `  $updatedAt: z.string(),\n`;
-    schemaString += `  $permissions: z.array(z.string()),\n`;
-    for (const attribute of attributes) {
-      if (attribute.type === "relationship") continue;
-      schemaString += `  ${attribute.key}: ${this.typeToZod(attribute)},\n`;
-    }
-
-    // Add recursive getters for relationships (respect required flag)
-    relatedCollections.forEach((rel) => {
-      const relatedPascalName = toPascalCase(rel[0]);
-      const isArray = rel[2] === "array";
-      const key = String(rel[1]);
-      const attrMeta = attributes.find(a => a.key === key && a.type === "relationship");
-      const isRequired = !!attrMeta?.required;
-      let getterBody = "";
-      if (isArray) {
-        getterBody = isRequired
-          ? `${relatedPascalName}Schema.array()`
-          : `${relatedPascalName}Schema.array().nullish()`;
-      } else {
-        getterBody = isRequired
-          ? `${relatedPascalName}Schema`
-          : `${relatedPascalName}Schema.nullish()`;
-      }
-      schemaString += `  get ${key}(){\n    return ${getterBody}\n  },\n`;
-    });
-
-    schemaString += `});\n\n`;
-    schemaString += `export type ${pascalName} = z.infer<typeof ${pascalName}Schema>;\n\n`;
-
-    return schemaString;
-  };
+      .map((detail) => {
+        const relatedCollectionName = detail.isChild
+          ? detail.parentCollection
+          : detail.childCollection;
+        const key = detail.isChild ? detail.childKey : detail.parentKey;
+        const isArray = detail.isArray ? "array" : "";
+        return [relatedCollectionName, key, isArray];
+      });
+
+    // Include one-way relationship attributes directly (no twoWayKey)
+    const oneWayRels: Array<[string, string, string]> = [];
+    for (const attr of attributes) {
+      if (attr.type === "relationship" && attr.relatedCollection) {
+        const relatedName = this.resolveCollectionName(attr.relatedCollection);
+        const isArray =
+          attr.relationType === "oneToMany" || attr.relationType === "manyToMany"
+            ? "array"
+            : "";
+        oneWayRels.push([relatedName, attr.key, isArray]);
+      }
+    }
+
+    // Merge and dedupe (by relatedName+key)
+    relatedCollections = [...relatedCollections, ...oneWayRels].filter(
+      (item, idx, self) =>
+        idx === self.findIndex((o) => `${o[0]}::${o[1]}` === `${item[0]}::${item[1]}`)
+    );
+
+    const hasRelationships = relatedCollections.length > 0;
+
+    // Build imports for related collections
+    if (hasRelationships) {
+      const importLines = relatedCollections.map((rel) => {
+        const relatedPascalName = toPascalCase(rel[0]);
+        const relatedCamelName = toCamelCase(rel[0]);
+        return `import { ${relatedPascalName}Schema } from "./${relatedCamelName}";`;
+      });
+      const unique = Array.from(new Set(importLines));
+      imports += unique.join("\n") + (unique.length ? "\n" : "");
+    }
+
+    let schemaString = `${imports}\n`;
+
+    // Single object schema with recursive getters (Zod v4)
+    schemaString += `export const ${pascalName}Schema = z.object({\n`;
+    schemaString += `  $id: z.string(),\n`;
+    schemaString += `  $createdAt: z.string(),\n`;
+    schemaString += `  $updatedAt: z.string(),\n`;
+    schemaString += `  $permissions: z.array(z.string()),\n`;
+    for (const attribute of attributes) {
+      if (attribute.type === "relationship") continue;
+      schemaString += `  ${attribute.key}: ${this.typeToZod(attribute)},\n`;
+    }
+
+    // Add recursive getters for relationships (respect required flag)
+    relatedCollections.forEach((rel) => {
+      const relatedPascalName = toPascalCase(rel[0]);
+      const isArray = rel[2] === "array";
+      const key = String(rel[1]);
+      const attrMeta = attributes.find(a => a.key === key && a.type === "relationship");
+      const isRequired = !!attrMeta?.required;
+      let getterBody = "";
+      if (isArray) {
+        getterBody = isRequired
+          ? `${relatedPascalName}Schema.array()`
+          : `${relatedPascalName}Schema.array().nullish()`;
+      } else {
+        getterBody = isRequired
+          ? `${relatedPascalName}Schema`
+          : `${relatedPascalName}Schema.nullish()`;
+      }
+      schemaString += `  get ${key}(){\n    return ${getterBody}\n  },\n`;
+    });
+
+    schemaString += `});\n\n`;
+    schemaString += `export type ${pascalName} = z.infer<typeof ${pascalName}Schema>;\n\n`;
+
+    return schemaString;
+  };
 
   typeToZod = (attribute: Attribute) => {
     let baseSchemaCode = "";

package/src/storage/backupCompression.ts

@@ -0,0 +1,88 @@
+import JSZip from "jszip";
+import type { BackupCreate } from "./schemas.js";
+
+export interface BackupCompressionOptions {
+  includeFiles?: boolean;
+  compressionLevel?: number; // 0-9, default 6
+}
+
+/**
+ * Creates a compressed ZIP backup from backup data
+ *
+ * Structure:
+ * - metadata.json (backup metadata)
+ * - database.json (database config)
+ * - collections/*.json (one file per collection)
+ * - documents/*.json (one file per collection's documents)
+ * - files/ (optional, if includeFiles is true)
+ */
+export async function createBackupZip(
+  backupData: BackupCreate,
+  options: BackupCompressionOptions = {}
+): Promise<Buffer> {
+  const zip = new JSZip();
+  const compressionLevel = options.compressionLevel ?? 6;
+
+  // Add metadata.json
+  const metadata = {
+    version: "1.0",
+    createdAt: new Date().toISOString(),
+    databaseId: JSON.parse(backupData.database).$id,
+    format: "zip",
+    includesFiles: options.includeFiles ?? false
+  };
+  zip.file("metadata.json", JSON.stringify(metadata, null, 2));
+
+  // Add database.json
+  zip.file("database.json", backupData.database);
+
+  // Add collections/*.json
+  const collectionsFolder = zip.folder("collections");
+  if (collectionsFolder) {
+    backupData.collections.forEach((collectionStr, index) => {
+      const collection = JSON.parse(collectionStr);
+      collectionsFolder.file(`${collection.$id || `collection_${index}`}.json`, collectionStr);
+    });
+  }
+
+  // Add documents/*.json
+  const documentsFolder = zip.folder("documents");
+  if (documentsFolder) {
+    backupData.documents.forEach((docBatch) => {
+      const collectionId = docBatch.collectionId;
+      documentsFolder.file(`${collectionId}.json`, docBatch.data);
+    });
+  }
+
+  // TODO: Add files support in future task (C3.5)
+  if (options.includeFiles) {
+    // Placeholder for file backup support
+    const filesFolder = zip.folder("files");
+    if (filesFolder) {
+      filesFolder.file("file-manifest.json", JSON.stringify({
+        note: "File backup not yet implemented"
+      }, null, 2));
+    }
+  }
+
+  // Generate ZIP buffer
+  const buffer = await zip.generateAsync({
+    type: "nodebuffer",
+    compression: "DEFLATE",
+    compressionOptions: { level: compressionLevel }
+  });
+
+  return buffer;
+}
+
+/**
+ * Estimates compression ratio for backup data
+ */
+export function estimateCompressedSize(
+  uncompressedSize: number,
+  format: string = "json"
+): number {
+  // JSON typically compresses to 20-30% of original size with gzip
+  const compressionRatio = format === "json" ? 0.25 : 0.5;
+  return Math.ceil(uncompressedSize * compressionRatio);
+}