@njdamstra/appwrite-utils-cli 1.10.0 → 1.11.0

package/dist/cli/commands/migrateCommands.d.ts

@@ -0,0 +1,6 @@
+import type { InteractiveCLI } from "../../interactiveCLI.js";
+export declare const migrateCommands: {
+    migrateStrings(cli: InteractiveCLI): Promise<void>;
+    analyzePhase(cli: InteractiveCLI): Promise<void>;
+    executePhase(cli: InteractiveCLI): Promise<void>;
+};

package/dist/cli/commands/migrateCommands.js

@@ -0,0 +1,118 @@
+import inquirer from "inquirer";
+import path from "node:path";
+import { MessageFormatter } from "@njdamstra/appwrite-utils-helpers";
+import { analyzeStringAttributes, executeMigrationPlan, } from "../../migrations/migrateStrings.js";
+export const migrateCommands = {
+    async migrateStrings(cli) {
+        const { phase } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "phase",
+                message: "String attribute migration:",
+                choices: [
+                    {
+                        name: "Analyze — scan local configs, generate migration plan (YAML)",
+                        value: "analyze",
+                    },
+                    {
+                        name: "Execute — run a migration plan against Appwrite server",
+                        value: "execute",
+                    },
+                    { name: "Back", value: "back" },
+                ],
+            },
+        ]);
+        if (phase === "back")
+            return;
+        if (phase === "analyze") {
+            await migrateCommands.analyzePhase(cli);
+        }
+        else {
+            await migrateCommands.executePhase(cli);
+        }
+    },
+    async analyzePhase(cli) {
+        const controller = cli.controller;
+        if (!controller?.config) {
+            MessageFormatter.error("No configuration loaded. Make sure you have a valid .appwrite config.", undefined, { prefix: "Analyze" });
+            return;
+        }
+        const config = controller.config;
+        const collections = [
+            ...(config.collections || []),
+            ...(config.tables || []),
+        ];
+        if (collections.length === 0) {
+            MessageFormatter.warning("No collections/tables found in local config. Nothing to analyze.", { prefix: "Analyze" });
+            return;
+        }
+        // Prompt for output path
+        const { outputPath } = await inquirer.prompt([
+            {
+                type: "input",
+                name: "outputPath",
+                message: "Output path for migration plan:",
+                default: path.join(process.cwd(), "migrate-strings-plan.yaml"),
+            },
+        ]);
+        const options = { outputPath };
+        try {
+            analyzeStringAttributes(config, options);
+            MessageFormatter.success("Analysis complete. Review the YAML plan, edit targetType/action as needed, then run Execute.", { prefix: "Analyze" });
+        }
+        catch (err) {
+            MessageFormatter.error(`Analysis failed: ${err.message}`, undefined, { prefix: "Analyze" });
+        }
+    },
+    async executePhase(cli) {
+        const controller = cli.controller;
+        if (!controller?.adapter) {
+            MessageFormatter.error("No database adapter available. Ensure a server connection is established.", undefined, { prefix: "Execute" });
+            return;
+        }
+        // Prompt for plan path
+        const { planPath } = await inquirer.prompt([
+            {
+                type: "input",
+                name: "planPath",
+                message: "Path to migration plan YAML:",
+                default: path.join(process.cwd(), "migrate-strings-plan.yaml"),
+            },
+        ]);
+        const { keepBackups } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "keepBackups",
+                message: "Keep backup attributes after migration? (safer, uses more attribute slots)",
+                default: true,
+            },
+        ]);
+        const { dryRun } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "dryRun",
+                message: "Dry run? (no actual changes)",
+                default: false,
+            },
+        ]);
+        const options = {
+            planPath,
+            keepBackups,
+            dryRun,
+        };
+        try {
+            const results = await executeMigrationPlan(controller.adapter, options);
+            if (results.failed > 0) {
+                MessageFormatter.warning(`Migration completed with ${results.failed} failure(s). Check checkpoint file to resume.`, { prefix: "Execute" });
+            }
+            else {
+                MessageFormatter.success("Migration completed successfully.", {
+                    prefix: "Execute",
+                });
+            }
+        }
+        catch (err) {
+            MessageFormatter.error(`Execution failed: ${err.message}`, undefined, { prefix: "Execute" });
+        }
+    },
+};

package/dist/collections/attributes.js

@@ -437,6 +437,39 @@ const createLegacyAttribute = async (db, dbId, collectionId, attribute) => {
                 ? attribute.xdefault
                 : undefined, attribute.array || false);
             break;
+        case "varchar":
+            await db.createVarcharAttribute(dbId, collectionId, attribute.key, attribute.size || 255, attribute.required || false, attribute.xdefault !== undefined && !attribute.required
+                ? attribute.xdefault
+                : undefined, attribute.array || false, attribute.encrypt);
+            break;
+        case "text":
+        case "mediumtext":
+        case "longtext": {
+            const createFn = attribute.type === "text"
+                ? db.createTextAttribute.bind(db)
+                : attribute.type === "mediumtext"
+                    ? db.createMediumtextAttribute.bind(db)
+                    : db.createLongtextAttribute.bind(db);
+            await createFn(dbId, collectionId, attribute.key, attribute.required || false, attribute.xdefault !== undefined && !attribute.required
+                ? attribute.xdefault
+                : undefined, attribute.array || false, attribute.encrypt);
+            break;
+        }
+        case "point":
+            await db.createPointAttribute(dbId, collectionId, attribute.key, attribute.required || false, attribute.xdefault !== undefined && !attribute.required
+                ? attribute.xdefault
+                : undefined);
+            break;
+        case "line":
+            await db.createLineAttribute(dbId, collectionId, attribute.key, attribute.required || false, attribute.xdefault !== undefined && !attribute.required
+                ? attribute.xdefault
+                : undefined);
+            break;
+        case "polygon":
+            await db.createPolygonAttribute(dbId, collectionId, attribute.key, attribute.required || false, attribute.xdefault !== undefined && !attribute.required
+                ? attribute.xdefault
+                : undefined);
+            break;
         case "relationship":
             await db.createRelationshipAttribute(dbId, collectionId, attribute.relatedCollection, attribute.relationType, attribute.twoWay, attribute.key, attribute.twoWayKey, attribute.onDelete);
             break;
@@ -446,6 +479,10 @@ const createLegacyAttribute = async (db, dbId, collectionId, attribute) => {
                 type: attribute.type,
                 supportedTypes: [
                     "string",
+                    "varchar",
+                    "text",
+                    "mediumtext",
+                    "longtext",
                     "integer",
                     "double",
                     "float",
@@ -455,6 +492,9 @@ const createLegacyAttribute = async (db, dbId, collectionId, attribute) => {
                     "ip",
                     "url",
                     "enum",
+                    "point",
+                    "line",
+                    "polygon",
                     "relationship",
                 ],
                 operation: "createLegacyAttribute",
@@ -526,6 +566,39 @@ const updateLegacyAttribute = async (db, dbId, collectionId, attribute) => {
                 ? attribute.xdefault
                 : null);
             break;
+        case "varchar":
+            await db.updateVarcharAttribute(dbId, collectionId, attribute.key, attribute.required || false, !attribute.required && attribute.xdefault !== undefined
+                ? attribute.xdefault
+                : null, attribute.size);
+            break;
+        case "text":
+        case "mediumtext":
+        case "longtext": {
+            const updateFn = attribute.type === "text"
+                ? db.updateTextAttribute.bind(db)
+                : attribute.type === "mediumtext"
+                    ? db.updateMediumtextAttribute.bind(db)
+                    : db.updateLongtextAttribute.bind(db);
+            await updateFn(dbId, collectionId, attribute.key, attribute.required || false, !attribute.required && attribute.xdefault !== undefined
+                ? attribute.xdefault
+                : null);
+            break;
+        }
+        case "point":
+            await db.updatePointAttribute(dbId, collectionId, attribute.key, attribute.required || false, !attribute.required && attribute.xdefault !== undefined
+                ? attribute.xdefault
+                : null);
+            break;
+        case "line":
+            await db.updateLineAttribute(dbId, collectionId, attribute.key, attribute.required || false, !attribute.required && attribute.xdefault !== undefined
+                ? attribute.xdefault
+                : null);
+            break;
+        case "polygon":
+            await db.updatePolygonAttribute(dbId, collectionId, attribute.key, attribute.required || false, !attribute.required && attribute.xdefault !== undefined
+                ? attribute.xdefault
+                : null);
+            break;
         case "relationship":
             await db.updateRelationshipAttribute(dbId, collectionId, attribute.key, attribute.onDelete);
             break;
@@ -679,12 +752,22 @@ const getComparableFields = (type) => {
     switch (type) {
         case "string":
             return [...baseFields, "size", "encrypt"];
+        case "varchar":
+            return [...baseFields, "size", "encrypt"];
+        case "text":
+        case "mediumtext":
+        case "longtext":
+            return [...baseFields, "encrypt"];
         case "integer":
         case "double":
         case "float":
             return [...baseFields, "min", "max"];
         case "enum":
             return [...baseFields, "elements"];
+        case "point":
+        case "line":
+        case "polygon":
+            return baseFields;
         case "relationship":
             return [
                 ...baseFields,

package/dist/collections/indexes.js

@@ -1,5 +1,5 @@
 import { indexSchema } from "@njdamstra/appwrite-utils";
-import { Databases, IndexType, Query } from "node-appwrite";
+import { Databases, IndexType, OrderBy, Query } from "node-appwrite";
 import { delay, tryAwaitWithRetry, calculateExponentialBackoff, isLegacyDatabases, MessageFormatter } from "@njdamstra/appwrite-utils-helpers";
 // System attributes that are always available for indexing in Appwrite
 const SYSTEM_ATTRIBUTES = ['$id', '$createdAt', '$updatedAt', '$permissions'];

package/dist/collections/tableOperations.js

@@ -4,6 +4,10 @@ const EXTREME_BOUND = new Decimal('1e12');
 // Property configuration for different column types
 const MUTABLE_PROPERTIES = {
     string: ["required", "default", "size", "array"],
+    varchar: ["required", "default", "size", "array"],
+    text: ["required", "default", "array"],
+    mediumtext: ["required", "default", "array"],
+    longtext: ["required", "default", "array"],
     integer: ["required", "default", "min", "max", "array"],
     float: ["required", "default", "min", "max", "array"],
     double: ["required", "default", "min", "max", "array"],
@@ -13,10 +17,17 @@ const MUTABLE_PROPERTIES = {
     ip: ["required", "default", "array"],
     url: ["required", "default", "array"],
     enum: ["required", "default", "elements", "array"],
+    point: ["required", "default"],
+    line: ["required", "default"],
+    polygon: ["required", "default"],
     relationship: ["required", "default"],
 };
 const IMMUTABLE_PROPERTIES = {
     string: ["encrypt", "key"],
+    varchar: ["encrypt", "key"],
+    text: ["encrypt", "key"],
+    mediumtext: ["encrypt", "key"],
+    longtext: ["encrypt", "key"],
     integer: ["encrypt", "key"],
     float: ["encrypt", "key"],
     double: ["encrypt", "key"],
@@ -26,10 +37,17 @@ const IMMUTABLE_PROPERTIES = {
     ip: ["key"],
     url: ["key"],
     enum: ["key"],
+    point: ["key"],
+    line: ["key"],
+    polygon: ["key"],
     relationship: ["key", "relatedCollection", "relationType", "twoWay", "twoWayKey", "onDelete"],
 };
 const TYPE_CHANGE_REQUIRES_RECREATE = [
     "string",
+    "varchar",
+    "text",
+    "mediumtext",
+    "longtext",
     "integer",
     "float",
     "double",
@@ -39,6 +57,9 @@ const TYPE_CHANGE_REQUIRES_RECREATE = [
     "ip",
     "url",
     "enum",
+    "point",
+    "line",
+    "polygon",
     "relationship",
 ];
 function normDefault(val) {
@@ -64,6 +85,13 @@ export function normalizeAttributeToComparable(attr) {
         base.size = attr.size ?? 255;
         base.encrypt = !!(attr.encrypt);
     }
+    if (t === 'varchar') {
+        base.size = attr.size ?? 255;
+        base.encrypt = !!(attr.encrypt);
+    }
+    if (t === 'text' || t === 'mediumtext' || t === 'longtext') {
+        base.encrypt = !!(attr.encrypt);
+    }
     if (t === 'integer' || t === 'float' || t === 'double') {
         const min = toNumber(attr.min);
         const max = toNumber(attr.max);
@@ -108,6 +136,13 @@ export function normalizeColumnToComparable(col) {
         base.size = typeof col?.size === 'number' ? col.size : undefined;
         base.encrypt = !!col?.encrypt;
     }
+    if (t === 'varchar') {
+        base.size = typeof col?.size === 'number' ? col.size : undefined;
+        base.encrypt = !!col?.encrypt;
+    }
+    if (t === 'text' || t === 'mediumtext' || t === 'longtext') {
+        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;

package/dist/interactiveCLI.js

@@ -22,6 +22,7 @@ import { storageCommands } from "./cli/commands/storageCommands.js";
 import { transferCommands } from "./cli/commands/transferCommands.js";
 import { schemaCommands } from "./cli/commands/schemaCommands.js";
 import { importFileCommands } from "./cli/commands/importFileCommands.js";
+import { migrateCommands } from "./cli/commands/migrateCommands.js";
 var CHOICES;
 (function (CHOICES) {
     CHOICES["MIGRATE_CONFIG"] = "\uD83D\uDD04 Migrate TypeScript config to YAML (.appwrite structure)";
@@ -47,6 +48,7 @@ var CHOICES;
     CHOICES["RELOAD_CONFIG"] = "\uD83D\uDD04 Reload configuration files";
     CHOICES["UPDATE_FUNCTION_SPEC"] = "\u2699\uFE0F Update function specifications";
     CHOICES["MANAGE_BUCKETS"] = "\uD83E\uDEA3 Manage storage buckets";
+    CHOICES["MIGRATE_STRINGS"] = "\uD83D\uDD04 Migrate string attributes to varchar/text types";
     CHOICES["EXIT"] = "\uD83D\uDC4B Exit";
 })(CHOICES || (CHOICES = {}));
 export class InteractiveCLI {
@@ -60,7 +62,7 @@ export class InteractiveCLI {
         this.options = options;
     }
     async run() {
-        MessageFormatter.banner("Appwrite Utils CLI", "Welcome to Appwrite Utils CLI Tool by Zach Handley");
+        MessageFormatter.banner("Appwrite Utils CLI", "Welcome to Appwrite Utils CLI Tool");
         MessageFormatter.info("For more information, visit https://github.com/njdamstra/AppwriteUtils");
         // Detect configuration type
         try {
@@ -165,6 +167,10 @@ export class InteractiveCLI {
                 case CHOICES.MANAGE_BUCKETS:
                     await this.manageBuckets();
                     break;
+                case CHOICES.MIGRATE_STRINGS:
+                    await this.initControllerIfNeeded();
+                    await migrateCommands.migrateStrings(this);
+                    break;
                 case CHOICES.EXIT:
                     MessageFormatter.success("Goodbye!");
                     process.exit(0);

package/dist/main.js

@@ -454,6 +454,32 @@ const argv = yargs(hideBin(process.argv))
     alias: ["target-table"],
     type: "string",
     description: "Target table ID for --importFile (prompted if omitted)",
+})
+    .option("migrateStringsAnalyze", {
+    alias: ["migrate-strings-analyze"],
+    type: "boolean",
+    description: "Analyze local configs and generate a string-to-varchar/text migration plan (YAML)",
+})
+    .option("migrateStringsExecute", {
+    alias: ["migrate-strings-execute"],
+    type: "string",
+    description: "Execute a string migration plan from the given YAML path",
+})
+    .option("migrateStringsOutput", {
+    alias: ["migrate-strings-output"],
+    type: "string",
+    description: "Output path for the migration plan (default: ./migrate-strings-plan.yaml)",
+})
+    .option("migrateStringsKeepBackups", {
+    alias: ["migrate-strings-keep-backups"],
+    type: "boolean",
+    default: true,
+    description: "Keep backup attributes after migration (default: true)",
+})
+    .option("migrateStringsDryRun", {
+    alias: ["migrate-strings-dry-run"],
+    type: "boolean",
+    description: "Dry run — show what would happen without making changes",
 })
     .parse();
 async function main() {
@@ -618,6 +644,36 @@ async function main() {
             }
             return;
         }
+        // String attribute migration (analyze or execute)
+        if (argv.migrateStringsAnalyze || argv.migrateStringsExecute) {
+            const { analyzeStringAttributes, executeMigrationPlan } = await import("./migrations/migrateStrings.js");
+            if (argv.migrateStringsAnalyze) {
+                if (!controller.config) {
+                    MessageFormatter.error("No Appwrite configuration found", undefined, {
+                        prefix: "Migration",
+                    });
+                    return;
+                }
+                analyzeStringAttributes(controller.config, {
+                    outputPath: argv.migrateStringsOutput,
+                });
+            }
+            else if (argv.migrateStringsExecute) {
+                if (!controller.adapter) {
+                    MessageFormatter.error("No database adapter available. Ensure config has valid credentials.", undefined, { prefix: "Migration" });
+                    return;
+                }
+                const results = await executeMigrationPlan(controller.adapter, {
+                    planPath: argv.migrateStringsExecute,
+                    keepBackups: argv.migrateStringsKeepBackups ?? true,
+                    dryRun: argv.migrateStringsDryRun ?? false,
+                });
+                if (results.failed > 0) {
+                    process.exit(1);
+                }
+            }
+            return;
+        }
         // List backups if requested
         if (parsedArgv.listBackups) {
             const { AdapterFactory } = await import("@njdamstra/appwrite-utils-helpers");

package/dist/migrations/appwriteToX.d.ts

@@ -21,6 +21,63 @@ export declare class AppwriteToX {
         error?: string | undefined;
         xdefault?: string | null | undefined;
         encrypt?: boolean | undefined;
+    } | {
+        key: string;
+        required: boolean;
+        type: "varchar";
+        size: number;
+        array?: boolean | undefined;
+        format?: string | undefined;
+        status?: string | undefined;
+        attributes?: string[] | undefined;
+        orders?: string[] | undefined;
+        $createdAt?: string | undefined;
+        $updatedAt?: string | undefined;
+        error?: string | undefined;
+        xdefault?: string | null | undefined;
+        encrypt?: boolean | undefined;
+    } | {
+        key: string;
+        required: boolean;
+        type: "text";
+        array?: boolean | undefined;
+        format?: string | undefined;
+        status?: string | undefined;
+        attributes?: string[] | undefined;
+        orders?: string[] | undefined;
+        $createdAt?: string | undefined;
+        $updatedAt?: string | undefined;
+        error?: string | undefined;
+        xdefault?: string | null | undefined;
+        encrypt?: boolean | undefined;
+    } | {
+        key: string;
+        required: boolean;
+        type: "mediumtext";
+        array?: boolean | undefined;
+        format?: string | undefined;
+        status?: string | undefined;
+        attributes?: string[] | undefined;
+        orders?: string[] | undefined;
+        $createdAt?: string | undefined;
+        $updatedAt?: string | undefined;
+        error?: string | undefined;
+        xdefault?: string | null | undefined;
+        encrypt?: boolean | undefined;
+    } | {
+        key: string;
+        required: boolean;
+        type: "longtext";
+        array?: boolean | undefined;
+        format?: string | undefined;
+        status?: string | undefined;
+        attributes?: string[] | undefined;
+        orders?: string[] | undefined;
+        $createdAt?: string | undefined;
+        $updatedAt?: string | undefined;
+        error?: string | undefined;
+        xdefault?: string | null | undefined;
+        encrypt?: boolean | undefined;
     } | {
         key: string;
         required: boolean;
@@ -145,6 +202,45 @@ export declare class AppwriteToX {
         $updatedAt?: string | undefined;
         error?: string | undefined;
         xdefault?: string | null | undefined;
+    } | {
+        key: string;
+        required: boolean;
+        type: "point";
+        array?: boolean | undefined;
+        format?: string | undefined;
+        status?: string | undefined;
+        attributes?: string[] | undefined;
+        orders?: string[] | undefined;
+        $createdAt?: string | undefined;
+        $updatedAt?: string | undefined;
+        error?: string | undefined;
+        xdefault?: number[] | null | undefined;
+    } | {
+        key: string;
+        required: boolean;
+        type: "line";
+        array?: boolean | undefined;
+        format?: string | undefined;
+        status?: string | undefined;
+        attributes?: string[] | undefined;
+        orders?: string[] | undefined;
+        $createdAt?: string | undefined;
+        $updatedAt?: string | undefined;
+        error?: string | undefined;
+        xdefault?: number[][] | null | undefined;
+    } | {
+        key: string;
+        required: boolean;
+        type: "polygon";
+        array?: boolean | undefined;
+        format?: string | undefined;
+        status?: string | undefined;
+        attributes?: string[] | undefined;
+        orders?: string[] | undefined;
+        $createdAt?: string | undefined;
+        $updatedAt?: string | undefined;
+        error?: string | undefined;
+        xdefault?: number[][][] | null | undefined;
     } | {
         key: string;
         required: boolean;