@asyncapi/cli 4.1.1 → 5.0.1

package/lib/interfaces/index.d.ts

@@ -1,22 +1,37 @@
-import { AsyncAPIDocumentInterface } from '@asyncapi/parser/cjs';
+import { AsyncAPIDocumentInterface, Diagnostic } from '@asyncapi/parser/cjs';
 import { OutputFormat } from '@stoplight/spectral-cli/dist/services/config';
+/**
+ * Supported diagnostic output formats for validation results.
+ */
 export type DiagnosticsFormat = 'stylish' | 'json' | 'junit' | 'html' | 'text' | 'teamcity' | 'pretty';
+/**
+ * Severity levels for validation diagnostics.
+ */
 export type SeverityKind = 'error' | 'warn' | 'info' | 'hint';
+/**
+ * Adapter type for CLI or API usage.
+ */
 export type Adapter = 'cli' | 'api';
 import specs from '@asyncapi/specs';
 import { Router } from 'express';
 import { AsyncAPIConvertVersion } from '@asyncapi/converter';
+/**
+ * Controller interface for Express routers.
+ */
 export interface Controller {
     basepath: string;
     boot(): Router | Promise<Router>;
 }
+/**
+ * RFC 7807 Problem Details object.
+ */
 export interface Problem {
     type: string;
     title: string;
     status: number;
     detail?: string;
     instance?: string;
-    [key: string]: any;
+    [key: string]: string | number | undefined;
 }
 export type AsyncAPIDocument = {
     asyncapi: string;
@@ -28,17 +43,28 @@ export interface AsyncAPIServiceOptions {
     source?: string;
     path?: string;
 }
-export interface ServiceResult<T = any> {
+/**
+ * Standard service result wrapper for consistent response handling.
+ *
+ * @template T - The type of data returned on success
+ */
+export interface ServiceResult<T = unknown> {
     success: boolean;
     data?: T;
     error?: string;
-    diagnostics?: any[];
+    diagnostics?: Diagnostic[];
 }
+/**
+ * Result of parsing an AsyncAPI document.
+ */
 export interface ParsedDocument {
     document: AsyncAPIDocumentInterface;
-    diagnostics: any[];
+    diagnostics: Diagnostic[];
     status: 'valid' | 'invalid';
 }
+/**
+ * Options for document validation.
+ */
 export interface ValidationOptions {
     'log-diagnostics'?: boolean;
     'diagnostics-format'?: `${OutputFormat}`;
@@ -47,10 +73,13 @@ export interface ValidationOptions {
     suppressWarnings?: string[];
     suppressAllWarnings?: boolean;
 }
+/**
+ * Result of document validation.
+ */
 export interface ValidationResult {
     status: 'valid' | 'invalid';
     document?: AsyncAPIDocument;
-    diagnostics?: any[];
+    diagnostics?: Diagnostic[];
     score?: number;
 }
 export interface ConversionOptions {
@@ -62,24 +91,37 @@ export interface ConversionResult {
     convertedDocument: string;
     originalFormat: string;
 }
+/**
+ * Base URL mapping configuration for template generation.
+ */
 export interface IMapBaseUrlToFlag {
     url: string;
     folder: string;
 }
+/**
+ * Configuration for npm registry authentication.
+ */
+export interface RegistryConfig {
+    url?: string;
+    auth?: string;
+    token?: string;
+}
+/**
+ * Options for code generation from AsyncAPI documents.
+ */
 export interface GenerationOptions {
-    templateParams?: Record<string, any>;
+    templateParams?: Record<string, unknown>;
     forceWrite?: boolean;
     install?: boolean;
     debug?: boolean;
     noOverwriteGlobs?: string[];
     disabledHooks?: Record<string, string>;
     mapBaseUrl?: IMapBaseUrlToFlag;
-    registry?: {
-        url?: string;
-        auth?: string;
-        token?: string;
-    };
+    registry?: RegistryConfig;
 }
+/**
+ * Result of a code generation operation.
+ */
 export interface GenerationResult {
     success: boolean;
     outputPath: string;

package/lib/utils/error-handler.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Error handling utilities for consistent error management across the CLI and API.
+ * Provides type-safe error handling and standardized error messages.
+ */
+/**
+ * Extracts a safe error message from any caught error.
+ * Handles various error types including Error objects, strings, and unknown types.
+ *
+ * @param error - The caught error (can be any type)
+ * @param fallbackMessage - Default message if error cannot be parsed
+ * @returns A string error message
+ *
+ * @example
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   const message = getErrorMessage(error, 'Operation failed');
+ *   console.error(message);
+ * }
+ */
+export declare function getErrorMessage(error: unknown, fallbackMessage?: string): string;
+/**
+ * Extracts the error stack trace if available.
+ *
+ * @param error - The caught error
+ * @returns Stack trace string or undefined
+ */
+export declare function getErrorStack(error: unknown): string | undefined;
+/**
+ * Type guard to check if a value is an Error instance.
+ *
+ * @param value - Value to check
+ * @returns True if value is an Error
+ */
+export declare function isError(value: unknown): value is Error;
+/**
+ * Type guard to check if an error has a specific code property.
+ * Useful for Node.js system errors (ENOENT, EACCES, etc.)
+ *
+ * @param error - The error to check
+ * @param code - The error code to match
+ * @returns True if error has the specified code
+ *
+ * @example
+ * try {
+ *   await fs.readFile(path);
+ * } catch (error) {
+ *   if (hasErrorCode(error, 'ENOENT')) {
+ *     console.log('File not found');
+ *   }
+ * }
+ */
+export declare function hasErrorCode(error: unknown, code: string): boolean;
+/**
+ * Wraps an async function to catch and transform errors.
+ * Useful for standardizing error handling in command handlers.
+ *
+ * @param fn - Async function to wrap
+ * @param errorHandler - Function to handle caught errors
+ * @returns Wrapped function
+ *
+ * @example
+ * const safeRun = withErrorHandling(
+ *   async () => await riskyOperation(),
+ *   (error) => console.error('Failed:', getErrorMessage(error))
+ * );
+ */
+export declare function withErrorHandling<T, Args extends unknown[]>(fn: (...args: Args) => Promise<T>, errorHandler: (error: unknown) => void): (...args: Args) => Promise<T | undefined>;
+/**
+ * Creates a typed error result for service functions.
+ * Alternative to throwing errors - returns a result object instead.
+ */
+export interface ErrorResult {
+    success: false;
+    error: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}
+export interface SuccessResult<T> {
+    success: true;
+    data: T;
+}
+export type Result<T> = SuccessResult<T> | ErrorResult;
+/**
+ * Creates a success result.
+ */
+export declare function success<T>(data: T): SuccessResult<T>;
+/**
+ * Creates an error result.
+ */
+export declare function failure(error: string, code?: string, details?: Record<string, unknown>): ErrorResult;
+/**
+ * Creates an error result from a caught error.
+ */
+export declare function failureFromError(error: unknown, fallbackMessage?: string): ErrorResult;

package/lib/utils/error-handler.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Error handling utilities for consistent error management across the CLI and API.
+ * Provides type-safe error handling and standardized error messages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getErrorMessage = getErrorMessage;
+exports.getErrorStack = getErrorStack;
+exports.isError = isError;
+exports.hasErrorCode = hasErrorCode;
+exports.withErrorHandling = withErrorHandling;
+exports.success = success;
+exports.failure = failure;
+exports.failureFromError = failureFromError;
+const tslib_1 = require("tslib");
+/**
+ * Extracts a safe error message from any caught error.
+ * Handles various error types including Error objects, strings, and unknown types.
+ *
+ * @param error - The caught error (can be any type)
+ * @param fallbackMessage - Default message if error cannot be parsed
+ * @returns A string error message
+ *
+ * @example
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   const message = getErrorMessage(error, 'Operation failed');
+ *   console.error(message);
+ * }
+ */
+function getErrorMessage(error, fallbackMessage = 'An unknown error occurred') {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String(error.message);
+    }
+    return fallbackMessage;
+}
+/**
+ * Extracts the error stack trace if available.
+ *
+ * @param error - The caught error
+ * @returns Stack trace string or undefined
+ */
+function getErrorStack(error) {
+    if (error instanceof Error) {
+        return error.stack;
+    }
+    return undefined;
+}
+/**
+ * Type guard to check if a value is an Error instance.
+ *
+ * @param value - Value to check
+ * @returns True if value is an Error
+ */
+function isError(value) {
+    return value instanceof Error;
+}
+/**
+ * Type guard to check if an error has a specific code property.
+ * Useful for Node.js system errors (ENOENT, EACCES, etc.)
+ *
+ * @param error - The error to check
+ * @param code - The error code to match
+ * @returns True if error has the specified code
+ *
+ * @example
+ * try {
+ *   await fs.readFile(path);
+ * } catch (error) {
+ *   if (hasErrorCode(error, 'ENOENT')) {
+ *     console.log('File not found');
+ *   }
+ * }
+ */
+function hasErrorCode(error, code) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'code' in error &&
+        error.code === code);
+}
+/**
+ * Wraps an async function to catch and transform errors.
+ * Useful for standardizing error handling in command handlers.
+ *
+ * @param fn - Async function to wrap
+ * @param errorHandler - Function to handle caught errors
+ * @returns Wrapped function
+ *
+ * @example
+ * const safeRun = withErrorHandling(
+ *   async () => await riskyOperation(),
+ *   (error) => console.error('Failed:', getErrorMessage(error))
+ * );
+ */
+function withErrorHandling(fn, errorHandler) {
+    return (...args) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+        try {
+            return yield fn(...args);
+        }
+        catch (error) {
+            errorHandler(error);
+            return undefined;
+        }
+    });
+}
+/**
+ * Creates a success result.
+ */
+function success(data) {
+    return { success: true, data };
+}
+/**
+ * Creates an error result.
+ */
+function failure(error, code, details) {
+    return { success: false, error, code, details };
+}
+/**
+ * Creates an error result from a caught error.
+ */
+function failureFromError(error, fallbackMessage = 'An unknown error occurred') {
+    return {
+        success: false,
+        error: getErrorMessage(error, fallbackMessage),
+        details: isError(error) ? { stack: error.stack } : undefined,
+    };
+}

package/lib/utils/proxy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Utility functions for proxy configuration.
+ * Centralizes proxy URL handling to avoid code duplication across commands.
+ */
+/**
+ * Applies proxy configuration to a file path or URL.
+ * If both proxyHost and proxyPort are provided, appends the proxy URL to the path.
+ *
+ * @param filePath - The original file path or URL
+ * @param proxyHost - The proxy host name (optional)
+ * @param proxyPort - The proxy port number (optional)
+ * @returns The file path with proxy configuration appended, or the original path
+ *
+ * @example
+ * applyProxyToPath('./asyncapi.yaml', 'localhost', '8080')
+ * // Returns: './asyncapi.yaml+http://localhost:8080'
+ *
+ * applyProxyToPath('./asyncapi.yaml')
+ * // Returns: './asyncapi.yaml'
+ */
+export declare function applyProxyToPath(filePath: string | undefined, proxyHost?: string, proxyPort?: string | number): string | undefined;
+/**
+ * Builds a proxy URL from host and port.
+ *
+ * @param proxyHost - The proxy host name
+ * @param proxyPort - The proxy port number
+ * @returns The proxy URL or undefined if either parameter is missing
+ */
+export declare function buildProxyUrl(proxyHost?: string, proxyPort?: string | number): string | undefined;

package/lib/utils/proxy.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Utility functions for proxy configuration.
+ * Centralizes proxy URL handling to avoid code duplication across commands.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyProxyToPath = applyProxyToPath;
+exports.buildProxyUrl = buildProxyUrl;
+/**
+ * Applies proxy configuration to a file path or URL.
+ * If both proxyHost and proxyPort are provided, appends the proxy URL to the path.
+ *
+ * @param filePath - The original file path or URL
+ * @param proxyHost - The proxy host name (optional)
+ * @param proxyPort - The proxy port number (optional)
+ * @returns The file path with proxy configuration appended, or the original path
+ *
+ * @example
+ * applyProxyToPath('./asyncapi.yaml', 'localhost', '8080')
+ * // Returns: './asyncapi.yaml+http://localhost:8080'
+ *
+ * applyProxyToPath('./asyncapi.yaml')
+ * // Returns: './asyncapi.yaml'
+ */
+function applyProxyToPath(filePath, proxyHost, proxyPort) {
+    if (!filePath) {
+        return filePath;
+    }
+    if (proxyHost && proxyPort) {
+        const proxyUrl = `http://${proxyHost}:${proxyPort}`;
+        return `${filePath}+${proxyUrl}`;
+    }
+    return filePath;
+}
+/**
+ * Builds a proxy URL from host and port.
+ *
+ * @param proxyHost - The proxy host name
+ * @param proxyPort - The proxy port number
+ * @returns The proxy URL or undefined if either parameter is missing
+ */
+function buildProxyUrl(proxyHost, proxyPort) {
+    if (proxyHost && proxyPort) {
+        return `http://${proxyHost}:${proxyPort}`;
+    }
+    return undefined;
+}

package/lib/utils/validation.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Input validation utilities for CLI commands and API endpoints.
+ * Provides reusable validation functions with consistent error messages.
+ */
+/**
+ * Validates that a file path is provided and not empty.
+ *
+ * @param filePath - The file path to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result with error message if invalid
+ */
+export declare function validateFilePath(filePath: string | undefined, fieldName?: string): {
+    valid: true;
+    value: string;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validates that a value is one of the allowed options.
+ *
+ * @param value - The value to validate
+ * @param allowedValues - Array of allowed values
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result
+ */
+export declare function validateEnum<T extends string>(value: string | undefined, allowedValues: readonly T[], fieldName?: string): {
+    valid: true;
+    value: T;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validates that a port number is valid.
+ *
+ * @param port - The port to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result
+ */
+export declare function validatePort(port: string | number | undefined, fieldName?: string): {
+    valid: true;
+    value: number;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validates a URL string.
+ *
+ * @param url - The URL to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result
+ */
+export declare function validateUrl(url: string | undefined, fieldName?: string): {
+    valid: true;
+    value: string;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validates that a value is a non-empty string.
+ *
+ * @param value - The value to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result
+ */
+export declare function validateNonEmptyString(value: string | undefined, fieldName?: string): {
+    valid: true;
+    value: string;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validates that a version string matches semantic versioning pattern.
+ *
+ * @param version - The version string to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result
+ */
+export declare function validateVersion(version: string | undefined, fieldName?: string): {
+    valid: true;
+    value: string;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Type guard to check if a value is defined (not null or undefined).
+ *
+ * @param value - Value to check
+ * @returns True if value is defined
+ */
+export declare function isDefined<T>(value: T | null | undefined): value is T;
+/**
+ * Type guard to check if a value is a non-empty array.
+ *
+ * @param value - Value to check
+ * @returns True if value is a non-empty array
+ */
+export declare function isNonEmptyArray<T>(value: T[] | null | undefined): value is [T, ...T[]];

package/lib/utils/validation.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Input validation utilities for CLI commands and API endpoints.
+ * Provides reusable validation functions with consistent error messages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateFilePath = validateFilePath;
+exports.validateEnum = validateEnum;
+exports.validatePort = validatePort;
+exports.validateUrl = validateUrl;
+exports.validateNonEmptyString = validateNonEmptyString;
+exports.validateVersion = validateVersion;
+exports.isDefined = isDefined;
+exports.isNonEmptyArray = isNonEmptyArray;
+/**
+ * Validates that a file path is provided and not empty.
+ *
+ * @param filePath - The file path to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result with error message if invalid
+ */
+function validateFilePath(filePath, fieldName = 'file path') {
+    if (!filePath || filePath.trim() === '') {
+        return {
+            valid: false,
+            error: `${fieldName} is required and cannot be empty`,
+        };
+    }
+    return { valid: true, value: filePath.trim() };
+}
+/**
+ * Validates that a value is one of the allowed options.
+ *
+ * @param value - The value to validate
+ * @param allowedValues - Array of allowed values
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result
+ */
+function validateEnum(value, allowedValues, fieldName = 'value') {
+    if (!value) {
+        return {
+            valid: false,
+            error: `${fieldName} is required`,
+        };
+    }
+    if (!allowedValues.includes(value)) {
+        return {
+            valid: false,
+            error: `${fieldName} must be one of: ${allowedValues.join(', ')}`,
+        };
+    }
+    return { valid: true, value: value };
+}
+/**
+ * Validates that a port number is valid.
+ *
+ * @param port - The port to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result
+ */
+function validatePort(port, fieldName = 'port') {
+    if (port === undefined || port === '') {
+        return {
+            valid: false,
+            error: `${fieldName} is required`,
+        };
+    }
+    const portNum = typeof port === 'string' ? parseInt(port, 10) : port;
+    if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+        return {
+            valid: false,
+            error: `${fieldName} must be a valid port number (1-65535)`,
+        };
+    }
+    return { valid: true, value: portNum };
+}
+/**
+ * Validates a URL string.
+ *
+ * @param url - The URL to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result
+ */
+function validateUrl(url, fieldName = 'URL') {
+    if (!url || url.trim() === '') {
+        return {
+            valid: false,
+            error: `${fieldName} is required`,
+        };
+    }
+    try {
+        new URL(url);
+        return { valid: true, value: url };
+    }
+    catch (_a) {
+        return {
+            valid: false,
+            error: `${fieldName} is not a valid URL`,
+        };
+    }
+}
+/**
+ * Validates that a value is a non-empty string.
+ *
+ * @param value - The value to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result
+ */
+function validateNonEmptyString(value, fieldName = 'value') {
+    if (!value || value.trim() === '') {
+        return {
+            valid: false,
+            error: `${fieldName} is required and cannot be empty`,
+        };
+    }
+    return { valid: true, value: value.trim() };
+}
+/**
+ * Validates that a version string matches semantic versioning pattern.
+ *
+ * @param version - The version string to validate
+ * @param fieldName - Name of the field for error messages
+ * @returns Validation result
+ */
+function validateVersion(version, fieldName = 'version') {
+    if (!version) {
+        return {
+            valid: false,
+            error: `${fieldName} is required`,
+        };
+    }
+    // Matches patterns like 1.0.0, 2.0.0, 3.0.0, etc.
+    const semverPattern = /^\d+\.\d+\.\d+$/;
+    if (!semverPattern.test(version)) {
+        return {
+            valid: false,
+            error: `${fieldName} must be a valid semantic version (e.g., 3.0.0)`,
+        };
+    }
+    return { valid: true, value: version };
+}
+/**
+ * Type guard to check if a value is defined (not null or undefined).
+ *
+ * @param value - Value to check
+ * @returns True if value is defined
+ */
+function isDefined(value) {
+    return value !== null && value !== undefined;
+}
+/**
+ * Type guard to check if a value is a non-empty array.
+ *
+ * @param value - Value to check
+ * @returns True if value is a non-empty array
+ */
+function isNonEmptyArray(value) {
+    return Array.isArray(value) && value.length > 0;
+}