appwrite-utils-cli 0.0.1

package/src/utils/helperFunctions.ts

@@ -0,0 +1,111 @@
+import type { AppwriteConfig } from "../types.js";
+import type { Models, Storage } from "node-appwrite";
+import fs from "node:fs";
+import path from "node:path";
+
+export const toPascalCase = (str: string): string => {
+  return (
+    str
+      // Split the string into words on spaces or camelCase transitions
+      .split(/(?:\s+)|(?:([A-Z][a-z]+))/g)
+      // Filter out empty strings that can appear due to the split regex
+      .filter(Boolean)
+      // Capitalize the first letter of each word and join them together
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join("")
+  );
+};
+
+export const toCamelCase = (str: string): string => {
+  return str
+    .replace(/(?:^\w|[A-Z]|\b\w)/g, (word, index) =>
+      index === 0 ? word.toLowerCase() : word.toUpperCase()
+    )
+    .replace(/\s+/g, "");
+};
+
+export const ensureDirectoryExistence = (filePath: string) => {
+  const dirname = path.dirname(filePath);
+  if (fs.existsSync(dirname)) {
+    return true;
+  }
+  ensureDirectoryExistence(dirname);
+  fs.mkdirSync(dirname);
+};
+
+export const writeFileSync = (
+  filePath: string,
+  content: string,
+  options: { flag: string }
+) => {
+  ensureDirectoryExistence(filePath);
+  fs.writeFileSync(filePath, content, options);
+};
+
+export const readFileSync = (filePath: string) => {
+  return fs.readFileSync(filePath, "utf8");
+};
+
+export const existsSync = (filePath: string) => {
+  return fs.existsSync(filePath);
+};
+
+export const mkdirSync = (filePath: string) => {
+  ensureDirectoryExistence(filePath);
+  fs.mkdirSync(filePath);
+};
+
+export const readdirSync = (filePath: string) => {
+  return fs.readdirSync(filePath);
+};
+
+export const areCollectionNamesSame = (a: string, b: string) => {
+  return (
+    a.toLowerCase().trim().replace(" ", "") ===
+    b.toLowerCase().trim().replace(" ", "")
+  );
+};
+
+/**
+ * Generates the view URL for a specific file based on the provided endpoint, project ID, bucket ID, file ID, and optional JWT token.
+ *
+ * @param {string} endpoint - the base URL endpoint
+ * @param {string} projectId - the ID of the project
+ * @param {string} bucketId - the ID of the bucket
+ * @param {string} fileId - the ID of the file
+ * @param {Models.Jwt} [jwt] - optional JWT token generated via the Appwrite SDK
+ * @return {string} the generated view URL for the file
+ */
+export const getFileViewUrl = (
+  endpoint: string,
+  projectId: string,
+  bucketId: string,
+  fileId: string,
+  jwt?: Models.Jwt
+) => {
+  return `${endpoint}/storage/buckets/${bucketId}/files/${fileId}/view?project=${projectId}${
+    jwt ? `&jwt=${jwt.jwt}` : ""
+  }`;
+};
+
+/**
+ * Generates a download URL for a file based on the provided endpoint, project ID, bucket ID, file ID, and optionally a JWT.
+ *
+ * @param {string} endpoint - The base URL endpoint.
+ * @param {string} projectId - The ID of the project.
+ * @param {string} bucketId - The ID of the bucket.
+ * @param {string} fileId - The ID of the file.
+ * @param {Models.Jwt} [jwt] - Optional JWT object for authentication with Appwrite.
+ * @return {string} The complete download URL for the file.
+ */
+export const getFileDownloadUrl = (
+  endpoint: string,
+  projectId: string,
+  bucketId: string,
+  fileId: string,
+  jwt?: Models.Jwt
+) => {
+  return `${endpoint}/storage/buckets/${bucketId}/files/${fileId}/download?project=${projectId}${
+    jwt ? `&jwt=${jwt.jwt}` : ""
+  }`;
+};

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./helperFunctions.js";
+export * from "./setupFiles.js";

package/src/utils/setupFiles.ts

@@ -0,0 +1,295 @@
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import configSchema from "./configSchema.json" assert { type: "json" };
+
+// Define our YAML files
+// Define our YAML files
+const configFileExample = `# yaml-language-server: $schema=./.appwrite/appwriteUtilsConfigSchema.json
+# Appwrite configuration settings
+appwriteEndpoint: 'https://cloud.appwrite.io/v1' # Your Appwrite endpoint. Default: 'https://cloud.appwrite.io/v1'
+appwriteProject: 'YOUR_PROJECT_ID' # Your Appwrite project ID
+appwriteKey: 'YOUR_API_KEY' # Your Appwrite API key (needs storage and databases at minimum)
+appwriteClient: null # Your Appwrite client -- don't worry about this
+enableDevDatabase: true # Enable development database alongside main
+enableBackups: true # Enable backups
+backupInterval: 3600 # Backup interval in seconds
+backupRetention: 30 # Backup retention in days
+enableBackupCleanup: true # Enable backup cleanup
+enableMockData: false # Enable mock data generation
+enableWipeOtherDatabases: true # Enable wiping other databases
+documentBucketId: 'documents' # Your Appwrite bucket ID for documents
+usersCollectionName: 'Members' # Your Appwrite collection for any extra info while importing members (if any)
+                               # This allows you to use any targetKey in the users field to create your user
+                               # these are: name, email, phone, labels, prefs, password, userId and (not yet added)
+                               # $createdAt, $updatedAt -- Add them to your attributeMappings (NOT attributes) to define them and set the
+                               # targetKey to the same as the Appwrite targetKey
+databases:
+  - $id: 'main'
+    name: 'Main'
+  - $id: 'staging'
+    name: 'Staging'
+  - $id: 'dev'
+    name: 'Development'
+collections:
+  - name: 'Members'
+    $permissions:
+      - permission: read
+        target: any
+      - permission: create
+        target: users
+      - permission: update
+        target: users
+      - permission: delete
+        target: users
+    attributes:
+      - key: 'idOrig'
+        type: 'string'
+        size: 255
+        required: false
+      - key: 'dogs'
+        type: 'relationship'
+        relatedCollection: 'Dogs'
+        relationType: 'oneToMany'
+        twoWay: true
+        twoWayKey: 'owner'
+        side: 'parent'
+        onDelete: 'cascade'
+        importMapping: { originalIdField: 'idOrig', targetField: 'ownerIdOrig' }
+      - key: 'dogIds'
+        type: 'string'
+        size: 255
+        array: true
+      - key: 'profilePhoto'
+        type: 'string'
+        size: 255
+        required: false
+      - key: 'profilePhotoTest'
+        type: 'string'
+        size: 255
+        required: false
+    indexes:
+      - key: 'idOrig_index'
+        type: 'key'
+        attributes: ['idOrig']
+    importDefs:
+      - filePath: 'importData/members.json'
+        basePath: 'RECORDS'
+        attributeMappings:
+          - oldKey: 'id'
+            targetKey: 'idOrig'
+            converters: ['anyToString']
+            postImportActions:
+              - action: 'checkAndUpdateFieldInDocument'
+                params:
+                  - "{dbId}"
+                  - "{collId}"
+                  - "{docId}"
+                  - "idOrig"
+                  - "{id}"
+                  - "{$id}"
+          - oldKey: 'name'
+            targetKey: 'name'
+          - oldKey: 'email'
+            targetKey: 'email'
+          - oldKey: 'doesntMatter'
+            targetKey: 'profilePhoto'
+            fileData: { name: "profilePhoto_{id}", path: "importData/profilePhotos" }
+          - oldKey: 'photoUrl'
+            targetKey: 'profilePhotoTest'
+            fileData: { name: "profilePhotoTest_{id}", path: "{photoUrl}" }
+  - name: 'Dogs'
+    $permissions:
+      - permission: read
+        target: any
+      - permission: create
+        target: users
+      - permission: update
+        target: users
+      - permission: delete
+        target: users
+    attributes:
+      - key: 'name'
+        type: 'string'
+        size: 255
+        required: true
+      - key: 'breed'
+        type: 'string'
+        size: 255
+        required: false
+      - key: 'age'
+        type: 'integer'
+        required: false
+        min: 0
+        max: 100
+      - key: 'idOrig'
+        type: 'string'
+        size: 20
+        required: false
+      - key: 'ownerIdOrig'
+        type: 'string'
+        size: 255
+        required: false
+      - key: 'vetRecords'
+        type: 'string'
+        size: 255
+        required: false
+      - key: 'vetRecordIds'
+        type: 'string'
+        size: 255
+        array: true
+        required: false
+    indexes:
+      - key: 'ownerIdIndex'
+        type: 'key'
+        attributes: ['ownerIdOrig']
+    importDefs:
+      - filePath: 'importData/dogs.json'
+        basePath: 'RECORDS'
+        attributeMappings:
+          - oldKey: 'id'
+            targetKey: 'idOrig'
+          - oldKey: 'name'
+            targetKey: 'name'
+          - oldKey: 'breed'
+            targetKey: 'breed'
+          - oldKey: 'age'
+            targetKey: 'age'
+          - oldKey: 'ownerId'
+            targetKey: 'ownerIdOrig'
+          - oldKey: 'vetRecords'
+            targetKey: 'vetRecords'
+            converters: ['stringifyObject']
+          - oldKey: 'vetRecords.[any].id'
+            targetKey: 'vetRecordIds'
+            converters: ['anyToString']
+      - filePath: 'importData/dogs.json'
+        basePath: 'RECORDS'
+        type: 'update'
+        updateMapping: { originalIdField: 'id', targetField: 'idOrig' }
+        attributeMappings:
+          - oldKey: 'name'
+            targetKey: 'name'
+          - oldKey: 'breed'
+            targetKey: 'breed'
+          - oldKey: 'age'
+            targetKey: 'age'`;
+
+const configFile = `# yaml-language-server: $schema=./.appwrite/appwriteUtilsConfigSchema.json
+# Basic Appwrite configuration settings
+appwriteEndpoint: 'https://cloud.appwrite.io/v1' # Your Appwrite endpoint
+appwriteProject: 'YOUR_PROJECT_ID' # Your Appwrite project ID
+appwriteKey: 'YOUR_API_KEY' # Your Appwrite API key (needs storage and databases at minimum)
+enableDevDatabase: true # Enable development database alongside main. Default: true
+enableBackups: true # Enable backups. Default: true
+backupInterval: 3600 # Backup interval in seconds. Default: 3600 - DOES NOTHING RIGHT NOW
+backupRetention: 30 # Backup retention in days. Default: 30 - DOES NOTHING RIGHT NOW
+enableBackupCleanup: true # Enable backup cleanup. Default: true - DOES NOTHING RIGHT NOW
+enableMockData: false # Enable mock data generation. Default: false - DOES NOTHING RIGHT NOW
+enableWipeOtherDatabases: true # Enable wiping other databases. Default: true
+documentBucketId: 'documents' # Your Appwrite bucket ID for documents. Default: 'documents'
+usersCollectionName: 'Members' # Your Appwrite collection for any extra info while importing members (if any). Default: 'Members'
+# Databases configuration
+# The first one is *always* Production
+# The second is *always* Staging
+# The third is *always* Development
+# They are found by name matching (without spaces and all lowercase), not $id
+# If no $id is included for anything defined, Appwrite will auto-generate one in its stead
+databases:
+  - $id: 'main' # Database ID
+    name: 'Main' # Database name
+  - $id: 'staging'
+    name: 'Staging'
+  - $id: 'dev'
+    name: 'Development'
+
+# Collections configuration
+collections:
+  - name: 'ExampleCollection' # Collection name
+    $permissions: # Permissions for the collection
+      - permission: read # Permission type
+        target: any # Permission target
+      - permission: create
+        target: users
+      - permission: update
+        target: users
+      - permission: delete
+        target: users
+    attributes: # Attributes of the collection
+      - key: 'exampleKey' # Attribute key
+        type: 'string' # Attribute type
+        size: 255 # Size of the attribute (for strings)
+        required: true # Whether the attribute is required`;
+
+export const customDefinitionsFile = `import type { ConverterFunctions, ValidationRules, AfterImportActions } from "appwrite-utils";
+
+export const customConverterFunctions: ConverterFunctions = {
+  // Add your custom converter functions here
+}
+export const customValidationRules: ValidationRules = {
+  // Add your custom validation rules here
+}
+export const customAfterImportActions: AfterImportActions = {
+  // Add your custom after import actions here
+}`;
+
+export const setupDirsFiles = async (example: boolean = false) => {
+  const basePath = process.cwd();
+  const srcPath = path.join(basePath, "src");
+
+  // Check if src directory exists in the current working directory
+  if (!existsSync(srcPath)) {
+    console.error("No 'src' directory found in the current working directory.");
+    return;
+  }
+
+  const appwriteFolder = path.join(srcPath, "appwrite");
+  const appwriteConfigFile = path.join(appwriteFolder, "appwriteConfig.yaml");
+  const appwriteCustomDefsFile = path.join(
+    appwriteFolder,
+    "customDefinitions.ts"
+  );
+  // const appwriteMigrationsFolder = path.join(appwriteFolder, "migrations");
+  const appwriteSchemaFolder = path.join(appwriteFolder, "schemas");
+  const appwriteDataFolder = path.join(appwriteFolder, "importData");
+  const appwriteHiddenFolder = path.join(appwriteFolder, ".appwrite");
+
+  // Directory creation and file writing logic remains the same
+  if (!existsSync(appwriteFolder)) {
+    mkdirSync(appwriteFolder, { recursive: true });
+  }
+
+  if (!existsSync(appwriteConfigFile)) {
+    if (example) {
+      writeFileSync(appwriteConfigFile, configFileExample);
+    } else {
+      writeFileSync(appwriteConfigFile, configFile);
+    }
+  }
+
+  if (!existsSync(appwriteCustomDefsFile)) {
+    writeFileSync(appwriteCustomDefsFile, customDefinitionsFile);
+  }
+
+  // if (!existsSync(appwriteMigrationsFolder)) {
+  //   mkdirSync(appwriteMigrationsFolder, { recursive: true });
+  // }
+
+  if (!existsSync(appwriteSchemaFolder)) {
+    mkdirSync(appwriteSchemaFolder, { recursive: true });
+  }
+
+  if (!existsSync(appwriteDataFolder)) {
+    mkdirSync(appwriteDataFolder, { recursive: true });
+  }
+
+  if (!existsSync(appwriteHiddenFolder)) {
+    mkdirSync(appwriteHiddenFolder, { recursive: true });
+  }
+  const schemaFilePath = path.join(
+    appwriteHiddenFolder,
+    "appwriteUtilsConfigSchema.json"
+  );
+  writeFileSync(schemaFilePath, JSON.stringify(configSchema, undefined, 2));
+
+  console.log("Created config and setup files/directories successfully.");
+};

package/src/utilsController.ts

@@ -0,0 +1,173 @@
+import { Client, Databases, Storage } from "node-appwrite";
+import { startSetup } from "./migrations/setupDatabase.js";
+import {
+  type AppwriteConfig,
+  AppwriteConfigSchema,
+} from "./migrations/schema.js";
+import path from "path";
+import fs from "fs";
+import { load } from "js-yaml";
+import { ImportDataActions } from "./migrations/importDataActions.js";
+import {
+  converterFunctions,
+  type ConverterFunctions,
+} from "./migrations/converters.js";
+import { readFileSync } from "./utils/helperFunctions.js";
+import {
+  afterImportActions,
+  type AfterImportActions,
+} from "./migrations/afterImportActions.js";
+import {
+  validationRules,
+  type ValidationRules,
+} from "./migrations/validationRules.js";
+import { ImportController } from "./migrations/importController.js";
+import _ from "lodash";
+
+async function loadConfig(configPath: string) {
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Configuration file not found at ${configPath}`);
+  }
+  const configModule = await load(readFileSync(configPath), {
+    json: true,
+  });
+  return AppwriteConfigSchema.parse(configModule);
+}
+
+export interface SetupOptions {
+  runProd: boolean;
+  runStaging: boolean;
+  runDev: boolean;
+  doBackup: boolean;
+  wipeDatabases: boolean;
+  wipeDocumentStorage: boolean;
+  wipeUsers: boolean;
+  generateSchemas: boolean;
+  generateMockData: boolean;
+  importData: boolean;
+  checkDuplicates: boolean;
+}
+
+type CollectionConfig = AppwriteConfig["collections"];
+type ImportDef = CollectionConfig[number]["importDefs"][number];
+type AttributeMappings = ImportDef["attributeMappings"];
+type AfterImportAction = AttributeMappings[number]["postImportActions"][number];
+type ValidityRule = AttributeMappings[number]["validationActions"][number];
+
+export class UtilsController {
+  private appwriteFolderPath: string;
+  private appwriteConfigPath: string;
+  private config?: AppwriteConfig;
+  private appwriteServer?: Client;
+  private database?: Databases;
+  private storage?: Storage;
+  public converterDefinitions: ConverterFunctions = converterFunctions;
+  public validityRuleDefinitions: ValidationRules = validationRules;
+  public afterImportActionsDefinitions: AfterImportActions = afterImportActions;
+
+  constructor() {
+    const basePath = process.cwd(); // Gets the current working directory
+    const appwriteFolderPath = path.join(basePath, "src", "appwrite");
+    const appwriteConfigPath = path.join(
+      appwriteFolderPath,
+      "appwriteConfig.yaml"
+    );
+    this.appwriteFolderPath = appwriteFolderPath;
+    this.appwriteConfigPath = appwriteConfigPath;
+  }
+
+  // async loadCustomDefinitions(): Promise<void> {
+  //   try {
+  //     const customDefinitionsPath = path.join(
+  //       this.appwriteFolderPath,
+  //       "customDefinitions.ts"
+  //     );
+  //     if (fs.existsSync(customDefinitionsPath)) {
+  //       // Dynamically import custom definitions
+  //       const customDefinitions = (await import(
+  //         customDefinitionsPath
+  //       )) as typeof import("customDefinitions");
+  //       this.converterDefinitions = {
+  //         ...this.converterDefinitions,
+  //         ...customDefinitions.converterDefinitions,
+  //       };
+  //       this.validityRuleDefinitions = {
+  //         ...this.validityRuleDefinitions,
+  //         ...customDefinitions.validityRuleDefinitions,
+  //       };
+  //       this.afterImportActionsDefinitions = {
+  //         ...this.afterImportActionsDefinitions,
+  //         ...customDefinitions.afterImportActionsDefinitions,
+  //       };
+  //     }
+  //   } catch (error) {
+  //     console.error("Failed to load custom definitions:", error);
+  //   }
+  // }
+
+  async init() {
+    if (!this.config) {
+      console.log("Initializing appwrite client & loading config...");
+      this.config = await loadConfig(this.appwriteConfigPath);
+      this.appwriteServer = new Client()
+        .setEndpoint(this.config.appwriteEndpoint)
+        .setProject(this.config.appwriteProject)
+        .setKey(this.config.appwriteKey);
+      this.database = new Databases(this.appwriteServer);
+      this.storage = new Storage(this.appwriteServer);
+      this.config.appwriteClient = this.appwriteServer;
+      // await this.loadCustomDefinitions();
+    }
+  }
+
+  async run(options: SetupOptions) {
+    await this.init(); // Ensure initialization is done
+    if (!this.database || !this.storage || !this.config) {
+      throw new Error("Database or storage not initialized");
+    }
+
+    // Start the setup
+    console.log(
+      "Starting setup, this step sets up migrations, runs backup, wipes databases, and updates schemas (depending on your options)..."
+    );
+    await startSetup(
+      this.database,
+      this.storage,
+      this.config,
+      options,
+      this.appwriteFolderPath
+    );
+    console.log("Setup complete.");
+
+    if (options.generateMockData) {
+      // TODO: Figure out how to do this dynamically
+      // await this.generateMockData();
+    }
+
+    if (options.importData) {
+      console.log("Starting import data...");
+      const importDataActions = new ImportDataActions(
+        this.database,
+        this.storage,
+        this.config,
+        this.converterDefinitions,
+        this.validityRuleDefinitions,
+        this.afterImportActionsDefinitions
+      );
+      const importController = new ImportController(
+        this.config!,
+        this.database!,
+        this.storage!,
+        this.appwriteFolderPath,
+        importDataActions,
+        options
+      );
+      await importController.run();
+      console.log("Import data complete.");
+    }
+
+    // if (options.checkDuplicates) {
+    //   await this.checkDuplicates();
+    // }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "target": "ESNext",
+    "module": "NodeNext",
+    "lib": ["ESNext"],
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "allowArbitraryExtensions": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+
+    // NodeNext mode
+    "moduleResolution": "NodeNext",
+    "verbatimModuleSyntax": true,
+    "noEmit": false,
+    "emitDeclarationOnly": false,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false,
+    "baseUrl": ".",
+    "esModuleInterop": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true
+  },
+  "include": ["src/main.ts", "src/**/*"],
+  "exclude": ["node_modules", "dist", "src/appwrite", "example/*"]
+}