appwrite-utils-cli 1.4.0 → 1.5.0

package/README.md

@@ -325,7 +325,28 @@ Available specifications:
 
 This updated CLI ensures that developers have robust tools at their fingertips to manage complex Appwrite projects effectively from the command line, with both interactive and non-interactive modes available for flexibility.
 
-## Changelog
+## Changelog
+
+### 1.5.0 - Recursive Zod v4 Schemas + One‑Way Relationship Support
+
+Highlights
+- Recursive getters: Generated schemas now use Zod v4 recursive getters (no `z.lazy`, no `BaseSchema` layering). Cleaner types and fully inferred mutual recursion.
+- One‑way relationships: Relationship attributes are now included even when `twoWay: false`. Related imports resolve collection IDs to names.
+- Required semantics: Relationship getters respect `required` and `array`:
+  - required scalar → `RelatedSchema`
+  - optional scalar → `RelatedSchema.nullish()`
+  - required array → `RelatedSchema.array()`
+  - optional array → `RelatedSchema.array().nullish()`
+- JSON Schemas: `$ref` definitions use resolved collection names when YAML provides IDs.
+
+Validation changes
+- Relationship schema: `twoWayKey` and `side` are now required only when `twoWay` is `true`.
+- Helpful errors: Keeps strong validation but removes false negatives for one‑way relationships.
+
+Developer notes
+- Imports: Schema generators import only `...Schema` from related collections (no type imports needed).
+- Example YAML: `Posts.yaml` demonstrates a required `manyToMany` (`categories`) and a one‑way `manyToOne` (`author`).
+
 
 ### 1.3.0 - Zod v4 Upgrade & Collection Management Fixes
 

package/dist/adapters/TablesDBAdapter.js

@@ -168,8 +168,9 @@ export class TablesDBAdapter extends BaseAdapter {
     // Attribute Operations
     async createAttribute(params) {
         try {
-            // TablesDB may have different method names for attribute operations
-            const result = await this.tablesDB.createAttribute(params);
+            // Prefer createColumn if available, fallback to createAttribute
+            const fn = this.tablesDB.createColumn || this.tablesDB.createAttribute;
+            const result = await fn.call(this.tablesDB, params);
             return { data: result };
         }
         catch (error) {
@@ -178,7 +179,8 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async updateAttribute(params) {
         try {
-            const result = await this.tablesDB.updateAttribute(params);
+            const fn = this.tablesDB.updateColumn || this.tablesDB.updateAttribute;
+            const result = await fn.call(this.tablesDB, params);
             return { data: result };
         }
         catch (error) {
@@ -187,7 +189,8 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async deleteAttribute(params) {
         try {
-            const result = await this.tablesDB.deleteAttribute(params);
+            const fn = this.tablesDB.deleteColumn || this.tablesDB.deleteAttribute;
+            const result = await fn.call(this.tablesDB, params);
             return { data: result };
         }
         catch (error) {

package/dist/collections/attributes.d.ts

@@ -4,7 +4,7 @@ import { type Attribute } from "appwrite-utils";
  * Enhanced attribute creation with proper status monitoring and retry logic
  */
 export declare const createOrUpdateAttributeWithStatusCheck: (db: Databases, dbId: string, collection: Models.Collection, attribute: Attribute, retryCount?: number, maxRetries?: number) => Promise<boolean>;
-export declare const createOrUpdateAttribute: (db: Databases, dbId: string, collection: Models.Collection, attribute: Attribute) => Promise<void>;
+export declare const createOrUpdateAttribute: (db: Databases, dbId: string, collection: Models.Collection, attribute: Attribute) => Promise<"queued" | "processed">;
 /**
  * Enhanced collection attribute creation with proper status monitoring
  */

package/dist/collections/attributes.js

@@ -157,7 +157,13 @@ export const createOrUpdateAttributeWithStatusCheck = async (db, dbId, collectio
     console.log(chalk.blue(`Creating/updating attribute '${attribute.key}' (attempt ${retryCount + 1}/${maxRetries + 1})`));
     try {
         // First, try to create/update the attribute using existing logic
-        await createOrUpdateAttribute(db, dbId, collection, attribute);
+        const result = await createOrUpdateAttribute(db, dbId, collection, attribute);
+        // If the attribute was queued (relationship dependency unresolved),
+        // skip status polling and retry logic — the queue will handle it later.
+        if (result === "queued") {
+            console.log(chalk.yellow(`⏭️  Deferred relationship attribute '${attribute.key}' — queued for later once dependencies are available`));
+            return true;
+        }
         // Now wait for the attribute to become available
         const success = await waitForAttributeAvailable(db, dbId, collection.$id, attribute.key, 60000, // 1 minute timeout
         retryCount, maxRetries);
@@ -229,7 +235,7 @@ export const createOrUpdateAttribute = async (db, dbId, collection, attribute) =
         attributesSame(foundAttribute, attribute) &&
         updateEnabled) {
         // No need to do anything, they are the same
-        return;
+        return "processed";
     }
     else if (foundAttribute &&
         !attributesSame(foundAttribute, attribute) &&
@@ -248,7 +254,7 @@ export const createOrUpdateAttribute = async (db, dbId, collection, attribute) =
         !attributesSame(foundAttribute, attribute)) {
         await db.deleteAttribute(dbId, collection.$id, attribute.key);
         console.log(`Deleted attribute: ${attribute.key} to recreate it because they diff (update disabled temporarily)`);
-        return;
+        return "processed";
     }
     // console.log(`${action}-ing attribute: ${finalAttribute.key}`);
     // Relationship attribute logic with adjustments
@@ -256,7 +262,18 @@ export const createOrUpdateAttribute = async (db, dbId, collection, attribute) =
     let relatedCollectionId;
     if (finalAttribute.type === "relationship" &&
         finalAttribute.relatedCollection) {
-        if (nameToIdMapping.has(finalAttribute.relatedCollection)) {
+        // First try treating relatedCollection as an ID directly
+        try {
+            const byIdCollection = await db.getCollection(dbId, finalAttribute.relatedCollection);
+            collectionFoundViaRelatedCollection = byIdCollection;
+            relatedCollectionId = byIdCollection.$id;
+            // Cache by name for subsequent lookups
+            nameToIdMapping.set(byIdCollection.name, byIdCollection.$id);
+        }
+        catch (_) {
+            // Not an ID or not found — fall back to name-based resolution below
+        }
+        if (!collectionFoundViaRelatedCollection && nameToIdMapping.has(finalAttribute.relatedCollection)) {
             relatedCollectionId = nameToIdMapping.get(finalAttribute.relatedCollection);
             try {
                 collectionFoundViaRelatedCollection = await db.getCollection(dbId, relatedCollectionId);
@@ -268,7 +285,7 @@ export const createOrUpdateAttribute = async (db, dbId, collection, attribute) =
                 collectionFoundViaRelatedCollection = undefined;
             }
         }
-        else {
+        else if (!collectionFoundViaRelatedCollection) {
             const collectionsPulled = await db.listCollections(dbId, [
                 Query.equal("name", finalAttribute.relatedCollection),
             ]);
@@ -288,7 +305,7 @@ export const createOrUpdateAttribute = async (db, dbId, collection, attribute) =
                 attribute,
                 dependencies: [finalAttribute.relatedCollection],
             });
-            return;
+            return "queued";
         }
     }
     finalAttribute = parseAttribute(finalAttribute);
@@ -445,6 +462,7 @@ export const createOrUpdateAttribute = async (db, dbId, collection, attribute) =
             console.error("Invalid attribute type");
             break;
     }
+    return "processed";
 };
 /**
  * Enhanced collection attribute creation with proper status monitoring

package/dist/collections/indexes.js

@@ -20,13 +20,23 @@ retryCount = 0, maxRetries = 5) => {
     }
     while (Date.now() - startTime < maxWaitTime) {
         try {
-            const indexList = await db.listIndexes(dbId, collectionId);
-            const index = indexList.indexes.find((idx) => idx.key === indexKey);
+            const indexList = await (db instanceof Databases
+                ? db.listIndexes(dbId, collectionId)
+                : db.listIndexes({ databaseId: dbId, tableId: collectionId }));
+            const indexes = (db instanceof Databases)
+                ? indexList.indexes
+                : (indexList.data || indexList.indexes || []);
+            const index = indexes.find((idx) => idx.key === indexKey);
             if (!index) {
                 console.log(chalk.red(`Index '${indexKey}' not found`));
                 return false;
             }
-            console.log(chalk.gray(`Index '${indexKey}' status: ${index.status}`));
+            if (db instanceof Databases) {
+                console.log(chalk.gray(`Index '${indexKey}' status: ${index.status}`));
+            }
+            else {
+                console.log(chalk.gray(`Index '${indexKey}' detected (TablesDB)`));
+            }
             switch (index.status) {
                 case 'available':
                     console.log(chalk.green(`✅ Index '${indexKey}' is now available`));

package/dist/collections/methods.d.ts

@@ -9,11 +9,20 @@ export declare const wipeDatabase: (database: Databases, databaseId: string) =>
     collectionName: string;
 }[]>;
 export declare const wipeCollection: (database: Databases, databaseId: string, collectionId: string) => Promise<void>;
+export declare const wipeAllTables: (adapter: DatabaseAdapter, databaseId: string) => Promise<{
+    tableId: string;
+    tableName: string;
+}[]>;
+export declare const wipeTableRows: (adapter: DatabaseAdapter, databaseId: string, tableId: string) => Promise<void>;
 export declare const generateSchemas: (config: AppwriteConfig, appwriteFolderPath: string) => Promise<void>;
 export declare const createOrUpdateCollections: (database: Databases, databaseId: string, config: AppwriteConfig, deletedCollections?: {
     collectionId: string;
     collectionName: string;
 }[], selectedCollections?: Models.Collection[]) => Promise<void>;
+export declare const createOrUpdateCollectionsViaAdapter: (adapter: DatabaseAdapter, databaseId: string, config: AppwriteConfig, deletedCollections?: {
+    collectionId: string;
+    collectionName: string;
+}[], selectedCollections?: Models.Collection[]) => Promise<void>;
 export declare const generateMockData: (database: Databases, databaseId: string, configCollections: any[]) => Promise<void>;
 export declare const fetchAllCollections: (dbId: string, database: Databases) => Promise<Models.Collection[]>;
 /**

package/dist/collections/methods.js

@@ -198,11 +198,89 @@ export const wipeCollection = async (database, databaseId, collectionId) => {
     const collection = collections.collections[0];
     await wipeDocumentsFromCollection(database, databaseId, collection.$id);
 };
+// TablesDB helpers for wiping
+export const wipeAllTables = async (adapter, databaseId) => {
+    MessageFormatter.info(`Wiping tables in database: ${databaseId}`, { prefix: 'Wipe' });
+    const res = await adapter.listTables({ databaseId, queries: [Query.limit(500)] });
+    const tables = res.tables || [];
+    const deleted = [];
+    const progress = ProgressManager.create(`wipe-db-${databaseId}`, tables.length, { title: 'Deleting tables' });
+    let processed = 0;
+    for (const t of tables) {
+        try {
+            await adapter.deleteTable({ databaseId, tableId: t.$id });
+            deleted.push({ tableId: t.$id, tableName: t.name });
+        }
+        catch (e) {
+            MessageFormatter.error(`Failed deleting table ${t.$id}`, e instanceof Error ? e : new Error(String(e)), { prefix: 'Wipe' });
+        }
+        processed++;
+        progress.update(processed);
+        await delay(100);
+    }
+    progress.stop();
+    return deleted;
+};
+export const wipeTableRows = async (adapter, databaseId, tableId) => {
+    try {
+        const initial = await adapter.listRows({ databaseId, tableId, queries: [Query.limit(1000)] });
+        let rows = initial.rows || [];
+        let total = rows.length;
+        let cursor = rows.length >= 1000 ? rows[rows.length - 1].$id : undefined;
+        while (cursor) {
+            const resp = await adapter.listRows({ databaseId, tableId, queries: [Query.limit(1000), ...(cursor ? [Query.cursorAfter(cursor)] : [])] });
+            const more = resp.rows || [];
+            rows.push(...more);
+            total = rows.length;
+            cursor = more.length >= 1000 ? more[more.length - 1].$id : undefined;
+            if (total % 10000 === 0) {
+                MessageFormatter.progress(`Found ${total} rows...`, { prefix: 'Wipe' });
+            }
+        }
+        MessageFormatter.info(`Found ${total} rows to delete`, { prefix: 'Wipe' });
+        if (total === 0)
+            return;
+        const progress = ProgressManager.create(`delete-${tableId}`, total, { title: 'Deleting rows' });
+        let processed = 0;
+        const maxStackSize = 50;
+        const batches = chunk(rows, maxStackSize);
+        for (const batch of batches) {
+            await Promise.all(batch.map(async (row) => {
+                try {
+                    await adapter.deleteRow({ databaseId, tableId, id: row.$id });
+                }
+                catch (e) {
+                    // ignore missing rows
+                }
+                processed++;
+                progress.update(processed);
+            }));
+            await delay(50);
+        }
+        progress.stop();
+        MessageFormatter.success(`Completed deletion of ${total} rows from table ${tableId}`, { prefix: 'Wipe' });
+    }
+    catch (error) {
+        MessageFormatter.error(`Error wiping rows from table ${tableId}`, error instanceof Error ? error : new Error(String(error)), { prefix: 'Wipe' });
+        throw error;
+    }
+};
 export const generateSchemas = async (config, appwriteFolderPath) => {
     const schemaGenerator = new SchemaGenerator(config, appwriteFolderPath);
     schemaGenerator.generateSchemas();
 };
 export const createOrUpdateCollections = async (database, databaseId, config, deletedCollections, selectedCollections = []) => {
+    // If API mode is tablesdb, route to adapter-based implementation
+    try {
+        const { adapter, apiMode } = await getAdapterFromConfig(config);
+        if (apiMode === 'tablesdb') {
+            await createOrUpdateCollectionsViaAdapter(adapter, databaseId, config, deletedCollections, selectedCollections);
+            return;
+        }
+    }
+    catch {
+        // Fallback to legacy path below
+    }
     const collectionsToProcess = selectedCollections.length > 0 ? selectedCollections : config.collections;
     if (!collectionsToProcess) {
         return;
@@ -304,6 +382,196 @@ export const createOrUpdateCollections = async (database, databaseId, config, de
         MessageFormatter.info("No queued operations to process", { prefix: "Collections" });
     }
 };
+// New: Adapter-based implementation for TablesDB
+export const createOrUpdateCollectionsViaAdapter = async (adapter, databaseId, config, deletedCollections, selectedCollections = []) => {
+    const collectionsToProcess = selectedCollections.length > 0 ? selectedCollections : (config.collections || []);
+    if (!collectionsToProcess || collectionsToProcess.length === 0)
+        return;
+    const usedIds = new Set();
+    // Helper: create attributes through adapter
+    const createAttr = async (tableId, attr) => {
+        const base = {
+            databaseId,
+            tableId,
+            key: attr.key,
+            type: attr.type,
+            size: attr.size,
+            required: !!attr.required,
+            default: attr.xdefault,
+            array: !!attr.array,
+            min: attr.min,
+            max: attr.max,
+            elements: attr.elements,
+            encrypt: attr.encrypted,
+            relatedCollection: attr.relatedCollection,
+            relationType: attr.relationType,
+            twoWay: attr.twoWay,
+            twoWayKey: attr.twoWayKey,
+            onDelete: attr.onDelete,
+            side: attr.side,
+        };
+        await adapter.createAttribute(base);
+        await delay(150);
+    };
+    // Local queue for unresolved relationships
+    const relQueue = [];
+    for (const collection of collectionsToProcess) {
+        const { attributes, indexes, ...collectionData } = collection;
+        // Prepare permissions as strings (reuse Permission helper)
+        const permissions = [];
+        if (collection.$permissions && collection.$permissions.length > 0) {
+            for (const p of collection.$permissions) {
+                if (typeof p === 'string')
+                    permissions.push(p);
+                else {
+                    switch (p.permission) {
+                        case 'read':
+                            permissions.push(Permission.read(p.target));
+                            break;
+                        case 'create':
+                            permissions.push(Permission.create(p.target));
+                            break;
+                        case 'update':
+                            permissions.push(Permission.update(p.target));
+                            break;
+                        case 'delete':
+                            permissions.push(Permission.delete(p.target));
+                            break;
+                        case 'write':
+                            permissions.push(Permission.write(p.target));
+                            break;
+                        default: break;
+                    }
+                }
+            }
+        }
+        // Find existing table by name
+        const list = await adapter.listTables({ databaseId, queries: [Query.equal('name', collectionData.name)] });
+        const items = list.tables || [];
+        let table = items[0];
+        let tableId;
+        if (!table) {
+            // Determine ID (prefer provided $id or re-use deleted one)
+            let foundColl = deletedCollections?.find((coll) => coll.collectionName.toLowerCase().trim().replace(" ", "") === collectionData.name.toLowerCase().trim().replace(" ", ""));
+            if (collectionData.$id)
+                tableId = collectionData.$id;
+            else if (foundColl && !usedIds.has(foundColl.collectionId))
+                tableId = foundColl.collectionId;
+            else
+                tableId = ID.unique();
+            usedIds.add(tableId);
+            const res = await adapter.createTable({
+                databaseId,
+                id: tableId,
+                name: collectionData.name,
+                permissions,
+                documentSecurity: !!collectionData.documentSecurity,
+                enabled: collectionData.enabled !== false
+            });
+            table = res.data || res;
+            nameToIdMapping.set(collectionData.name, tableId);
+        }
+        else {
+            tableId = table.$id;
+            await adapter.updateTable({
+                databaseId,
+                id: tableId,
+                name: collectionData.name,
+                permissions,
+                documentSecurity: !!collectionData.documentSecurity,
+                enabled: collectionData.enabled !== false
+            });
+        }
+        // Add small delay after table create/update
+        await delay(250);
+        // Create attributes: non-relationship first
+        const nonRel = (attributes || []).filter((a) => a.type !== 'relationship');
+        for (const attr of nonRel) {
+            await createAttr(tableId, attr);
+        }
+        // Relationship attributes — resolve relatedCollection to ID
+        const rels = (attributes || []).filter((a) => a.type === 'relationship');
+        for (const attr of rels) {
+            const relNameOrId = attr.relatedCollection;
+            if (!relNameOrId)
+                continue;
+            let relId = nameToIdMapping.get(relNameOrId) || relNameOrId;
+            // If looks like a name (not ULID) and not in cache, try query by name
+            if (!nameToIdMapping.has(relNameOrId)) {
+                try {
+                    const relList = await adapter.listTables({ databaseId, queries: [Query.equal('name', relNameOrId)] });
+                    const relItems = relList.tables || [];
+                    if (relItems[0]?.$id) {
+                        relId = relItems[0].$id;
+                        nameToIdMapping.set(relNameOrId, relId);
+                    }
+                }
+                catch { }
+            }
+            if (relId && typeof relId === 'string') {
+                attr.relatedCollection = relId;
+                await createAttr(tableId, attr);
+            }
+            else {
+                // Defer if unresolved
+                relQueue.push({ tableId, attr: attr });
+            }
+        }
+        // Indexes
+        const idxs = (indexes || []);
+        for (const idx of idxs) {
+            try {
+                await adapter.createIndex({
+                    databaseId,
+                    tableId,
+                    key: idx.key,
+                    type: idx.type,
+                    attributes: idx.attributes,
+                    orders: idx.orders || []
+                });
+                await delay(150);
+            }
+            catch (e) {
+                MessageFormatter.error(`Failed to create index ${idx.key}`, e instanceof Error ? e : new Error(String(e)), { prefix: 'Indexes' });
+            }
+        }
+    }
+    // Process queued relationships once mapping likely populated
+    for (const { tableId, attr } of relQueue) {
+        const relNameOrId = attr.relatedCollection;
+        if (!relNameOrId)
+            continue;
+        const relId = nameToIdMapping.get(relNameOrId) || relNameOrId;
+        if (relId) {
+            attr.relatedCollection = relId;
+            try {
+                await adapter.createAttribute({
+                    databaseId,
+                    tableId,
+                    key: attr.key,
+                    type: attr.type,
+                    size: attr.size,
+                    required: !!attr.required,
+                    default: attr.xdefault,
+                    array: !!attr.array,
+                    min: attr.min,
+                    max: attr.max,
+                    elements: attr.elements,
+                    relatedCollection: relId,
+                    relationType: attr.relationType,
+                    twoWay: attr.twoWay,
+                    twoWayKey: attr.twoWayKey,
+                    onDelete: attr.onDelete,
+                    side: attr.side
+                });
+                await delay(150);
+            }
+            catch (e) {
+                MessageFormatter.error(`Failed queued relationship ${attr.key}`, e instanceof Error ? e : new Error(String(e)), { prefix: 'Attributes' });
+            }
+        }
+    }
+};
 export const generateMockData = async (database, databaseId, configCollections) => {
     for (const { collection, mockFunction } of configCollections) {
         if (mockFunction) {

package/dist/migrations/appwriteToX.d.ts

@@ -90,12 +90,12 @@ export declare class AppwriteToX {
         relatedCollection: string;
         relationType: "oneToMany" | "manyToOne" | "oneToOne" | "manyToMany";
         twoWay: boolean;
-        twoWayKey: string;
         onDelete: "setNull" | "cascade" | "restrict";
-        side: "parent" | "child";
         error?: string | undefined;
         required?: boolean | undefined;
         array?: boolean | undefined;
+        twoWayKey?: string | undefined;
+        side?: "parent" | "child" | undefined;
         importMapping?: {
             originalIdField: string;
             targetField?: string | undefined;

package/dist/migrations/comprehensiveTransfer.js

@@ -2,6 +2,7 @@ import { converterFunctions, tryAwaitWithRetry, parseAttribute, objectNeedsUpdat
 import { Client, Databases, Storage, Users, Functions, Teams, Query, AppwriteException, } from "node-appwrite";
 import { InputFile } from "node-appwrite/file";
 import { MessageFormatter } from "../shared/messageFormatter.js";
+import { processQueue, queuedOperations } from "../shared/operationQueue.js";
 import { ProgressManager } from "../shared/progressManager.js";
 import { getClient } from "../utils/getClientFromConfig.js";
 import { transferDatabaseLocalToLocal, transferDatabaseLocalToRemote, transferStorageLocalToLocal, transferStorageLocalToRemote, transferUsersLocalToRemote, } from "./transfer.js";
@@ -343,6 +344,17 @@ export class ComprehensiveTransfer {
                     MessageFormatter.error(`Error processing collection ${collection.name}`, error instanceof Error ? error : new Error(String(error)), { prefix: "Transfer" });
                 }
             }
+            // After processing all collections' attributes and indexes, process any queued
+            // relationship attributes so dependencies are resolved within this phase.
+            if (queuedOperations.length > 0) {
+                MessageFormatter.info(`Processing ${queuedOperations.length} queued relationship operations`, { prefix: "Transfer" });
+                await processQueue(this.targetDatabases, dbId);
+            }
+            else {
+                MessageFormatter.info("No queued relationship operations to process", {
+                    prefix: "Transfer",
+                });
+            }
         }
         catch (error) {
             MessageFormatter.error(`Failed to create database structure for ${dbId}`, error instanceof Error ? error : new Error(String(error)), { prefix: "Transfer" });

package/dist/migrations/dataLoader.d.ts

@@ -100,16 +100,16 @@ export declare const CollectionImportDataSchema: z.ZodObject<{
                 manyToMany: "manyToMany";
             }>;
             twoWay: z.ZodBoolean;
-            twoWayKey: z.ZodString;
+            twoWayKey: z.ZodOptional<z.ZodString>;
             onDelete: z.ZodDefault<z.ZodEnum<{
                 setNull: "setNull";
                 cascade: "cascade";
                 restrict: "restrict";
             }>>;
-            side: z.ZodEnum<{
+            side: z.ZodOptional<z.ZodEnum<{
                 parent: "parent";
                 child: "child";
-            }>;
+            }>>;
             importMapping: z.ZodOptional<z.ZodObject<{
                 originalIdField: z.ZodString;
                 targetField: z.ZodOptional<z.ZodString>;
@@ -374,12 +374,12 @@ export declare class DataLoader {
                 relatedCollection: string;
                 relationType: "oneToMany" | "manyToOne" | "oneToOne" | "manyToMany";
                 twoWay: boolean;
-                twoWayKey: string;
                 onDelete: "setNull" | "cascade" | "restrict";
-                side: "parent" | "child";
                 error?: string | undefined;
                 required?: boolean | undefined;
                 array?: boolean | undefined;
+                twoWayKey?: string | undefined;
+                side?: "parent" | "child" | undefined;
                 importMapping?: {
                     originalIdField: string;
                     targetField?: string | undefined;

package/dist/migrations/relationships.d.ts

@@ -9,12 +9,12 @@ export declare const findCollectionsWithRelationships: (config: AppwriteConfig)
     relatedCollection: string;
     relationType: "oneToMany" | "manyToOne" | "oneToOne" | "manyToMany";
     twoWay: boolean;
-    twoWayKey: string;
     onDelete: "setNull" | "cascade" | "restrict";
-    side: "parent" | "child";
     error?: string | undefined;
     required?: boolean | undefined;
     array?: boolean | undefined;
+    twoWayKey?: string | undefined;
+    side?: "parent" | "child" | undefined;
     importMapping?: {
         originalIdField: string;
         targetField?: string | undefined;

package/dist/shared/jsonSchemaGenerator.d.ts

@@ -31,6 +31,7 @@ export declare class JsonSchemaGenerator {
     private appwriteFolderPath;
     private relationshipMap;
     constructor(config: AppwriteConfig, appwriteFolderPath: string);
+    private resolveCollectionName;
     private extractRelationships;
     private attributeToJsonSchemaProperty;
     private getBaseTypeSchema;

package/dist/shared/jsonSchemaGenerator.js

@@ -11,6 +11,10 @@ export class JsonSchemaGenerator {
         this.appwriteFolderPath = appwriteFolderPath;
         this.extractRelationships();
     }
+    resolveCollectionName = (idOrName) => {
+        const col = this.config.collections?.find((c) => c.$id === idOrName || c.name === idOrName);
+        return col?.name ?? idOrName;
+    };
     extractRelationships() {
         if (!this.config.collections)
             return;
@@ -22,7 +26,7 @@ export class JsonSchemaGenerator {
                     const relationships = this.relationshipMap.get(collection.name) || [];
                     relationships.push({
                         attributeKey: attr.key,
-                        relatedCollection: attr.relatedCollection,
+                        relatedCollection: this.resolveCollectionName(attr.relatedCollection),
                         relationType: attr.relationType,
                         isArray: attr.relationType === "oneToMany" || attr.relationType === "manyToMany"
                     });
@@ -108,7 +112,7 @@ export class JsonSchemaGenerator {
             case "relationship":
                 if (attribute.relatedCollection) {
                     // For relationships, reference the related collection schema
-                    schema.$ref = `#/definitions/${toPascalCase(attribute.relatedCollection)}`;
+                    schema.$ref = `#/definitions/${toPascalCase(this.resolveCollectionName(attribute.relatedCollection))}`;
                 }
                 else {
                     schema.type = "string";

package/dist/shared/operationQueue.js

@@ -33,7 +33,20 @@ export const processQueue = async (db, dbId) => {
                 }
                 // Attempt to resolve related collection if specified and not already found
                 if (!collectionFound && operation.attribute?.relatedCollection) {
-                    collectionFound = await fetchAndCacheCollectionByName(db, dbId, operation.attribute.relatedCollection);
+                    // First, try treating relatedCollection as an ID
+                    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.
+                    }
+                    catch (_) {
+                        // Not an ID or not found; fall back to name-based cache
+                    }
+                    // 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) {

package/dist/shared/schemaGenerator.d.ts

@@ -4,6 +4,7 @@ export declare class SchemaGenerator {
     private config;
     private appwriteFolderPath;
     constructor(config: AppwriteConfig, appwriteFolderPath: string);
+    private resolveCollectionName;
     updateYamlCollections(): void;
     updateTsSchemas(): void;
     updateConfig(config: AppwriteConfig, isYamlConfig?: boolean): Promise<void>;
@@ -15,6 +16,6 @@ export declare class SchemaGenerator {
         format?: "zod" | "json" | "both";
         verbose?: boolean;
     }): void;
-    createSchemaString: (name: string, attributes: Attribute[]) => string;
+    createSchemaStringV4: (name: string, attributes: Attribute[]) => string;
     typeToZod: (attribute: Attribute) => string;
 }