appwrite-utils-cli 1.11.0 → 1.12.0

package/dist/collections/tableOperations.d.ts

@@ -0,0 +1,87 @@
+import type { Attribute } from "appwrite-utils";
+interface ColumnPropertyChange {
+    property: string;
+    oldValue: any;
+    newValue: any;
+    requiresRecreate: boolean;
+}
+interface ColumnOperationPlan {
+    toCreate: Attribute[];
+    toUpdate: Array<{
+        attribute: Attribute;
+        changes: ColumnPropertyChange[];
+    }>;
+    toRecreate: Array<{
+        oldAttribute: any;
+        newAttribute: Attribute;
+    }>;
+    toDelete: Array<{
+        attribute: any;
+    }>;
+    unchanged: string[];
+}
+type ComparableColumn = {
+    key: string;
+    type: string;
+    required?: boolean;
+    array?: boolean;
+    default?: any;
+    size?: number;
+    min?: number;
+    max?: number;
+    elements?: string[];
+    encrypt?: boolean;
+    relatedCollection?: string;
+    relationType?: string;
+    twoWay?: boolean;
+    twoWayKey?: string;
+    onDelete?: string;
+    side?: string;
+};
+export declare function normalizeAttributeToComparable(attr: Attribute): ComparableColumn;
+export declare function normalizeColumnToComparable(col: any): ComparableColumn;
+export declare function isColumnEqualToColumn(a: any, b: any): boolean;
+export declare function isIndexEqualToIndex(a: any, b: any): boolean;
+/**
+ * Enhanced version of columns diff with detailed change analysis
+ * Order: desired first, then existing (matches internal usage here)
+ * Handles case-insensitive key matches as renames (recreates)
+ */
+export declare function diffColumnsDetailed(desiredAttributes: Attribute[], existingColumns: any[]): ColumnOperationPlan;
+/**
+ * Returns true if there is any difference between existing columns and desired attributes
+ */
+export declare function areTableColumnsDiff(existingColumns: any[], desired: Attribute[]): boolean;
+export declare function diffTableColumns(existingColumns: any[], desired: Attribute[]): {
+    toCreate: Attribute[];
+    toUpdate: Attribute[];
+    unchanged: string[];
+};
+/**
+ * Execute the column operation plan using the adapter
+ */
+export declare function executeColumnOperations(adapter: any, databaseId: string, tableId: string, plan: ColumnOperationPlan): Promise<{
+    success: string[];
+    errors: Array<{
+        column: string;
+        error: string;
+    }>;
+}>;
+/**
+ * Integration function for methods.ts - processes columns using enhanced logic
+ */
+export declare function processTableColumns(adapter: any, databaseId: string, tableId: string, desiredAttributes: Attribute[], existingColumns?: any[]): Promise<{
+    totalProcessed: number;
+    success: string[];
+    errors: Array<{
+        column: string;
+        error: string;
+    }>;
+    summary: {
+        created: number;
+        updated: number;
+        recreated: number;
+        unchanged: number;
+    };
+}>;
+export {};

package/dist/collections/tableOperations.js

@@ -0,0 +1,466 @@
+import { mapToCreateAttributeParams, mapToUpdateAttributeParams } from "appwrite-utils-helpers";
+import { Decimal } from "decimal.js";
+const EXTREME_BOUND = new Decimal('1e12');
+// Property configuration for different column types
+const MUTABLE_PROPERTIES = {
+    string: ["required", "default", "size", "array"],
+    integer: ["required", "default", "min", "max", "array"],
+    float: ["required", "default", "min", "max", "array"],
+    double: ["required", "default", "min", "max", "array"],
+    boolean: ["required", "default", "array"],
+    datetime: ["required", "default", "array"],
+    email: ["required", "default", "array"],
+    ip: ["required", "default", "array"],
+    url: ["required", "default", "array"],
+    enum: ["required", "default", "elements", "array"],
+    relationship: ["required", "default"],
+};
+const IMMUTABLE_PROPERTIES = {
+    string: ["encrypt", "key"],
+    integer: ["encrypt", "key"],
+    float: ["encrypt", "key"],
+    double: ["encrypt", "key"],
+    boolean: ["key"],
+    datetime: ["key"],
+    email: ["key"],
+    ip: ["key"],
+    url: ["key"],
+    enum: ["key"],
+    relationship: ["key", "relatedCollection", "relationType", "twoWay", "twoWayKey", "onDelete"],
+};
+const TYPE_CHANGE_REQUIRES_RECREATE = [
+    "string",
+    "integer",
+    "float",
+    "double",
+    "boolean",
+    "datetime",
+    "email",
+    "ip",
+    "url",
+    "enum",
+    "relationship",
+];
+function normDefault(val) {
+    // Treat undefined and null as equal unset default
+    return val === undefined ? null : val;
+}
+function toNumber(n) {
+    if (n === null || n === undefined)
+        return undefined;
+    const num = Number(n);
+    return Number.isFinite(num) ? num : undefined;
+}
+export function normalizeAttributeToComparable(attr) {
+    const t = String(attr.type || '').toLowerCase();
+    const base = {
+        key: attr.key,
+        type: t,
+        required: !!attr.required,
+        array: !!attr.array,
+        default: normDefault(attr.xdefault),
+    };
+    if (t === 'string') {
+        base.size = attr.size ?? 255;
+        base.encrypt = !!(attr.encrypt);
+    }
+    if (t === 'integer' || t === 'float' || t === 'double') {
+        const min = toNumber(attr.min);
+        const max = toNumber(attr.max);
+        if (min !== undefined && max !== undefined) {
+            base.min = Math.min(min, max);
+            base.max = Math.max(min, max);
+        }
+        else {
+            base.min = min;
+            base.max = max;
+        }
+    }
+    if (t === 'enum') {
+        base.elements = Array.isArray(attr.elements) ? attr.elements.slice().sort() : [];
+    }
+    if (t === 'relationship') {
+        base.relatedCollection = attr.relatedCollection;
+        base.relationType = attr.relationType;
+        base.twoWay = !!attr.twoWay;
+        base.twoWayKey = attr.twoWayKey;
+        base.onDelete = attr.onDelete;
+        base.side = attr.side;
+    }
+    return base;
+}
+export function normalizeColumnToComparable(col) {
+    // Detect enum surfaced as string+elements or string+format:enum from server and normalize to enum for comparison
+    let t = String((col?.type ?? col?.columnType ?? '')).toLowerCase();
+    const hasElements = Array.isArray(col?.elements) && col.elements.length > 0;
+    const hasEnumFormat = (col?.format === 'enum');
+    if (t === 'string' && (hasElements || hasEnumFormat)) {
+        t = 'enum';
+    }
+    const base = {
+        key: col?.key,
+        type: t,
+        required: !!col?.required,
+        array: !!col?.array,
+        default: normDefault(col?.default ?? col?.xdefault),
+    };
+    if (t === 'string') {
+        base.size = typeof col?.size === 'number' ? col.size : undefined;
+        base.encrypt = !!col?.encrypt;
+    }
+    if (t === 'integer' || t === 'float' || t === 'double') {
+        // Preserve raw min/max without forcing extremes; compare with Decimal in shallowEqual
+        const rawMin = col?.min;
+        const rawMax = col?.max;
+        base.min = rawMin;
+        base.max = rawMax;
+    }
+    if (t === 'enum') {
+        base.elements = Array.isArray(col?.elements) ? col.elements.slice().sort() : [];
+    }
+    if (t === 'relationship') {
+        base.relatedCollection = col?.relatedTableId || col?.relatedCollection;
+        base.relationType = col?.relationType || col?.typeName;
+        base.twoWay = !!col?.twoWay;
+        base.twoWayKey = col?.twoWayKey;
+        base.onDelete = col?.onDelete;
+        base.side = col?.side;
+    }
+    return base;
+}
+function shallowEqual(a, b) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const k of keys) {
+        const va = a[k];
+        const vb = b[k];
+        if (Array.isArray(va) && Array.isArray(vb)) {
+            if (va.length !== vb.length)
+                return false;
+            for (let i = 0; i < va.length; i++)
+                if (va[i] !== vb[i])
+                    return false;
+        }
+        else if (k === 'min' || k === 'max') {
+            // Compare numeric bounds with Decimal to avoid precision issues
+            if (va == null && vb == null)
+                continue;
+            if (va == null || vb == null) {
+                // Treat extreme bounds on one side as equivalent to undefined (unbounded)
+                const present = va == null ? vb : va;
+                try {
+                    const dp = new Decimal(String(present));
+                    if (dp.abs().greaterThanOrEqualTo(EXTREME_BOUND))
+                        continue; // equal
+                }
+                catch { }
+                return false;
+            }
+            try {
+                const da = new Decimal(String(va));
+                const db = new Decimal(String(vb));
+                if (!da.equals(db))
+                    return false;
+            }
+            catch {
+                if (va !== vb)
+                    return false;
+            }
+        }
+        else if (va !== vb) {
+            // Treat null and undefined as equal for defaults
+            if (!(va == null && vb == null))
+                return false;
+        }
+    }
+    return true;
+}
+export function isColumnEqualToColumn(a, b) {
+    const na = normalizeColumnToComparable(a);
+    const nb = normalizeColumnToComparable(b);
+    return shallowEqual(na, nb);
+}
+export function isIndexEqualToIndex(a, b) {
+    if (!a || !b)
+        return false;
+    if (a.key !== b.key)
+        return false;
+    if (String(a.type).toLowerCase() !== String(b.type).toLowerCase())
+        return false;
+    // Compare attributes as sets (order-insensitive)
+    // Support TablesDB which returns 'columns' instead of 'attributes'
+    const attrsAraw = Array.isArray(a.attributes)
+        ? a.attributes
+        : (Array.isArray(a.columns) ? a.columns : []);
+    const attrsA = [...attrsAraw].sort();
+    const attrsB = Array.isArray(b.attributes)
+        ? [...b.attributes].sort()
+        : (Array.isArray(b.columns) ? [...b.columns].sort() : []);
+    if (attrsA.length !== attrsB.length)
+        return false;
+    for (let i = 0; i < attrsA.length; i++)
+        if (attrsA[i] !== attrsB[i])
+            return false;
+    // Orders are only considered if CONFIG (b) has orders defined
+    // This prevents false positives when Appwrite returns orders but user didn't specify them
+    const hasConfigOrders = Array.isArray(b.orders) && b.orders.length > 0;
+    if (hasConfigOrders) {
+        // Some APIs may expose 'directions' instead of 'orders'
+        const ordersA = Array.isArray(a.orders)
+            ? [...a.orders].sort()
+            : (Array.isArray(a.directions) ? [...a.directions].sort() : []);
+        const ordersB = [...b.orders].sort();
+        if (ordersA.length !== ordersB.length)
+            return false;
+        for (let i = 0; i < ordersA.length; i++)
+            if (ordersA[i] !== ordersB[i])
+                return false;
+    }
+    return true;
+}
+/**
+ * Compare individual properties between old and new columns
+ */
+function compareColumnProperties(oldColumn, newAttribute, columnType) {
+    const changes = [];
+    const t = String(columnType || newAttribute.type || '').toLowerCase();
+    const key = newAttribute?.key || 'unknown';
+    const mutableProps = MUTABLE_PROPERTIES[t] || [];
+    const immutableProps = IMMUTABLE_PROPERTIES[t] || [];
+    const getNewVal = (prop) => {
+        const na = newAttribute;
+        if (prop === 'default')
+            return na.xdefault;
+        if (prop === 'encrypt')
+            return na.encrypt;
+        return na[prop];
+    };
+    const getOldVal = (prop) => {
+        if (prop === 'default')
+            return oldColumn?.default ?? oldColumn?.xdefault;
+        return oldColumn?.[prop];
+    };
+    for (const prop of mutableProps) {
+        const oldValue = getOldVal(prop);
+        let newValue = getNewVal(prop);
+        // Special-case: enum elements empty/missing should not trigger updates
+        if (t === 'enum' && prop === 'elements') {
+            if (!Array.isArray(newValue) || newValue.length === 0) {
+                newValue = oldValue;
+            }
+        }
+        if (Array.isArray(oldValue) && Array.isArray(newValue)) {
+            if (oldValue.length !== newValue.length || oldValue.some((v, i) => v !== newValue[i])) {
+                changes.push({ property: prop, oldValue, newValue, requiresRecreate: false });
+            }
+        }
+        else if (oldValue !== newValue) {
+            changes.push({ property: prop, oldValue, newValue, requiresRecreate: false });
+        }
+    }
+    for (const prop of immutableProps) {
+        const oldValue = getOldVal(prop);
+        const newValue = getNewVal(prop);
+        if (Array.isArray(oldValue) && Array.isArray(newValue)) {
+            if (oldValue.length !== newValue.length || oldValue.some((v, i) => v !== newValue[i])) {
+                changes.push({ property: prop, oldValue, newValue, requiresRecreate: true });
+            }
+        }
+        else if (oldValue !== newValue) {
+            changes.push({ property: prop, oldValue, newValue, requiresRecreate: true });
+        }
+    }
+    // Type change requires recreate (normalize string+elements to enum on old side)
+    const oldTypeRaw = String(oldColumn?.type || oldColumn?.columnType || '').toLowerCase();
+    const oldHasElements = Array.isArray(oldColumn?.elements) && oldColumn.elements.length > 0;
+    const oldHasEnumFormat = (oldColumn?.format === 'enum');
+    const oldType = oldTypeRaw === 'string' && (oldHasElements || oldHasEnumFormat) ? 'enum' : oldTypeRaw;
+    if (oldType && t && oldType !== t && TYPE_CHANGE_REQUIRES_RECREATE.includes(oldType)) {
+        changes.push({ property: 'type', oldValue: oldType, newValue: t, requiresRecreate: true });
+    }
+    return changes;
+}
+/**
+ * Analyze what changes are needed for a specific column
+ */
+function analyzeColumnChanges(oldColumn, newAttribute) {
+    const columnType = String(newAttribute.type || 'string').toLowerCase();
+    const columnKey = newAttribute.key;
+    // Use normalized comparison to reduce false positives then property-wise details
+    const normalizedOld = normalizeColumnToComparable(oldColumn);
+    const normalizedNew = normalizeAttributeToComparable(newAttribute);
+    const hasAnyDiff = !shallowEqual(normalizedOld, normalizedNew);
+    const changes = hasAnyDiff ? compareColumnProperties(oldColumn, newAttribute, columnType) : [];
+    const requiresRecreate = changes.some((c) => c.requiresRecreate);
+    const mutableChanges = {};
+    const immutableChanges = {};
+    for (const c of changes) {
+        if (c.requiresRecreate)
+            immutableChanges[c.property] = { old: c.oldValue, new: c.newValue };
+        else
+            mutableChanges[c.property] = { old: c.oldValue, new: c.newValue };
+    }
+    return {
+        columnKey,
+        columnType,
+        hasChanges: changes.length > 0,
+        requiresRecreate,
+        changes,
+        mutableChanges,
+        immutableChanges,
+    };
+}
+/**
+ * Enhanced version of columns diff with detailed change analysis
+ * Order: desired first, then existing (matches internal usage here)
+ * Handles case-insensitive key matches as renames (recreates)
+ */
+export function diffColumnsDetailed(desiredAttributes, existingColumns) {
+    // Exact key lookup (case-sensitive)
+    const byKey = new Map((existingColumns || []).map((col) => [col?.key, col]));
+    // Case-insensitive key lookup for detecting renames
+    const byKeyLower = new Map((existingColumns || []).map((col) => [col?.key?.toLowerCase(), col]));
+    const toCreate = [];
+    const toUpdate = [];
+    const toRecreate = [];
+    const unchanged = [];
+    const handledExistingKeys = new Set(); // Track which existing columns we've handled
+    for (const attr of desiredAttributes || []) {
+        const key = attr?.key;
+        if (!key)
+            continue;
+        // First try exact match
+        const exactMatch = byKey.get(key);
+        if (exactMatch) {
+            handledExistingKeys.add(key);
+            const analysis = analyzeColumnChanges(exactMatch, attr);
+            if (!analysis.hasChanges)
+                unchanged.push(analysis.columnKey);
+            else if (analysis.requiresRecreate)
+                toRecreate.push({ oldAttribute: exactMatch, newAttribute: attr });
+            else
+                toUpdate.push({ attribute: attr, changes: analysis.changes });
+            continue;
+        }
+        // Check for case-insensitive match (rename scenario like oAuthAccounts -> oauthAccounts)
+        const caseInsensitiveMatch = byKeyLower.get(key.toLowerCase());
+        if (caseInsensitiveMatch && caseInsensitiveMatch.key !== key) {
+            // This is a rename - treat as recreate (delete old, create new)
+            handledExistingKeys.add(caseInsensitiveMatch.key);
+            toRecreate.push({ oldAttribute: caseInsensitiveMatch, newAttribute: attr });
+            continue;
+        }
+        // No match - it's a new attribute
+        toCreate.push(attr);
+    }
+    // Note: we keep toDelete empty for now (conservative behavior)
+    // Deletions are handled separately in methods.ts
+    return { toCreate, toUpdate, toRecreate, toDelete: [], unchanged };
+}
+/**
+ * Returns true if there is any difference between existing columns and desired attributes
+ */
+export function areTableColumnsDiff(existingColumns, desired) {
+    const byKey = new Map();
+    for (const c of existingColumns || []) {
+        if (c?.key)
+            byKey.set(c.key, c);
+    }
+    for (const attr of desired || []) {
+        const desiredNorm = normalizeAttributeToComparable(attr);
+        const existing = byKey.get(desiredNorm.key);
+        if (!existing)
+            return true;
+        const existingNorm = normalizeColumnToComparable(existing);
+        if (!shallowEqual(desiredNorm, existingNorm))
+            return true;
+    }
+    // Extra columns on remote also constitute a diff
+    const desiredKeys = new Set((desired || []).map((a) => a.key));
+    for (const k of byKey.keys())
+        if (!desiredKeys.has(k))
+            return true;
+    return false;
+}
+export function diffTableColumns(existingColumns, desired) {
+    // Use detailed plan but return legacy structure for compatibility
+    const plan = diffColumnsDetailed(desired, existingColumns);
+    const toUpdate = [
+        ...plan.toUpdate.map((u) => u.attribute),
+        ...plan.toRecreate.map((r) => r.newAttribute),
+    ];
+    return { toCreate: plan.toCreate, toUpdate, unchanged: plan.unchanged };
+}
+/**
+ * Execute the column operation plan using the adapter
+ */
+export async function executeColumnOperations(adapter, databaseId, tableId, plan) {
+    if (!databaseId || !tableId)
+        throw new Error('Database ID and Table ID are required for column operations');
+    if (!adapter || typeof adapter.createAttribute !== 'function')
+        throw new Error('Valid adapter is required for column operations');
+    const results = { success: [], errors: [] };
+    const exec = async (fn, key, op) => {
+        try {
+            await fn();
+            results.success.push(`${op}: ${key}`);
+        }
+        catch (e) {
+            results.errors.push({ column: key, error: `${op} failed: ${e?.message || String(e)}` });
+        }
+    };
+    for (const attr of plan.toCreate) {
+        const params = mapToCreateAttributeParams(attr, { databaseId, tableId });
+        await exec(() => adapter.createAttribute(params), attr.key, 'CREATE');
+    }
+    for (const { attribute } of plan.toUpdate) {
+        const params = mapToUpdateAttributeParams(attribute, { databaseId, tableId });
+        await exec(() => adapter.updateAttribute(params), attribute.key, 'UPDATE');
+    }
+    for (const { oldAttribute, newAttribute } of plan.toRecreate) {
+        await exec(() => adapter.deleteAttribute({ databaseId, tableId, key: oldAttribute.key }), oldAttribute.key, 'DELETE (for recreate)');
+        // Wait until the attribute is actually removed (or no longer 'deleting') before recreating
+        try {
+            const start = Date.now();
+            const maxWaitMs = 60000; // 60s
+            while (Date.now() - start < maxWaitMs) {
+                try {
+                    const tableRes = await adapter.getTable({ databaseId, tableId });
+                    const cols = (tableRes?.data?.columns || tableRes?.data?.attributes || []);
+                    const found = cols.find((c) => c.key === oldAttribute.key);
+                    if (!found)
+                        break; // fully removed
+                    if (found.status && found.status !== 'deleting')
+                        break; // no longer deleting (failed/stuck) -> stop waiting
+                }
+                catch { }
+                await new Promise((r) => setTimeout(r, 1500));
+            }
+        }
+        catch { }
+        const params = mapToCreateAttributeParams(newAttribute, { databaseId, tableId });
+        await exec(() => adapter.createAttribute(params), newAttribute.key, 'CREATE (after recreate)');
+    }
+    return results;
+}
+/**
+ * Integration function for methods.ts - processes columns using enhanced logic
+ */
+export async function processTableColumns(adapter, databaseId, tableId, desiredAttributes, existingColumns = []) {
+    if (!existingColumns || existingColumns.length === 0) {
+        const tableInfo = await adapter.getTable({ databaseId, tableId });
+        existingColumns = (tableInfo?.data?.columns || tableInfo?.data?.attributes || []);
+    }
+    const plan = diffColumnsDetailed(desiredAttributes, existingColumns);
+    const results = await executeColumnOperations(adapter, databaseId, tableId, plan);
+    return {
+        totalProcessed: plan.toCreate.length + plan.toUpdate.length + plan.toRecreate.length,
+        success: results.success,
+        errors: results.errors,
+        summary: {
+            created: plan.toCreate.length,
+            updated: plan.toUpdate.length,
+            recreated: plan.toRecreate.length,
+            unchanged: plan.unchanged.length,
+        },
+    };
+}

package/dist/collections/transferOperations.d.ts

@@ -0,0 +1,8 @@
+import { Databases } from "node-appwrite";
+import type { DatabaseAdapter } from "appwrite-utils-helpers";
+/**
+ * Transfers all documents from one collection to another in a different database
+ * within the same Appwrite Project
+ */
+export declare const transferDocumentsBetweenDbsLocalToLocal: (db: Databases | DatabaseAdapter, fromDbId: string, toDbId: string, fromCollId: string, toCollId: string) => Promise<void>;
+export declare const transferDocumentsBetweenDbsLocalToRemote: (localDb: Databases | DatabaseAdapter, endpoint: string, projectId: string, apiKey: string, fromDbId: string, toDbId: string, fromCollId: string, toCollId: string) => Promise<void>;