appwrite-utils-cli
Version:
Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.
215 lines (214 loc) • 7.22 kB
TypeScript
import type { AppwriteConfig } from "appwrite-utils";
import { type ValidationError as BaseValidationError } from "../configValidation.js";
/**
* Re-export types from configValidation for convenience
*/
export type ValidationError = BaseValidationError;
/**
* Warning-level validation issue (non-blocking)
*/
export interface ValidationWarning extends BaseValidationError {
severity: "warning";
}
/**
* Complete validation result including errors, warnings, and suggestions
*/
export interface ValidationResult {
isValid: boolean;
errors: ValidationError[];
warnings: ValidationWarning[];
suggestions?: ValidationError[];
}
/**
* Options for validation reporting
*/
export interface ValidationReportOptions {
/**
* Include detailed information in the report
* @default false
*/
verbose?: boolean;
/**
* Suppress console output (only log to file)
* @default false
*/
silent?: boolean;
/**
* Exit process if validation fails
* @default false
*/
exitOnError?: boolean;
}
/**
* Service for validating Appwrite configuration with support for multiple validation modes
*
* This service provides centralized configuration validation with:
* - Standard validation (warnings allowed)
* - Strict validation (warnings treated as errors)
* - Detailed error reporting with suggestions
* - Configurable output verbosity
*
* @example
* ```typescript
* const validationService = new ConfigValidationService();
*
* // Standard validation
* const result = validationService.validate(config);
* if (!result.isValid) {
* validationService.reportResults(result, { verbose: true });
* }
*
* // Strict validation (warnings become errors)
* const strictResult = validationService.validateStrict(config);
* if (!strictResult.isValid) {
* throw new Error("Configuration validation failed in strict mode");
* }
* ```
*/
export declare class ConfigValidationService {
/**
* Validate configuration with standard rules
*
* Standard validation allows warnings - the configuration is considered valid
* even if warnings are present. Only errors cause validation to fail.
*
* Validation checks include:
* - Basic structure validation (required fields, array structure)
* - Naming conflict detection (collections vs tables)
* - Database reference validation
* - Schema consistency validation
* - Duplicate definition detection
*
* @param config - Appwrite configuration to validate
* @returns Validation result with errors, warnings, and suggestions
*
* @example
* ```typescript
* const result = validationService.validate(config);
*
* if (result.isValid) {
* console.log("Configuration is valid");
* if (result.warnings.length > 0) {
* console.log(`Found ${result.warnings.length} warnings`);
* }
* } else {
* console.error(`Configuration has ${result.errors.length} errors`);
* }
* ```
*/
validate(config: AppwriteConfig): ValidationResult;
/**
* Validate configuration with strict rules
*
* Strict validation treats all warnings as errors. This is useful for:
* - CI/CD pipelines (fail builds on any issues)
* - Production deployments (ensure highest quality)
* - Configuration audits (enforce best practices)
*
* All warnings are promoted to errors, so the configuration is only
* considered valid if there are zero warnings and zero errors.
*
* @param config - Appwrite configuration to validate
* @returns Validation result with promoted warnings as errors
*
* @example
* ```typescript
* const result = validationService.validateStrict(config);
*
* if (!result.isValid) {
* console.error("Configuration failed strict validation");
* result.errors.forEach(err => {
* console.error(` - ${err.message}`);
* });
* process.exit(1);
* }
* ```
*/
validateStrict(config: AppwriteConfig): ValidationResult;
/**
* Report validation results to console with formatted output
*
* Provides user-friendly formatting of validation results:
* - Color-coded output (errors in red, warnings in yellow, etc.)
* - Detailed error descriptions with suggestions
* - Affected items listing
* - Optional verbose mode for additional details
*
* @param validation - Validation result to report
* @param options - Reporting options (verbose, silent, exitOnError)
*
* @example
* ```typescript
* const result = validationService.validate(config);
*
* // Basic reporting
* validationService.reportResults(result);
*
* // Verbose reporting with all details
* validationService.reportResults(result, { verbose: true });
*
* // Report and exit on error (useful for scripts)
* validationService.reportResults(result, { exitOnError: true });
* ```
*/
reportResults(validation: ValidationResult, options?: ValidationReportOptions): void;
/**
* Validate and report in a single call
*
* Convenience method that combines validation and reporting.
* Useful for quick validation checks in CLI commands.
*
* @param config - Appwrite configuration to validate
* @param strict - Use strict validation mode
* @param reportOptions - Reporting options
* @returns Validation result
*
* @example
* ```typescript
* // Quick validation with reporting
* const result = validationService.validateAndReport(config, false, {
* verbose: true,
* exitOnError: true
* });
* ```
*/
validateAndReport(config: AppwriteConfig, strict?: boolean, reportOptions?: ValidationReportOptions): ValidationResult;
/**
* Check if configuration is valid without detailed reporting
*
* Quick validation check that returns a simple boolean.
* Useful for conditional logic where you don't need detailed error information.
*
* @param config - Appwrite configuration to validate
* @param strict - Use strict validation mode
* @returns true if configuration is valid, false otherwise
*
* @example
* ```typescript
* if (validationService.isValid(config)) {
* // Proceed with configuration
* } else {
* // Show error and prompt for correction
* }
* ```
*/
isValid(config: AppwriteConfig, strict?: boolean): boolean;
/**
* Get a summary of validation results as a formatted string
*
* Returns a human-readable summary of validation results suitable for
* logging or display in UIs.
*
* @param validation - Validation result to summarize
* @returns Formatted summary string
*
* @example
* ```typescript
* const result = validationService.validate(config);
* const summary = validationService.getSummary(result);
* console.log(summary);
* // Output: "Configuration valid with 2 warnings, 1 suggestion"
* ```
*/
getSummary(validation: ValidationResult): string;
}