@njdamstra/appwrite-utils-cli 1.8.9 → 1.10.1

package/dist/config/services/ConfigMergeService.d.ts

@@ -1,208 +0,0 @@
-import type { AppwriteConfig } from "@njdamstra/appwrite-utils";
-import type { SessionAuthInfo } from "./SessionAuthService.js";
-/**
- * Configuration override options that can be applied from CLI arguments or environment
- */
-export interface ConfigOverrides {
-    /** Appwrite endpoint URL (e.g., https://cloud.appwrite.io/v1) */
-    appwriteEndpoint?: string;
-    /** Appwrite project ID */
-    appwriteProject?: string;
-    /** API key for authentication */
-    appwriteKey?: string;
-    /** Session cookie for authentication */
-    sessionCookie?: string;
-    /** Explicitly set authentication method */
-    authMethod?: "session" | "apikey" | "auto";
-}
-/**
- * Service responsible for merging configuration from multiple sources with proper priority handling.
- *
- * @description
- * Handles configuration merging with the following priority order (highest to lowest):
- * 1. CLI arguments/overrides (--endpoint, --apiKey, etc.)
- * 2. Session cookie from ~/.appwrite/prefs.json
- * 3. Config file values (YAML/TS/JSON)
- * 4. Environment variables (APPWRITE_ENDPOINT, APPWRITE_PROJECT, etc.)
- *
- * The service ensures proper deep merging of nested objects while preserving array order
- * and preventing undefined/null values from overwriting existing values.
- *
- * @example
- * ```typescript
- * const mergeService = new ConfigMergeService();
- *
- * // Merge session into config
- * const configWithSession = mergeService.mergeSession(baseConfig, sessionInfo);
- *
- * // Apply CLI overrides
- * const finalConfig = mergeService.applyOverrides(configWithSession, {
- *   appwriteEndpoint: 'https://custom-endpoint.com/v1',
- *   appwriteKey: 'custom-api-key'
- * });
- * ```
- */
-export declare class ConfigMergeService {
-    /**
-     * Merges session authentication information into an existing configuration.
-     *
-     * @description
-     * Adds session authentication details to the configuration, setting:
-     * - sessionCookie: The authentication cookie from the session
-     * - authMethod: Set to "session" to indicate session-based auth
-     *
-     * The session endpoint and projectId are used for validation but not merged
-     * since they should match the config's values.
-     *
-     * @param config - Base configuration to merge session into
-     * @param session - Session authentication information
-     * @returns New configuration object with session merged (input config is not mutated)
-     *
-     * @example
-     * ```typescript
-     * const configWithSession = mergeService.mergeSession(config, {
-     *   projectId: "my-project",
-     *   endpoint: "https://cloud.appwrite.io/v1",
-     *   sessionCookie: "eyJhbGc...",
-     *   email: "user@example.com"
-     * });
-     * ```
-     */
-    mergeSession(config: AppwriteConfig, session: SessionAuthInfo): AppwriteConfig;
-    /**
-     * Applies configuration overrides from CLI arguments or programmatic sources.
-     *
-     * @description
-     * Applies high-priority overrides that take precedence over all other config sources.
-     * Only applies values that are explicitly set (not undefined or null).
-     *
-     * This method is typically used to apply CLI arguments like:
-     * - --endpoint
-     * - --apiKey
-     * - --project
-     *
-     * @param config - Base configuration to apply overrides to
-     * @param overrides - Override values to apply
-     * @returns New configuration object with overrides applied (input config is not mutated)
-     *
-     * @example
-     * ```typescript
-     * const overriddenConfig = mergeService.applyOverrides(config, {
-     *   appwriteEndpoint: 'https://custom.appwrite.io/v1',
-     *   appwriteKey: 'my-api-key',
-     *   authMethod: 'apikey'
-     * });
-     * ```
-     */
-    applyOverrides(config: AppwriteConfig, overrides: ConfigOverrides): AppwriteConfig;
-    /**
-     * Merges environment variables into the configuration.
-     *
-     * @description
-     * Reads environment variables and merges them into the config with the lowest priority.
-     * Only applies environment variables that are set and have non-empty values.
-     *
-     * Supported environment variables:
-     * - APPWRITE_ENDPOINT: Appwrite API endpoint URL
-     * - APPWRITE_PROJECT: Appwrite project ID
-     * - APPWRITE_API_KEY: API key for authentication
-     * - APPWRITE_SESSION_COOKIE: Session cookie for authentication
-     *
-     * Environment variables are only applied if the corresponding config value is not already set.
-     *
-     * @param config - Base configuration to merge environment variables into
-     * @returns New configuration object with environment variables merged (input config is not mutated)
-     *
-     * @example
-     * ```typescript
-     * // With env vars: APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
-     * const configWithEnv = mergeService.mergeEnvironmentVariables(config);
-     * // configWithEnv.appwriteEndpoint will be set from env var if not already set
-     * ```
-     */
-    mergeEnvironmentVariables(config: AppwriteConfig): AppwriteConfig;
-    /**
-     * Performs a deep merge of multiple partial configuration sources into a complete configuration.
-     *
-     * @description
-     * Merges multiple configuration sources using a deep merge strategy that:
-     * - Recursively merges nested objects
-     * - Preserves array order (arrays are replaced, not merged)
-     * - Skips undefined and null values (they don't overwrite existing values)
-     * - Later sources in the array take precedence over earlier ones
-     *
-     * This method is useful when combining:
-     * - Base defaults with file-based config
-     * - Multiple configuration files
-     * - Config fragments from different sources
-     *
-     * @param sources - Array of partial configurations to merge (order matters: later sources override earlier ones)
-     * @returns Complete merged configuration object
-     *
-     * @throws {Error} If no valid configuration can be produced from the sources
-     *
-     * @example
-     * ```typescript
-     * const merged = mergeService.mergeSources([
-     *   envConfig,           // Lowest priority
-     *   fileConfig,          // Medium priority
-     *   sessionConfig,       // Higher priority
-     *   overrideConfig       // Highest priority
-     * ]);
-     * ```
-     */
-    mergeSources(sources: Array<Partial<AppwriteConfig>>): AppwriteConfig;
-    /**
-     * Internal helper for deep merging two configuration objects.
-     *
-     * @description
-     * Performs a deep merge of two objects with special handling for:
-     * - Plain objects: Recursively merged
-     * - Arrays: Target array is replaced by source array (not merged)
-     * - Undefined/null values in source: Skipped (don't overwrite target)
-     * - Primitive values: Source overwrites target
-     *
-     * This is used internally by mergeSources but can also be used directly
-     * for specific merge operations.
-     *
-     * @param target - Base configuration object
-     * @param source - Configuration to merge into target
-     * @returns New deeply merged configuration object
-     *
-     * @private
-     */
-    private deepMergeConfigs;
-    /**
-     * Creates a configuration by merging all sources in the correct priority order.
-     *
-     * @description
-     * Convenience method that applies the full configuration merge pipeline:
-     * 1. Start with base config (from file)
-     * 2. Merge environment variables (lowest priority)
-     * 3. Merge session information (if provided)
-     * 4. Apply CLI/programmatic overrides (highest priority)
-     *
-     * This is the recommended way to build a final configuration from all sources.
-     *
-     * @param baseConfig - Configuration loaded from file (YAML/TS/JSON)
-     * @param options - Optional merge options
-     * @param options.session - Session authentication to merge
-     * @param options.overrides - CLI/programmatic overrides to apply
-     * @param options.includeEnv - Whether to include environment variables (default: true)
-     * @returns Final merged configuration with all sources applied in priority order
-     *
-     * @example
-     * ```typescript
-     * const finalConfig = mergeService.mergeAllSources(fileConfig, {
-     *   session: sessionInfo,
-     *   overrides: cliOverrides,
-     *   includeEnv: true
-     * });
-     * ```
-     */
-    mergeAllSources(baseConfig: AppwriteConfig, options?: {
-        session?: SessionAuthInfo;
-        overrides?: ConfigOverrides;
-        includeEnv?: boolean;
-    }): AppwriteConfig;
-}

package/dist/config/services/ConfigMergeService.js

@@ -1,308 +0,0 @@
-import { merge, cloneDeep, isPlainObject } from "es-toolkit";
-/**
- * Service responsible for merging configuration from multiple sources with proper priority handling.
- *
- * @description
- * Handles configuration merging with the following priority order (highest to lowest):
- * 1. CLI arguments/overrides (--endpoint, --apiKey, etc.)
- * 2. Session cookie from ~/.appwrite/prefs.json
- * 3. Config file values (YAML/TS/JSON)
- * 4. Environment variables (APPWRITE_ENDPOINT, APPWRITE_PROJECT, etc.)
- *
- * The service ensures proper deep merging of nested objects while preserving array order
- * and preventing undefined/null values from overwriting existing values.
- *
- * @example
- * ```typescript
- * const mergeService = new ConfigMergeService();
- *
- * // Merge session into config
- * const configWithSession = mergeService.mergeSession(baseConfig, sessionInfo);
- *
- * // Apply CLI overrides
- * const finalConfig = mergeService.applyOverrides(configWithSession, {
- *   appwriteEndpoint: 'https://custom-endpoint.com/v1',
- *   appwriteKey: 'custom-api-key'
- * });
- * ```
- */
-export class ConfigMergeService {
-    /**
-     * Merges session authentication information into an existing configuration.
-     *
-     * @description
-     * Adds session authentication details to the configuration, setting:
-     * - sessionCookie: The authentication cookie from the session
-     * - authMethod: Set to "session" to indicate session-based auth
-     *
-     * The session endpoint and projectId are used for validation but not merged
-     * since they should match the config's values.
-     *
-     * @param config - Base configuration to merge session into
-     * @param session - Session authentication information
-     * @returns New configuration object with session merged (input config is not mutated)
-     *
-     * @example
-     * ```typescript
-     * const configWithSession = mergeService.mergeSession(config, {
-     *   projectId: "my-project",
-     *   endpoint: "https://cloud.appwrite.io/v1",
-     *   sessionCookie: "eyJhbGc...",
-     *   email: "user@example.com"
-     * });
-     * ```
-     */
-    mergeSession(config, session) {
-        // Clone config to avoid mutation
-        const merged = cloneDeep(config);
-        // Add session authentication (map 'cookie' to 'sessionCookie')
-        merged.sessionCookie = session.cookie;
-        // Set authMethod to session (priority handled by ClientFactory)
-        merged.authMethod = "session";
-        // Add session metadata if available
-        if (session.email || session.expiresAt) {
-            merged.sessionMetadata = {
-                email: session.email,
-                expiresAt: session.expiresAt,
-            };
-        }
-        return merged;
-    }
-    /**
-     * Applies configuration overrides from CLI arguments or programmatic sources.
-     *
-     * @description
-     * Applies high-priority overrides that take precedence over all other config sources.
-     * Only applies values that are explicitly set (not undefined or null).
-     *
-     * This method is typically used to apply CLI arguments like:
-     * - --endpoint
-     * - --apiKey
-     * - --project
-     *
-     * @param config - Base configuration to apply overrides to
-     * @param overrides - Override values to apply
-     * @returns New configuration object with overrides applied (input config is not mutated)
-     *
-     * @example
-     * ```typescript
-     * const overriddenConfig = mergeService.applyOverrides(config, {
-     *   appwriteEndpoint: 'https://custom.appwrite.io/v1',
-     *   appwriteKey: 'my-api-key',
-     *   authMethod: 'apikey'
-     * });
-     * ```
-     */
-    applyOverrides(config, overrides) {
-        // Clone config to avoid mutation
-        const merged = cloneDeep(config);
-        // Apply each override only if it has a value (not undefined/null)
-        if (overrides.appwriteEndpoint !== undefined && overrides.appwriteEndpoint !== null) {
-            merged.appwriteEndpoint = overrides.appwriteEndpoint;
-        }
-        if (overrides.appwriteProject !== undefined && overrides.appwriteProject !== null) {
-            merged.appwriteProject = overrides.appwriteProject;
-        }
-        if (overrides.appwriteKey !== undefined && overrides.appwriteKey !== null) {
-            merged.appwriteKey = overrides.appwriteKey;
-        }
-        if (overrides.sessionCookie !== undefined && overrides.sessionCookie !== null) {
-            merged.sessionCookie = overrides.sessionCookie;
-        }
-        if (overrides.authMethod !== undefined && overrides.authMethod !== null) {
-            merged.authMethod = overrides.authMethod;
-        }
-        return merged;
-    }
-    /**
-     * Merges environment variables into the configuration.
-     *
-     * @description
-     * Reads environment variables and merges them into the config with the lowest priority.
-     * Only applies environment variables that are set and have non-empty values.
-     *
-     * Supported environment variables:
-     * - APPWRITE_ENDPOINT: Appwrite API endpoint URL
-     * - APPWRITE_PROJECT: Appwrite project ID
-     * - APPWRITE_API_KEY: API key for authentication
-     * - APPWRITE_SESSION_COOKIE: Session cookie for authentication
-     *
-     * Environment variables are only applied if the corresponding config value is not already set.
-     *
-     * @param config - Base configuration to merge environment variables into
-     * @returns New configuration object with environment variables merged (input config is not mutated)
-     *
-     * @example
-     * ```typescript
-     * // With env vars: APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
-     * const configWithEnv = mergeService.mergeEnvironmentVariables(config);
-     * // configWithEnv.appwriteEndpoint will be set from env var if not already set
-     * ```
-     */
-    mergeEnvironmentVariables(config) {
-        // Clone config to avoid mutation
-        const merged = cloneDeep(config);
-        // Read environment variables
-        const envEndpoint = process.env.APPWRITE_ENDPOINT;
-        const envProject = process.env.APPWRITE_PROJECT;
-        const envApiKey = process.env.APPWRITE_API_KEY;
-        const envSessionCookie = process.env.APPWRITE_SESSION_COOKIE;
-        // Apply environment variables only if not already set in config
-        // Environment variables have the lowest priority
-        if (envEndpoint && !merged.appwriteEndpoint) {
-            merged.appwriteEndpoint = envEndpoint;
-        }
-        if (envProject && !merged.appwriteProject) {
-            merged.appwriteProject = envProject;
-        }
-        if (envApiKey && !merged.appwriteKey) {
-            merged.appwriteKey = envApiKey;
-        }
-        if (envSessionCookie && !merged.sessionCookie) {
-            merged.sessionCookie = envSessionCookie;
-        }
-        return merged;
-    }
-    /**
-     * Performs a deep merge of multiple partial configuration sources into a complete configuration.
-     *
-     * @description
-     * Merges multiple configuration sources using a deep merge strategy that:
-     * - Recursively merges nested objects
-     * - Preserves array order (arrays are replaced, not merged)
-     * - Skips undefined and null values (they don't overwrite existing values)
-     * - Later sources in the array take precedence over earlier ones
-     *
-     * This method is useful when combining:
-     * - Base defaults with file-based config
-     * - Multiple configuration files
-     * - Config fragments from different sources
-     *
-     * @param sources - Array of partial configurations to merge (order matters: later sources override earlier ones)
-     * @returns Complete merged configuration object
-     *
-     * @throws {Error} If no valid configuration can be produced from the sources
-     *
-     * @example
-     * ```typescript
-     * const merged = mergeService.mergeSources([
-     *   envConfig,           // Lowest priority
-     *   fileConfig,          // Medium priority
-     *   sessionConfig,       // Higher priority
-     *   overrideConfig       // Highest priority
-     * ]);
-     * ```
-     */
-    mergeSources(sources) {
-        // Filter out undefined/null sources
-        const validSources = sources.filter((source) => source !== undefined && source !== null);
-        if (validSources.length === 0) {
-            throw new Error("No valid configuration sources provided for merging");
-        }
-        // Start with an empty base object
-        let merged = {};
-        // Merge each source in order (later sources override earlier ones)
-        for (const source of validSources) {
-            merged = this.deepMergeConfigs(merged, source);
-        }
-        // Validate that we have the minimum required fields
-        if (!merged.appwriteEndpoint || !merged.appwriteProject) {
-            throw new Error("Merged configuration is missing required fields: appwriteEndpoint and/or appwriteProject");
-        }
-        return merged;
-    }
-    /**
-     * Internal helper for deep merging two configuration objects.
-     *
-     * @description
-     * Performs a deep merge of two objects with special handling for:
-     * - Plain objects: Recursively merged
-     * - Arrays: Target array is replaced by source array (not merged)
-     * - Undefined/null values in source: Skipped (don't overwrite target)
-     * - Primitive values: Source overwrites target
-     *
-     * This is used internally by mergeSources but can also be used directly
-     * for specific merge operations.
-     *
-     * @param target - Base configuration object
-     * @param source - Configuration to merge into target
-     * @returns New deeply merged configuration object
-     *
-     * @private
-     */
-    deepMergeConfigs(target, source) {
-        // Clone target to avoid mutation
-        const result = cloneDeep(target);
-        // Iterate through source properties
-        for (const key in source) {
-            if (!Object.prototype.hasOwnProperty.call(source, key)) {
-                continue;
-            }
-            const sourceValue = source[key];
-            const targetValue = result[key];
-            // Skip undefined and null values from source
-            if (sourceValue === undefined || sourceValue === null) {
-                continue;
-            }
-            // Handle arrays: Replace target array with source array (don't merge)
-            if (Array.isArray(sourceValue)) {
-                result[key] = cloneDeep(sourceValue);
-                continue;
-            }
-            // Handle plain objects: Recursively merge
-            if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
-                result[key] = this.deepMergeConfigs(targetValue, sourceValue);
-                continue;
-            }
-            // For all other cases (primitives, etc.), source overwrites target
-            result[key] = cloneDeep(sourceValue);
-        }
-        return result;
-    }
-    /**
-     * Creates a configuration by merging all sources in the correct priority order.
-     *
-     * @description
-     * Convenience method that applies the full configuration merge pipeline:
-     * 1. Start with base config (from file)
-     * 2. Merge environment variables (lowest priority)
-     * 3. Merge session information (if provided)
-     * 4. Apply CLI/programmatic overrides (highest priority)
-     *
-     * This is the recommended way to build a final configuration from all sources.
-     *
-     * @param baseConfig - Configuration loaded from file (YAML/TS/JSON)
-     * @param options - Optional merge options
-     * @param options.session - Session authentication to merge
-     * @param options.overrides - CLI/programmatic overrides to apply
-     * @param options.includeEnv - Whether to include environment variables (default: true)
-     * @returns Final merged configuration with all sources applied in priority order
-     *
-     * @example
-     * ```typescript
-     * const finalConfig = mergeService.mergeAllSources(fileConfig, {
-     *   session: sessionInfo,
-     *   overrides: cliOverrides,
-     *   includeEnv: true
-     * });
-     * ```
-     */
-    mergeAllSources(baseConfig, options = {}) {
-        const { session, overrides, includeEnv = true } = options;
-        // Start with base config
-        let config = cloneDeep(baseConfig);
-        // Step 1: Merge environment variables (lowest priority)
-        if (includeEnv) {
-            config = this.mergeEnvironmentVariables(config);
-        }
-        // Step 2: Merge session (medium-high priority)
-        if (session) {
-            config = this.mergeSession(config, session);
-        }
-        // Step 3: Apply overrides (highest priority)
-        if (overrides) {
-            config = this.applyOverrides(config, overrides);
-        }
-        return config;
-    }
-}