appwrite-utils-cli 1.7.7 → 1.7.9

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/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{functionName}}",
+  "version": "1.0.0",
+  "description": "Appwrite function to count documents in a collection",
+  "main": "src/main.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/main.js",
+    "dev": "tsx src/main.ts"
+  },
+  "dependencies": {
+    "node-appwrite": "^13.0.0",
+    "appwrite-utils": "latest",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

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 "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>;

package/dist/functions/templates/count-docs-in-collection/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "checkJs": false,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noImplicitThis": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "moduleDetection": "force",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}