@njdamstra/appwrite-utils-cli 1.10.0 → 1.11.0

package/dist/migrations/migrateStringsTypes.d.ts

@@ -0,0 +1,195 @@
+import { z } from "zod";
+export declare const MigrationTargetType: z.ZodEnum<{
+    varchar: "varchar";
+    text: "text";
+    mediumtext: "mediumtext";
+    longtext: "longtext";
+}>;
+export type MigrationTargetType = z.infer<typeof MigrationTargetType>;
+export declare const MigrationAction: z.ZodEnum<{
+    skip: "skip";
+    migrate: "migrate";
+}>;
+export type MigrationAction = z.infer<typeof MigrationAction>;
+export declare const MigrationPlanEntrySchema: z.ZodObject<{
+    databaseId: z.ZodString;
+    databaseName: z.ZodString;
+    collectionId: z.ZodString;
+    collectionName: z.ZodString;
+    attributeKey: z.ZodString;
+    currentType: z.ZodDefault<z.ZodString>;
+    currentSize: z.ZodNumber;
+    isRequired: z.ZodDefault<z.ZodBoolean>;
+    isArray: z.ZodDefault<z.ZodBoolean>;
+    isEncrypted: z.ZodDefault<z.ZodBoolean>;
+    hasDefault: z.ZodDefault<z.ZodBoolean>;
+    defaultValue: z.ZodOptional<z.ZodAny>;
+    suggestedType: z.ZodEnum<{
+        varchar: "varchar";
+        text: "text";
+        mediumtext: "mediumtext";
+        longtext: "longtext";
+    }>;
+    targetType: z.ZodEnum<{
+        varchar: "varchar";
+        text: "text";
+        mediumtext: "mediumtext";
+        longtext: "longtext";
+    }>;
+    targetSize: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodEnum<{
+        skip: "skip";
+        migrate: "migrate";
+    }>;
+    skipReason: z.ZodOptional<z.ZodString>;
+    indexesAffected: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type MigrationPlanEntry = z.infer<typeof MigrationPlanEntrySchema>;
+export declare const MigrationPlanSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodNumber>;
+    generatedAt: z.ZodString;
+    appwriteEndpoint: z.ZodOptional<z.ZodString>;
+    appwriteProject: z.ZodOptional<z.ZodString>;
+    summary: z.ZodObject<{
+        totalStringAttributes: z.ZodNumber;
+        toMigrate: z.ZodNumber;
+        toSkip: z.ZodNumber;
+        databaseCount: z.ZodNumber;
+        collectionCount: z.ZodNumber;
+    }, z.core.$strip>;
+    entries: z.ZodArray<z.ZodObject<{
+        databaseId: z.ZodString;
+        databaseName: z.ZodString;
+        collectionId: z.ZodString;
+        collectionName: z.ZodString;
+        attributeKey: z.ZodString;
+        currentType: z.ZodDefault<z.ZodString>;
+        currentSize: z.ZodNumber;
+        isRequired: z.ZodDefault<z.ZodBoolean>;
+        isArray: z.ZodDefault<z.ZodBoolean>;
+        isEncrypted: z.ZodDefault<z.ZodBoolean>;
+        hasDefault: z.ZodDefault<z.ZodBoolean>;
+        defaultValue: z.ZodOptional<z.ZodAny>;
+        suggestedType: z.ZodEnum<{
+            varchar: "varchar";
+            text: "text";
+            mediumtext: "mediumtext";
+            longtext: "longtext";
+        }>;
+        targetType: z.ZodEnum<{
+            varchar: "varchar";
+            text: "text";
+            mediumtext: "mediumtext";
+            longtext: "longtext";
+        }>;
+        targetSize: z.ZodOptional<z.ZodNumber>;
+        action: z.ZodEnum<{
+            skip: "skip";
+            migrate: "migrate";
+        }>;
+        skipReason: z.ZodOptional<z.ZodString>;
+        indexesAffected: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MigrationPlan = z.infer<typeof MigrationPlanSchema>;
+export declare const CheckpointPhase: z.ZodEnum<{
+    pending: "pending";
+    completed: "completed";
+    failed: "failed";
+    backup_created: "backup_created";
+    data_copied_to_backup: "data_copied_to_backup";
+    data_verified_backup: "data_verified_backup";
+    original_deleted: "original_deleted";
+    new_attr_created: "new_attr_created";
+    data_copied_back: "data_copied_back";
+    data_verified_final: "data_verified_final";
+    backup_deleted: "backup_deleted";
+}>;
+export type CheckpointPhase = z.infer<typeof CheckpointPhase>;
+export declare const CheckpointEntrySchema: z.ZodObject<{
+    databaseId: z.ZodString;
+    collectionId: z.ZodString;
+    attributeKey: z.ZodString;
+    backupKey: z.ZodString;
+    phase: z.ZodEnum<{
+        pending: "pending";
+        completed: "completed";
+        failed: "failed";
+        backup_created: "backup_created";
+        data_copied_to_backup: "data_copied_to_backup";
+        data_verified_backup: "data_verified_backup";
+        original_deleted: "original_deleted";
+        new_attr_created: "new_attr_created";
+        data_copied_back: "data_copied_back";
+        data_verified_final: "data_verified_final";
+        backup_deleted: "backup_deleted";
+    }>;
+    targetType: z.ZodEnum<{
+        varchar: "varchar";
+        text: "text";
+        mediumtext: "mediumtext";
+        longtext: "longtext";
+    }>;
+    targetSize: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodString>;
+    storedIndexes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodString;
+        attributes: z.ZodArray<z.ZodString>;
+        orders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CheckpointEntry = z.infer<typeof CheckpointEntrySchema>;
+export declare const MigrationCheckpointSchema: z.ZodObject<{
+    planFile: z.ZodString;
+    startedAt: z.ZodString;
+    lastUpdatedAt: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        databaseId: z.ZodString;
+        collectionId: z.ZodString;
+        attributeKey: z.ZodString;
+        backupKey: z.ZodString;
+        phase: z.ZodEnum<{
+            pending: "pending";
+            completed: "completed";
+            failed: "failed";
+            backup_created: "backup_created";
+            data_copied_to_backup: "data_copied_to_backup";
+            data_verified_backup: "data_verified_backup";
+            original_deleted: "original_deleted";
+            new_attr_created: "new_attr_created";
+            data_copied_back: "data_copied_back";
+            data_verified_final: "data_verified_final";
+            backup_deleted: "backup_deleted";
+        }>;
+        targetType: z.ZodEnum<{
+            varchar: "varchar";
+            text: "text";
+            mediumtext: "mediumtext";
+            longtext: "longtext";
+        }>;
+        targetSize: z.ZodOptional<z.ZodNumber>;
+        error: z.ZodOptional<z.ZodString>;
+        storedIndexes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            type: z.ZodString;
+            attributes: z.ZodArray<z.ZodString>;
+            orders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MigrationCheckpoint = z.infer<typeof MigrationCheckpointSchema>;
+export interface AnalyzeOptions {
+    outputPath?: string;
+    verbose?: boolean;
+}
+export interface ExecuteOptions {
+    planPath: string;
+    keepBackups?: boolean;
+    dryRun?: boolean;
+    batchSize?: number;
+    batchDelayMs?: number;
+    checkpointPath?: string;
+}
+export declare function suggestTargetType(size: number, hasIndex: boolean): MigrationTargetType;
+export declare function generateBackupKey(originalKey: string): string;

package/dist/migrations/migrateStringsTypes.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+// ── Target types for string attribute migration ──
+export const MigrationTargetType = z.enum([
+    "varchar",
+    "text",
+    "mediumtext",
+    "longtext",
+]);
+export const MigrationAction = z.enum(["migrate", "skip"]);
+// ── Plan entry: one per attribute to migrate ──
+export const MigrationPlanEntrySchema = z.object({
+    databaseId: z.string(),
+    databaseName: z.string(),
+    collectionId: z.string(),
+    collectionName: z.string(),
+    attributeKey: z.string(),
+    currentType: z.string().default("string"),
+    currentSize: z.number(),
+    isRequired: z.boolean().default(false),
+    isArray: z.boolean().default(false),
+    isEncrypted: z.boolean().default(false),
+    hasDefault: z.boolean().default(false),
+    defaultValue: z.any().optional(),
+    suggestedType: MigrationTargetType,
+    targetType: MigrationTargetType,
+    targetSize: z.number().optional(), // varchar only
+    action: MigrationAction,
+    skipReason: z.string().optional(),
+    indexesAffected: z.array(z.string()).default([]),
+});
+// ── Plan: full migration plan (user-editable YAML) ──
+export const MigrationPlanSchema = z.object({
+    version: z.number().default(1),
+    generatedAt: z.string(),
+    appwriteEndpoint: z.string().optional(),
+    appwriteProject: z.string().optional(),
+    summary: z.object({
+        totalStringAttributes: z.number(),
+        toMigrate: z.number(),
+        toSkip: z.number(),
+        databaseCount: z.number(),
+        collectionCount: z.number(),
+    }),
+    entries: z.array(MigrationPlanEntrySchema),
+});
+// ── Checkpoint: tracks progress during execution ──
+export const CheckpointPhase = z.enum([
+    "pending",
+    "backup_created",
+    "data_copied_to_backup",
+    "data_verified_backup",
+    "original_deleted",
+    "new_attr_created",
+    "data_copied_back",
+    "data_verified_final",
+    "backup_deleted",
+    "completed",
+    "failed",
+]);
+export const CheckpointEntrySchema = z.object({
+    databaseId: z.string(),
+    collectionId: z.string(),
+    attributeKey: z.string(),
+    backupKey: z.string(),
+    phase: CheckpointPhase,
+    targetType: MigrationTargetType,
+    targetSize: z.number().optional(),
+    error: z.string().optional(),
+    // Store index definitions for recreation after attribute delete
+    storedIndexes: z
+        .array(z.object({
+        key: z.string(),
+        type: z.string(),
+        attributes: z.array(z.string()),
+        orders: z.array(z.string()).optional(),
+    }))
+        .default([]),
+});
+export const MigrationCheckpointSchema = z.object({
+    planFile: z.string(),
+    startedAt: z.string(),
+    lastUpdatedAt: z.string(),
+    entries: z.array(CheckpointEntrySchema),
+});
+// ── Helper: suggest target type from size + index presence ──
+export function suggestTargetType(size, hasIndex) {
+    // varchar supports up to 16,383 bytes and allows full indexing
+    if (size <= 768)
+        return "varchar";
+    if (hasIndex)
+        return "varchar"; // indexes require varchar
+    if (size <= 16_383)
+        return "text";
+    if (size <= 4_000_000)
+        return "mediumtext";
+    return "longtext";
+}
+// ── Helper: generate backup key with length limits ──
+const MAX_KEY_LENGTH = 36;
+const BACKUP_PREFIX = "_mig_";
+export function generateBackupKey(originalKey) {
+    const candidate = `${BACKUP_PREFIX}${originalKey}`;
+    if (candidate.length <= MAX_KEY_LENGTH) {
+        return candidate;
+    }
+    // Truncate + 4-char hash for uniqueness
+    const hash = simpleHash(originalKey);
+    const maxOrigLen = MAX_KEY_LENGTH - BACKUP_PREFIX.length - 1 - 4; // _mig_ + _ + hash4
+    return `_m_${originalKey.slice(0, maxOrigLen)}_${hash}`;
+}
+function simpleHash(str) {
+    let h = 0;
+    for (let i = 0; i < str.length; i++) {
+        h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+    }
+    return Math.abs(h).toString(36).slice(0, 4).padStart(4, "0");
+}