@njdamstra/appwrite-utils-cli 1.8.9

package/dist/functions/methods.d.ts

@@ -0,0 +1,16 @@
+import { Client } from "node-appwrite";
+import { type AppwriteFunction, type Specification } from "@njdamstra/appwrite-utils";
+export declare const listFunctions: (client: Client, queries?: string[], search?: string) => Promise<import("node-appwrite").Models.FunctionList>;
+export declare const getFunction: (client: Client, functionId: string) => Promise<import("node-appwrite").Models.Function>;
+export declare const downloadLatestFunctionDeployment: (client: Client, functionId: string, basePath?: string) => Promise<{
+    path: string;
+    function: import("node-appwrite").Models.Function;
+    deployment: import("node-appwrite").Models.Deployment;
+}>;
+export declare const deleteFunction: (client: Client, functionId: string) => Promise<{}>;
+export declare const createFunction: (client: Client, functionConfig: AppwriteFunction) => Promise<import("node-appwrite").Models.Function>;
+export declare const updateFunctionSpecifications: (client: Client, functionId: string, specification: Specification) => Promise<import("node-appwrite").Models.Function | undefined>;
+export declare const listSpecifications: (client: Client) => Promise<import("node-appwrite").Models.SpecificationList>;
+export declare const listFunctionDeployments: (client: Client, functionId: string, queries?: string[]) => Promise<import("node-appwrite").Models.DeploymentList>;
+export declare const updateFunction: (client: Client, functionConfig: AppwriteFunction) => Promise<import("node-appwrite").Models.Function>;
+export declare const createFunctionTemplate: (templateType: "typescript-node" | "uv" | "count-docs-in-collection" | "hono-typescript", functionName: string, basePath?: string) => Promise<string>;

package/dist/functions/methods.js

@@ -0,0 +1,162 @@
+import { AppwriteException, Client, Functions, Query, Runtime, } from "node-appwrite";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import {} from "@njdamstra/appwrite-utils";
+import chalk from "chalk";
+import { extract as extractTar } from "tar";
+import { MessageFormatter } from "../shared/messageFormatter.js";
+import { expandTildePath, normalizeFunctionName } from "./pathResolution.js";
+/**
+ * Validates and filters events array for Appwrite functions
+ * - Filters out empty/invalid strings
+ * - Limits to 100 items maximum (Appwrite limit)
+ * - Returns empty array if input is invalid
+ */
+const validateEvents = (events) => {
+    if (!events || !Array.isArray(events))
+        return [];
+    return events
+        .filter(event => event && typeof event === 'string' && event.trim().length > 0)
+        .slice(0, 100);
+};
+export const listFunctions = async (client, queries, search) => {
+    const functions = new Functions(client);
+    const functionsList = await functions.list(queries, search);
+    return functionsList;
+};
+export const getFunction = async (client, functionId) => {
+    const functions = new Functions(client);
+    const functionResponse = await functions.get(functionId);
+    return functionResponse;
+};
+export const downloadLatestFunctionDeployment = async (client, functionId, basePath = process.cwd()) => {
+    const functions = new Functions(client);
+    const functionInfo = await getFunction(client, functionId);
+    const functionDeployments = await functions.listDeployments(functionId, [
+        Query.orderDesc("$createdAt"),
+    ]);
+    if (functionDeployments.deployments.length === 0) {
+        throw new Error("No deployments found for function");
+    }
+    const latestDeployment = functionDeployments.deployments[0];
+    const deploymentData = await functions.getDeploymentDownload(functionId, latestDeployment.$id);
+    // Create function directory using provided basePath
+    const functionDir = join(basePath, normalizeFunctionName(functionInfo.name));
+    await fs.promises.mkdir(functionDir, { recursive: true });
+    // Create temporary file for tar extraction
+    const tarPath = join(functionDir, "temp.tar.gz");
+    const uint8Array = new Uint8Array(deploymentData);
+    await fs.promises.writeFile(tarPath, uint8Array);
+    try {
+        // Extract tar file
+        extractTar({
+            C: functionDir,
+            file: tarPath,
+            sync: true,
+        });
+        return {
+            path: functionDir,
+            function: functionInfo,
+            deployment: latestDeployment,
+        };
+    }
+    finally {
+        // Clean up tar file
+        await fs.promises.unlink(tarPath).catch(() => { });
+    }
+};
+export const deleteFunction = async (client, functionId) => {
+    const functions = new Functions(client);
+    const functionResponse = await functions.delete(functionId);
+    return functionResponse;
+};
+export const createFunction = async (client, functionConfig) => {
+    const functions = new Functions(client);
+    const functionResponse = await functions.create(functionConfig.$id, functionConfig.name, functionConfig.runtime, functionConfig.execute, validateEvents(functionConfig.events), functionConfig.schedule, functionConfig.timeout, functionConfig.enabled, functionConfig.logging, functionConfig.entrypoint, functionConfig.commands, functionConfig.scopes, functionConfig.installationId, functionConfig.providerRepositoryId, functionConfig.providerBranch, functionConfig.providerSilentMode, functionConfig.providerRootDirectory);
+    return functionResponse;
+};
+export const updateFunctionSpecifications = async (client, functionId, specification) => {
+    const curFunction = await listFunctions(client, [
+        Query.equal("$id", functionId),
+    ]);
+    if (curFunction.functions.length === 0) {
+        throw new Error("Function not found");
+    }
+    const functionFound = curFunction.functions[0];
+    try {
+        const functionResponse = await updateFunction(client, {
+            ...functionFound,
+            runtime: functionFound.runtime,
+            scopes: functionFound.scopes,
+            specification: specification,
+        });
+        return functionResponse;
+    }
+    catch (error) {
+        if (error instanceof AppwriteException &&
+            error.message.includes("Invalid `specification`")) {
+            MessageFormatter.error("Error updating function specifications, please try setting the env variable `_FUNCTIONS_CPUS` and `_FUNCTIONS_RAM` to non-zero values", undefined, { prefix: "Functions" });
+        }
+        else {
+            MessageFormatter.error("Error updating function specifications", error instanceof Error ? error : undefined, { prefix: "Functions" });
+            throw error;
+        }
+    }
+};
+export const listSpecifications = async (client) => {
+    const functions = new Functions(client);
+    const specifications = await functions.listSpecifications();
+    return specifications;
+};
+export const listFunctionDeployments = async (client, functionId, queries) => {
+    const functions = new Functions(client);
+    const deployments = await functions.listDeployments(functionId, queries);
+    return deployments;
+};
+export const updateFunction = async (client, functionConfig) => {
+    const functions = new Functions(client);
+    const functionResponse = await functions.update(functionConfig.$id, functionConfig.name, functionConfig.runtime, functionConfig.execute, validateEvents(functionConfig.events), functionConfig.schedule, functionConfig.timeout, functionConfig.enabled, functionConfig.logging, functionConfig.entrypoint, functionConfig.commands, functionConfig.scopes, functionConfig.installationId, functionConfig.providerRepositoryId, functionConfig.providerBranch, functionConfig.providerSilentMode, functionConfig.providerRootDirectory, functionConfig.specification);
+    return functionResponse;
+};
+export const createFunctionTemplate = async (templateType, functionName, basePath = "./functions") => {
+    const expandedBasePath = expandTildePath(basePath);
+    const functionPath = join(expandedBasePath, functionName);
+    const currentFileUrl = import.meta.url;
+    const currentDir = dirname(fileURLToPath(currentFileUrl));
+    const templatesPath = join(currentDir, "templates", templateType);
+    // Create function directory
+    await fs.promises.mkdir(functionPath, { recursive: true });
+    // Copy template files recursively
+    const copyTemplateFiles = async (sourcePath, targetPath) => {
+        const entries = await fs.promises.readdir(sourcePath, {
+            withFileTypes: true,
+        });
+        for (const entry of entries) {
+            const srcPath = join(sourcePath, entry.name);
+            const destPath = join(targetPath, entry.name);
+            if (entry.isDirectory()) {
+                await fs.promises.mkdir(destPath, { recursive: true });
+                await copyTemplateFiles(srcPath, destPath);
+            }
+            else {
+                let content = await fs.promises.readFile(srcPath, "utf-8");
+                // Replace template variables
+                content = content
+                    .replace(/\{\{functionName\}\}/g, functionName)
+                    .replace(/\{\{databaseId\}\}/g, "{{databaseId}}")
+                    .replace(/\{\{collectionId\}\}/g, "{{collectionId}}");
+                await fs.promises.writeFile(destPath, content);
+            }
+        }
+    };
+    try {
+        await copyTemplateFiles(templatesPath, functionPath);
+        MessageFormatter.success(`Created ${templateType} function template at ${functionPath}`, { prefix: "Functions" });
+    }
+    catch (error) {
+        MessageFormatter.error("Failed to create function template", error instanceof Error ? error : undefined, { prefix: "Functions" });
+        throw error;
+    }
+    return functionPath;
+};

package/dist/functions/pathResolution.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Expands tilde (~) in paths to the user's home directory
+ * @param pathStr - Path string that may contain ~
+ * @returns Expanded path with home directory
+ */
+export declare function expandTildePath(pathStr: string): string;
+/**
+ * Normalizes function name to standard format (lowercase, dashes instead of spaces)
+ * @param name - Function name to normalize
+ * @returns Normalized function name
+ */
+export declare function normalizeFunctionName(name: string): string;
+/**
+ * Validates that a directory exists and contains function markers
+ * @param dirPath - Directory path to validate
+ * @returns True if directory is a valid function directory
+ */
+export declare function validateFunctionDirectory(dirPath: string): boolean;
+/**
+ * Helper function to search for function in standard locations
+ * @param configDirPath - Directory where config file is located
+ * @param normalizedName - Normalized function name
+ * @returns First valid function directory path or undefined
+ */
+export declare function findFunctionInStandardLocations(configDirPath: string, normalizedName: string): string | undefined;
+/**
+ * Resolves the absolute path to a function directory
+ * Handles multiple resolution strategies with proper priority
+ *
+ * @param functionName - Name of the function
+ * @param configDirPath - Directory where config file is located
+ * @param dirPath - Optional explicit dirPath from config
+ * @param explicitPath - Optional path passed as parameter (highest priority)
+ * @returns Absolute path to the function directory
+ * @throws Error if function directory cannot be found or is invalid
+ */
+export declare function resolveFunctionDirectory(functionName: string, configDirPath: string, dirPath?: string, explicitPath?: string): string;

package/dist/functions/pathResolution.js

@@ -0,0 +1,185 @@
+import { existsSync, statSync, readdirSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { MessageFormatter } from '../shared/messageFormatter.js';
+import { logger } from '../shared/logging.js';
+/**
+ * Expands tilde (~) in paths to the user's home directory
+ * @param pathStr - Path string that may contain ~
+ * @returns Expanded path with home directory
+ */
+export function expandTildePath(pathStr) {
+    if (!pathStr)
+        return pathStr;
+    if (pathStr.startsWith('~/') || pathStr === '~') {
+        const expandedPath = pathStr.replace(/^~(?=$|\/|\\)/, homedir());
+        logger.debug('Expanded tilde path', { original: pathStr, expanded: expandedPath });
+        return expandedPath;
+    }
+    return pathStr;
+}
+/**
+ * Normalizes function name to standard format (lowercase, dashes instead of spaces)
+ * @param name - Function name to normalize
+ * @returns Normalized function name
+ */
+export function normalizeFunctionName(name) {
+    if (!name)
+        return name;
+    const normalized = name.toLowerCase().replace(/\s+/g, '-');
+    if (normalized !== name) {
+        logger.debug('Normalized function name', { original: name, normalized });
+    }
+    return normalized;
+}
+/**
+ * Validates that a directory exists and contains function markers
+ * @param dirPath - Directory path to validate
+ * @returns True if directory is a valid function directory
+ */
+export function validateFunctionDirectory(dirPath) {
+    try {
+        // Check if directory exists
+        if (!existsSync(dirPath)) {
+            logger.debug('Directory does not exist', { dirPath });
+            return false;
+        }
+        // Check if it's actually a directory
+        const stats = statSync(dirPath);
+        if (!stats.isDirectory()) {
+            logger.debug('Path is not a directory', { dirPath });
+            return false;
+        }
+        // Check for function markers
+        const contents = readdirSync(dirPath);
+        const hasPackageJson = contents.includes('package.json');
+        const hasPyprojectToml = contents.includes('pyproject.toml');
+        const hasSrcDir = contents.includes('src');
+        const isValid = hasPackageJson || hasPyprojectToml || hasSrcDir;
+        logger.debug('Function directory validation', {
+            dirPath,
+            isValid,
+            markers: {
+                hasPackageJson,
+                hasPyprojectToml,
+                hasSrcDir
+            }
+        });
+        return isValid;
+    }
+    catch (error) {
+        logger.debug('Error validating function directory', {
+            dirPath,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        return false;
+    }
+}
+/**
+ * Helper function to search for function in standard locations
+ * @param configDirPath - Directory where config file is located
+ * @param normalizedName - Normalized function name
+ * @returns First valid function directory path or undefined
+ */
+export function findFunctionInStandardLocations(configDirPath, normalizedName) {
+    const searchPaths = [
+        // Same directory as config
+        join(configDirPath, 'functions', normalizedName),
+        // Parent directory of config
+        join(configDirPath, '..', 'functions', normalizedName),
+        // Current working directory
+        join(process.cwd(), 'functions', normalizedName),
+    ];
+    logger.debug('Searching for function in standard locations', {
+        normalizedName,
+        configDirPath,
+        searchPaths
+    });
+    for (const searchPath of searchPaths) {
+        const resolvedPath = resolve(searchPath);
+        logger.debug('Checking search path', { searchPath, resolvedPath });
+        if (validateFunctionDirectory(resolvedPath)) {
+            logger.debug('Found function in standard location', { resolvedPath });
+            return resolvedPath;
+        }
+    }
+    logger.debug('Function not found in any standard location', { normalizedName });
+    return undefined;
+}
+/**
+ * Resolves the absolute path to a function directory
+ * Handles multiple resolution strategies with proper priority
+ *
+ * @param functionName - Name of the function
+ * @param configDirPath - Directory where config file is located
+ * @param dirPath - Optional explicit dirPath from config
+ * @param explicitPath - Optional path passed as parameter (highest priority)
+ * @returns Absolute path to the function directory
+ * @throws Error if function directory cannot be found or is invalid
+ */
+export function resolveFunctionDirectory(functionName, configDirPath, dirPath, explicitPath) {
+    logger.debug('Resolving function directory', {
+        functionName,
+        configDirPath,
+        dirPath,
+        explicitPath
+    });
+    const normalizedName = normalizeFunctionName(functionName);
+    // Priority 1: Explicit path parameter (highest priority)
+    if (explicitPath) {
+        logger.debug('Using explicit path parameter');
+        const expandedPath = expandTildePath(explicitPath);
+        const resolvedPath = isAbsolute(expandedPath)
+            ? expandedPath
+            : resolve(process.cwd(), expandedPath);
+        if (!validateFunctionDirectory(resolvedPath)) {
+            const errorMsg = `Explicit path is not a valid function directory: ${resolvedPath}`;
+            logger.error(errorMsg);
+            MessageFormatter.error('Invalid function directory', errorMsg, { prefix: 'Path Resolution' });
+            throw new Error(errorMsg);
+        }
+        logger.debug('Resolved using explicit path', { resolvedPath });
+        MessageFormatter.debug(`Resolved function directory using explicit path: ${resolvedPath}`, undefined, { prefix: 'Path Resolution' });
+        return resolvedPath;
+    }
+    // Priority 2: dirPath from config (relative to config location)
+    if (dirPath) {
+        logger.debug('Using dirPath from config');
+        const expandedPath = expandTildePath(dirPath);
+        const resolvedPath = isAbsolute(expandedPath)
+            ? expandedPath
+            : resolve(configDirPath, expandedPath);
+        if (!validateFunctionDirectory(resolvedPath)) {
+            const errorMsg = `Config dirPath is not a valid function directory: ${resolvedPath}`;
+            logger.error(errorMsg);
+            MessageFormatter.error('Invalid function directory', errorMsg, { prefix: 'Path Resolution' });
+            throw new Error(errorMsg);
+        }
+        logger.debug('Resolved using config dirPath', { resolvedPath });
+        MessageFormatter.debug(`Resolved function directory using config dirPath: ${resolvedPath}`, undefined, { prefix: 'Path Resolution' });
+        return resolvedPath;
+    }
+    // Priority 3: Search standard locations
+    logger.debug('Searching standard locations for function');
+    const foundPath = findFunctionInStandardLocations(configDirPath, normalizedName);
+    if (foundPath) {
+        logger.debug('Resolved using standard location search', { foundPath });
+        MessageFormatter.debug(`Found function directory in standard location: ${foundPath}`, undefined, { prefix: 'Path Resolution' });
+        return foundPath;
+    }
+    // Priority 4: Not found - throw error
+    const searchedLocations = [
+        join(configDirPath, 'functions', normalizedName),
+        join(configDirPath, '..', 'functions', normalizedName),
+        join(process.cwd(), 'functions', normalizedName),
+    ];
+    const errorMsg = `Function directory not found for '${functionName}' (normalized: '${normalizedName}'). ` +
+        `Searched locations:\n${searchedLocations.map(p => `  - ${p}`).join('\n')}`;
+    logger.error('Function directory not found', {
+        functionName,
+        normalizedName,
+        searchedLocations
+    });
+    MessageFormatter.error('Function directory not found', errorMsg, { prefix: 'Path Resolution' });
+    throw new Error(errorMsg);
+}

package/dist/functions/templates/count-docs-in-collection/README.md

@@ -0,0 +1,54 @@
+# Count Documents in Collection Function
+
+A utility function that accurately counts documents in an Appwrite collection, even when there are more than 5,000 documents.
+
+## Features
+- Handles collections with any number of documents
+- Supports filtering using Appwrite queries
+- Uses efficient binary search algorithm for large collections
+- Provides detailed logging during the counting process
+
+## Structure
+- `src/main.ts`: Main function implementation with counting logic
+- `src/request.ts`: Request validation schema using Zod
+
+## Usage
+Send a POST request with:
+```json
+{
+  "databaseId": "your-database-id",
+  "collectionId": "your-collection-id",
+  "queries": [Query.orderDesc("$createdAt"), Query.contains("name", "John")] // Or put the string array from after this, they are the same
+}
+```
+
+## Response
+```json
+{
+  "success": true,
+  "count": 12345
+}
+```
+
+## Development
+1. Install dependencies: `npm|yarn|bun install`
+2. Build: `npm|yarn|bun run build`
+3. Deploy: Function will be built automatically during deployment
+
+## Deployment
+Make sure it's inside `appwriteConfig.ts` functions array, and if you want to build it FIRST, before Appwrite (using your system), you can
+add the `predeployCommands` to the function in `appwriteConfig.ts`.
+
+## Example Config
+```typescript
+{
+  $id: 'count-docs',
+  name: 'Count Documents',
+  runtime: 'node-18.0',
+  path: 'functions/count-docs',
+  entrypoint: './main.js',
+  execute: ['any'],
+  predeployCommands: ['npm install', 'npm run build'],
+  deployDir: './dist'
+}
+```

package/dist/functions/templates/count-docs-in-collection/src/main.ts

@@ -0,0 +1,159 @@
+import { Client, Databases, Query } from "node-appwrite";
+import { AppwriteRequest, type AppwriteResponse } from "@njdamstra/appwrite-utils";
+import { requestSchema } from "./request.js";
+
+/**
+ * Main function to handle document counting requests.
+ * @param {Object} params - The function parameters.
+ * @param {Object} params.req - The request object.
+ * @param {Object} params.res - The response object.
+ * @param {Function} params.log - Logging function.
+ * @param {Function} params.error - Error logging function.
+ * @returns {Promise<Object>} JSON response with count or error message.
+ */
+export default async ({
+  req,
+  res,
+  log,
+  error,
+}: {
+  req: AppwriteRequest;
+  res: AppwriteResponse;
+  log: (message: string) => void;
+  error: (message: string) => void;
+}) => {
+  // Initialize Appwrite client
+  const client = new Client()
+    .setEndpoint(process.env["APPWRITE_FUNCTION_ENDPOINT"]!)
+    .setProject(process.env["APPWRITE_FUNCTION_PROJECT_ID"]!)
+    .setKey(req.headers["x-appwrite-key"] || "");
+
+  const databases = new Databases(client);
+
+  try {
+    if (req.method === "POST") {
+      // Parse request body
+      const body = requestSchema.safeParse(
+        typeof req.body === "string" ? JSON.parse(req.body) : req.body
+      );
+
+      if (!body.success) {
+        return res.json({ success: false, error: body.error }, 400);
+      }
+
+      const { databaseId, collectionId, queries = [] } = body.data;
+
+      log(`Queries: ${JSON.stringify(queries)}`);
+
+      // Count documents in the specified collection
+      const count = await countAllDocuments(
+        log,
+        databases,
+        databaseId,
+        collectionId,
+        queries
+      );
+
+      // Return successful response with document count
+      return res.json({
+        success: true,
+        count: count,
+      });
+    } else {
+      // Return error for non-POST requests
+      return res.json({ success: false, error: "Method not allowed" }, 405);
+    }
+  } catch (err) {
+    // Log and return any errors
+    error(`Error processing request: ${err}`);
+    return res.json({ success: false, error: (err as Error).message }, 500);
+  }
+};
+
+/**
+ * Counts all documents in a collection, handling large collections efficiently.
+ * @param {Function} log - Logging function.
+ * @param {Databases} databases - Appwrite Databases instance.
+ * @param {string} databaseId - ID of the database.
+ * @param {string} collectionId - ID of the collection.
+ * @param {string[]} queries - Array of query strings to filter documents.
+ * @param {number} batchSize - Size of batches for processing (default: 1000).
+ * @returns {Promise<number>} Total count of documents.
+ */
+async function countAllDocuments(
+  log: any,
+  databases: Databases,
+  databaseId: string,
+  collectionId: string,
+  queries: string[] = [],
+  batchSize: number = 1000
+): Promise<number> {
+  // Filter out limit and offset queries
+  const initialQueries = queries.filter(
+    (q) => !(q.includes("limit") || q.includes("offset"))
+  );
+
+  // Initial query to check if total is less than 5000
+  const initialResponse = await databases.listDocuments(
+    databaseId,
+    collectionId,
+    [...initialQueries, Query.limit(1)]
+  );
+
+  if (initialResponse.total < 5000) {
+    log(`Total documents (from initial response): ${initialResponse.total}`);
+    return initialResponse.total;
+  }
+
+  // If total is 5000 or more, we need to count manually
+  let bound = 5000;
+
+  // Exponential search to find an upper bound
+  while (true) {
+    log(`Querying for offset ${bound}`);
+    try {
+      const response = await databases.listDocuments(databaseId, collectionId, [
+        ...initialQueries,
+        Query.limit(1),
+        Query.offset(bound),
+      ]);
+
+      if (response.documents.length === 0) {
+        break;
+      }
+      bound *= 2;
+    } catch (error) {
+      break;
+    }
+  }
+
+  // Binary search to find the exact count
+  let low = Math.floor(bound / 2);
+  let high = bound;
+  let lastValidCount = low;
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    log(`Binary search: Querying for offset ${mid}`);
+
+    try {
+      const response = await databases.listDocuments(databaseId, collectionId, [
+        ...initialQueries,
+        Query.limit(1),
+        Query.offset(mid),
+      ]);
+
+      if (response.documents.length > 0) {
+        lastValidCount = mid + 1; // +1 because offset is 0-based
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    } catch (error) {
+      high = mid - 1;
+    }
+  }
+
+  log(`Total documents: ${lastValidCount}`);
+  return lastValidCount;
+}

package/dist/functions/templates/count-docs-in-collection/src/request.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const requestSchema = z.object({
+  databaseId: z.string(),
+  collectionId: z.string(),
+  queries: z.array(z.string()).optional(),
+});
+
+export type Request = z.infer<typeof requestSchema>;