appwrite-utils-cli 0.0.1

package/dist/migrations/backup.js

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import { attributeSchema, parseAttribute, CollectionCreateSchema, } from "./schema.js";
+export const BackupSchema = z.object({
+    $id: z.string(),
+    $createdAt: z.string(),
+    $updatedAt: z.string(),
+    database: z.string(),
+    collections: z.array(z.string()),
+    documents: z
+        .array(z.object({
+        collectionId: z.string(),
+        data: z.string(),
+    }))
+        .default([]),
+});
+export const BackupCreateSchema = BackupSchema.omit({
+    $id: true,
+    $createdAt: true,
+    $updatedAt: true,
+});
+export const BatchSchema = z.object({
+    $id: z.string(),
+    $createdAt: z.string(),
+    $updatedAt: z.string(),
+    data: z.string().describe("The serialized data for this batch"),
+    processed: z
+        .boolean()
+        .default(false)
+        .describe("Whether the batch has been processed"),
+});
+export const BatchCreateSchema = BatchSchema.omit({
+    $id: true,
+    $createdAt: true,
+    $updatedAt: true,
+});
+export const OperationSchema = z.object({
+    $id: z.string(),
+    $createdAt: z.string(),
+    $updatedAt: z.string(),
+    operationType: z.string(),
+    collectionId: z.string(),
+    data: z.any(),
+    batches: z.array(z.string()).default([]).optional(),
+    progress: z.number(),
+    total: z.number(),
+    error: z.string(),
+    status: z.enum(["pending", "in_progress", "completed", "error"]),
+});
+export const OperationCreateSchema = OperationSchema.omit({
+    $id: true,
+    $createdAt: true,
+    $updatedAt: true,
+});
+export const getMigrationCollectionSchemas = () => {
+    const currentOperationsAttributes = [
+        parseAttribute({
+            key: "operationType",
+            type: "string",
+            error: "Invalid Operation Type",
+            size: 50,
+            required: true,
+            array: false,
+            xdefault: null,
+        }),
+        attributeSchema.parse({
+            key: "collectionId",
+            type: "string",
+            error: "Invalid Collection Id",
+            size: 50,
+            array: false,
+            xdefault: null,
+        }),
+        attributeSchema.parse({
+            key: "batches",
+            type: "string",
+            error: "Invalid Batches",
+            size: 1073741824,
+            array: true,
+        }),
+        attributeSchema.parse({
+            key: "data",
+            type: "string",
+            error: "Invalid Data",
+            size: 1073741824,
+        }),
+        attributeSchema.parse({
+            key: "progress",
+            type: "integer",
+            error: "Invalid Progress",
+            required: true,
+            array: false,
+        }),
+        attributeSchema.parse({
+            key: "total",
+            type: "integer",
+            error: "Invalid Total",
+            required: true,
+            array: false,
+        }),
+        attributeSchema.parse({
+            key: "error",
+            type: "string",
+            error: "Operation Error",
+            required: false,
+            array: false,
+        }),
+        attributeSchema.parse({
+            key: "status",
+            type: "enum",
+            elements: ["pending", "in_progress", "completed", "error"],
+            error: "Invalid Status",
+            array: false,
+            xdefault: "pending",
+        }),
+    ];
+    const currentOperationsConfig = CollectionCreateSchema.parse({
+        name: "CurrentOperations",
+        enabled: true,
+        documentSecurity: false,
+        attributes: [],
+        indexes: [],
+    });
+    const batchesAttributes = [
+        attributeSchema.parse({
+            key: "data",
+            type: "string",
+            size: 1073741824,
+            error: "Invalid Data",
+            required: true,
+            array: false,
+        }),
+        attributeSchema.parse({
+            key: "processed",
+            type: "boolean",
+            error: "Invalid Processed",
+            required: true,
+            array: false,
+            xdefault: false,
+        }),
+    ];
+    const batchesConfig = CollectionCreateSchema.parse({
+        name: "Batches",
+        enabled: true,
+        documentSecurity: false,
+        attributes: [],
+        indexes: [],
+    });
+    const toReturn = {
+        CurrentOperations: {
+            collection: currentOperationsConfig,
+            attributes: currentOperationsAttributes,
+        },
+        Batches: {
+            collection: batchesConfig,
+            attributes: batchesAttributes,
+        },
+    };
+    return toReturn;
+};

package/dist/migrations/collections.d.ts

@@ -0,0 +1,16 @@
+import { Databases, type Models } from "node-appwrite";
+import type { AppwriteConfig, CollectionCreate } from "./schema.js";
+export declare const documentExists: (db: Databases, dbId: string, targetCollectionId: string, toCreateObject: any) => Promise<Models.Document | null>;
+export declare const checkForCollection: (db: Databases, dbId: string, collection: Partial<CollectionCreate>) => Promise<Models.Collection | null>;
+export declare const fetchAndCacheCollectionByName: (db: Databases, dbId: string, collectionName: string) => Promise<Models.Collection | undefined>;
+export declare const wipeDatabase: (database: Databases, databaseId: string) => Promise<{
+    collectionId: string;
+    collectionName: string;
+}[]>;
+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;
+}[]) => 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/migrations/collections.js

@@ -0,0 +1,207 @@
+import { Databases, ID, Permission, Query } from "node-appwrite";
+import { nameToIdMapping, processQueue } from "./queue.js";
+import { createUpdateCollectionAttributes } from "./attributes.js";
+import { createOrUpdateIndexes } from "./indexes.js";
+import { ensureDirectoryExistence, toCamelCase, toPascalCase, writeFileSync, } from "../utils/index.js";
+import _ from "lodash";
+import { SchemaGenerator } from "./schemaStrings.js";
+import path from "path";
+const { join } = _;
+export const documentExists = async (db, dbId, targetCollectionId, toCreateObject) => {
+    // Had to do this because kept running into issues with type checking arrays so, sorry 40ms
+    const collection = await db.getCollection(dbId, targetCollectionId);
+    const attributes = collection.attributes;
+    let arrayTypeAttributes = attributes
+        .filter((attribute) => attribute.array === true)
+        .map((attribute) => attribute.key);
+    // Function to check if a string is JSON
+    const isJsonString = (str) => {
+        try {
+            const json = JSON.parse(str);
+            return typeof json === "object" && json !== null; // Check if parsed JSON is an object or array
+        }
+        catch (e) {
+            return false;
+        }
+    };
+    // Validate and prepare query parameters
+    const validQueryParams = _.chain(toCreateObject)
+        .pickBy((value, key) => !arrayTypeAttributes.includes(key) &&
+        !key.startsWith("$") &&
+        !_.isNull(value) &&
+        !_.isUndefined(value) &&
+        !_.isEmpty(value) &&
+        !_.isObject(value) && // Keeps excluding objects
+        !_.isArray(value) && // Explicitly exclude arrays
+        !(_.isString(value) && isJsonString(value)) && // Exclude JSON strings
+        (_.isString(value) ? value.length < 4096 && value.length > 0 : true) // String length check
+    )
+        .mapValues((value, key) => _.isString(value) || _.isNumber(value) || _.isBoolean(value)
+        ? value
+        : null)
+        .omitBy(_.isNull) // Remove any null values that might have been added in mapValues
+        .toPairs()
+        .slice(0, 25) // Limit to 25 to adhere to query limit
+        .map(([key, value]) => Query.equal(key, value))
+        .value();
+    // Execute the query with the validated and prepared parameters
+    const result = await db.listDocuments(dbId, targetCollectionId, validQueryParams);
+    return result.documents[0] || null;
+};
+export const checkForCollection = async (db, dbId, collection) => {
+    try {
+        console.log(`Checking for collection with name: ${collection.name}`);
+        const response = await db.listCollections(dbId, [
+            Query.equal("name", collection.name),
+        ]);
+        if (response.collections.length > 0) {
+            console.log(`Collection found: ${response.collections[0].$id}`);
+            return { ...collection, ...response.collections[0] };
+        }
+        else {
+            console.log(`No collection found with name: ${collection.name}`);
+            return null;
+        }
+    }
+    catch (error) {
+        console.error(`Error checking for collection: ${error}`);
+        return null;
+    }
+};
+// Helper function to fetch and cache collection by name
+export const fetchAndCacheCollectionByName = async (db, dbId, collectionName) => {
+    if (nameToIdMapping.has(collectionName)) {
+        const collectionId = nameToIdMapping.get(collectionName);
+        console.log(`\tCollection found in cache: ${collectionId}`);
+        return await db.getCollection(dbId, collectionId);
+    }
+    else {
+        console.log(`\tFetching collection by name: ${collectionName}`);
+        const collectionsPulled = await db.listCollections(dbId, [
+            Query.equal("name", collectionName),
+        ]);
+        if (collectionsPulled.total > 0) {
+            const collection = collectionsPulled.collections[0];
+            console.log(`\tCollection found: ${collection.$id}`);
+            nameToIdMapping.set(collectionName, collection.$id);
+            return collection;
+        }
+        else {
+            console.log(`\tCollection not found by name: ${collectionName}`);
+            return undefined;
+        }
+    }
+};
+export const wipeDatabase = async (database, databaseId) => {
+    console.log(`Wiping database: ${databaseId}`);
+    const { collections: existingCollections } = await database.listCollections(databaseId);
+    let collectionsDeleted = [];
+    for (const { $id: collectionId, name: name } of existingCollections) {
+        console.log(`Deleting collection: ${collectionId}`);
+        collectionsDeleted.push({
+            collectionId: collectionId,
+            collectionName: name,
+        });
+        await database.deleteCollection(databaseId, collectionId);
+    }
+    return collectionsDeleted;
+};
+export const generateSchemas = async (config, appwriteFolderPath) => {
+    const schemaGenerator = new SchemaGenerator(config, appwriteFolderPath);
+    schemaGenerator.generateSchemas();
+};
+export const createOrUpdateCollections = async (database, databaseId, config, deletedCollections) => {
+    const configCollections = config.collections;
+    for (const { attributes, indexes, ...collection } of configCollections) {
+        let collectionsFound = await database.listCollections(databaseId, [
+            Query.equal("name", collection.name),
+        ]);
+        const permissions = [];
+        if (collection.$permissions.length > 0) {
+            for (const permission of collection.$permissions) {
+                switch (permission.permission) {
+                    case "read":
+                        permissions.push(Permission.read(permission.target));
+                        break;
+                    case "create":
+                        permissions.push(Permission.create(permission.target));
+                        break;
+                    case "update":
+                        permissions.push(Permission.update(permission.target));
+                        break;
+                    case "delete":
+                        permissions.push(Permission.delete(permission.target));
+                        break;
+                    case "write":
+                        permissions.push(Permission.write(permission.target));
+                        break;
+                    default:
+                        console.log(`Unknown permission: ${permission.permission}`);
+                        break;
+                }
+            }
+        }
+        let collectionToUse = collectionsFound.total > 0 ? collectionsFound.collections[0] : null;
+        if (!collectionToUse) {
+            console.log(`Creating collection: ${collection.name}`);
+            if (deletedCollections && deletedCollections.length > 0) {
+                const foundColl = deletedCollections.find((coll) => coll.collectionName.toLowerCase().trim().replace(" ", "") ===
+                    collection.name.toLowerCase().trim().replace(" ", ""));
+                if (foundColl) {
+                    const collectionId = foundColl.collectionId || ID.unique();
+                    console.log(`Processing collection: ${collection.name} with ID: ${collectionId}`);
+                    collectionToUse = await database.createCollection(databaseId, collectionId, collection.name, permissions, collection.documentSecurity, collection.enabled);
+                    nameToIdMapping.set(collection.name, collectionToUse.$id);
+                }
+                else {
+                    collectionToUse = await database.createCollection(databaseId, ID.unique(), collection.name, permissions, collection.documentSecurity, collection.enabled);
+                    nameToIdMapping.set(collection.name, collectionToUse.$id);
+                }
+            }
+            else {
+                collectionToUse = await database.createCollection(databaseId, ID.unique(), collection.name, permissions, collection.documentSecurity, collection.enabled);
+                nameToIdMapping.set(collection.name, collectionToUse.$id);
+            }
+        }
+        else {
+            console.log(`Collection ${collection.name} already exists.`);
+        }
+        console.log("Creating Attributes");
+        await createUpdateCollectionAttributes(database, databaseId, collectionToUse, attributes);
+        console.log("Creating Indexes");
+        await createOrUpdateIndexes(databaseId, database, collectionToUse.$id, indexes);
+    }
+    await processQueue(database, databaseId);
+};
+export const generateMockData = async (database, databaseId, configCollections) => {
+    for (const { collection, mockFunction } of configCollections) {
+        if (mockFunction) {
+            console.log(`Generating mock data for collection: ${collection.name}`);
+            const mockData = mockFunction();
+            for (const data of mockData) {
+                await database.createDocument(databaseId, collection.$id, ID.unique(), data);
+            }
+        }
+    }
+};
+export const fetchAllCollections = async (dbId, database) => {
+    console.log(`Fetching all collections for database ID: ${dbId}`);
+    let collections = [];
+    let moreCollections = true;
+    let lastCollectionId;
+    while (moreCollections) {
+        const queries = [Query.limit(500)];
+        if (lastCollectionId) {
+            queries.push(Query.cursorAfter(lastCollectionId));
+        }
+        const response = await database.listCollections(dbId, queries);
+        collections = collections.concat(response.collections);
+        moreCollections = response.collections.length === 500;
+        if (moreCollections) {
+            lastCollectionId =
+                response.collections[response.collections.length - 1].$id;
+        }
+    }
+    console.log(`Fetched a total of ${collections.length} collections.`);
+    return collections;
+};

package/dist/migrations/converters.d.ts

@@ -0,0 +1,179 @@
+export interface ConverterFunctions {
+    [key: string]: (value: any) => any;
+}
+export declare const converterFunctions: {
+    /**
+     * Converts any value to a string. Handles null and undefined explicitly.
+     * @param {any} value The value to convert.
+     * @return {string | null} The converted string or null if the value is null or undefined.
+     */
+    anyToString(value: any): string | null;
+    /**
+     * Converts any value to a number. Returns null for non-numeric values, null, or undefined.
+     * @param {any} value The value to convert.
+     * @return {number | null} The converted number or null.
+     */
+    anyToNumber(value: any): number | null;
+    /**
+     * Converts any value to a boolean. Specifically handles string representations.
+     * @param {any} value The value to convert.
+     * @return {boolean | null} The converted boolean or null if conversion is not possible.
+     */
+    anyToBoolean(value: any): boolean | null;
+    /**
+     * Converts any value to an array, attempting to split strings by a specified separator.
+     * @param {any} value The value to convert.
+     * @param {string | undefined} separator The separator to use when splitting strings.
+     * @return {any[]} The resulting array after conversion.
+     */
+    anyToAnyArray(value: any): any[];
+    /**
+     * Converts any value to an array of strings. If the input is already an array, returns it as is.
+     * Otherwise, if the input is a string, returns an array with the string as the only element.
+     * Otherwise, returns an empty array.
+     * @param {any} value The value to convert.
+     * @return {string[]} The resulting array after conversion.
+     */
+    anyToStringArray(value: any): string[];
+    /**
+     * A function that converts any type of value to an array of numbers.
+     *
+     * @param {any} value - the value to be converted
+     * @return {number[]} an array of numbers
+     */
+    anyToNumberArray(value: any): number[];
+    trim(value: string): string;
+    /**
+     * Removes the start and end quotes from a string.
+     * @param value The string to remove quotes from.
+     * @return The string with quotes removed.
+     **/
+    removeStartEndQuotes(value: string): string;
+    /**
+     * Tries to split a string by different separators and returns the split that has the most uniform segment lengths.
+     * This can be particularly useful for structured data like phone numbers.
+     * @param value The string to split.
+     * @return The split string array that has the most uniform segment lengths.
+     */
+    trySplitByDifferentSeparators(value: string): string[];
+    joinValues(values: any[]): any;
+    joinBySpace(values: any[]): any;
+    joinByComma(values: any[]): any;
+    joinByPipe(values: any[]): any;
+    joinBySemicolon(values: any[]): any;
+    joinByColon(values: any[]): any;
+    joinBySlash(values: any[]): any;
+    joinByHyphen(values: any[]): any;
+    splitByComma(value: string): any;
+    splitByPipe(value: string): any;
+    splitBySemicolon(value: string): any;
+    splitByColon(value: string): any;
+    splitBySlash(value: string): any;
+    splitByBackslash(value: string): any;
+    splitBySpace(value: string): any;
+    splitByDot(value: string): any;
+    splitByUnderscore(value: string): any;
+    splitByHyphen(value: string): any;
+    /**
+     * Takes the first element of an array and returns it.
+     * @param {any[]} value The array to take the first element from.
+     * @return {any} The first element of the array.
+     */
+    pickFirstElement(value: any[]): any;
+    /**
+     * Takes the last element of an array and returns it.
+     * @param {any[]} value The array to take the last element from.
+     * @return {any} The last element of the array.
+     */
+    pickLastElement(value: any[]): any;
+    /**
+     * Converts an object to a JSON string.
+     * @param {any} object The object to convert.
+     * @return {string} The JSON string representation of the object.
+     */
+    stringifyObject(object: any): string;
+    /**
+     * Converts a JSON string to an object.
+     * @param {string} jsonString The JSON string to convert.
+     * @return {any} The object representation of the JSON string.
+     */
+    parseObject(jsonString: string): any;
+    convertPhoneStringToUSInternational(value: string): string;
+    convertEmptyToNull(value: any): any;
+    /**
+     * A function that removes invalid elements from an array
+     *
+     * @param {any[]} array - the input array
+     * @return {any[]} the filtered array without invalid elements
+     */
+    removeInvalidElements(array: any[]): any[];
+    validateOrNullEmail(email: string): string | null;
+    /**
+     * Tries to parse a date from various formats using Luxon with enhanced error reporting.
+     * @param {string | number} input The input date as a string or timestamp.
+     * @return {string | null} The parsed date in ISO 8601 format or null if parsing failed.
+     */
+    safeParseDate(input: string | number): string | null;
+};
+/**
+ * Deeply converts all properties of an object (or array) to strings.
+ * @param data The input data to convert.
+ * @returns The data with all its properties converted to strings.
+ */
+export declare const deepAnyToString: (data: any) => any;
+/**
+ * Performs a deep conversion of all values in a nested structure to the specified type.
+ * Uses a conversion function like anyToString, anyToNumber, etc.
+ * @param data The data to convert.
+ * @param convertFn The conversion function to apply.
+ * @returns The converted data.
+ */
+export declare const deepConvert: <T>(data: any, convertFn: (value: any) => T) => any;
+/**
+ * Converts an entire object's properties to different types based on a provided schema.
+ * @param obj The object to convert.
+ * @param schema A mapping of object keys to conversion functions.
+ * @returns The converted object.
+ */
+export declare const convertObjectBySchema: (obj: Record<string, any>, schema: Record<string, (value: any) => any>) => Record<string, any>;
+/**
+ * Converts the keys of an object based on a provided attributeMappings.
+ * Each key in the object is checked against attributeMappings; if a matching entry is found,
+ * the key is renamed to the targetKey specified in attributeMappings.
+ *
+ * @param obj The object to convert.
+ * @param attributeMappings The attributeMappings defining how keys in the object should be converted.
+ * @returns The converted object with keys renamed according to attributeMappings.
+ */
+export declare const convertObjectByAttributeMappings: (obj: Record<string, any>, attributeMappings: {
+    targetKey: string;
+    converters: string[];
+    validationActions: {
+        params: string[];
+        action: string;
+    }[];
+    postImportActions: {
+        params: (string | Record<string, any>)[];
+        action: string;
+    }[];
+    oldKey?: string | undefined;
+    oldKeys?: string[] | undefined;
+    fileData?: {
+        path: string;
+        name: string;
+    } | undefined;
+}[]) => Record<string, any>;
+/**
+ * Ensures data conversion without mutating the original input.
+ * @param data The data to convert.
+ * @param convertFn The conversion function to apply.
+ * @returns The converted data.
+ */
+export declare const immutableConvert: <T>(data: any, convertFn: (value: any) => T) => T;
+/**
+ * Validates a string against a regular expression and returns the string if valid, or null.
+ * @param value The string to validate.
+ * @param pattern The regex pattern to validate against.
+ * @returns The original string if valid, otherwise null.
+ */
+export declare const validateString: (value: string, pattern: RegExp) => string | null;