obsidian-mcp-server 1.5.8 → 2.0.2

package/dist/utils/index.d.ts

@@ -1,8 +1,5 @@
-/**
- * Exports all utility functions and classes
- */
-export * from './errors.js';
-export * from './logging.js';
-export * from './rate-limiting.js';
-export * from './tokenization.js';
-export * from './validation.js';
+export * from "./internal/index.js";
+export * from "./parsing/index.js";
+export * from "./security/index.js";
+export * from "./metrics/index.js";
+export * from "./obsidian/index.js";

package/dist/utils/index.js

@@ -1,9 +1,13 @@
-/**
- * Exports all utility functions and classes
- */
-export * from './errors.js';
-export * from './logging.js';
-export * from './rate-limiting.js';
-export * from './tokenization.js';
-export * from './validation.js';
-//# sourceMappingURL=index.js.map
+// Re-export all utilities from their categorized subdirectories
+export * from "./internal/index.js";
+export * from "./parsing/index.js";
+export * from "./security/index.js";
+export * from "./metrics/index.js";
+export * from "./obsidian/index.js"; // Added export for obsidian utils
+// It's good practice to have index.ts files in each subdirectory
+// that export the contents of that directory.
+// Assuming those will be created or already exist.
+// If not, this might need adjustment to export specific files, e.g.:
+// export * from './internal/errorHandler.js';
+// export * from './internal/logger.js';
+// ... etc.

package/dist/utils/internal/asyncUtils.d.ts

@@ -0,0 +1,54 @@
+import { RequestContext } from "./requestContext.js";
+/**
+ * Configuration for the {@link retryWithDelay} function, defining how retries are handled.
+ */
+export interface RetryConfig<T> {
+    /**
+     * A descriptive name for the operation being retried. Used in logging.
+     * Example: "FetchUserData", "ProcessPayment".
+     */
+    operationName: string;
+    /**
+     * The request context associated with the operation, for logging and tracing.
+     */
+    context: RequestContext;
+    /**
+     * The maximum number of retry attempts before failing.
+     */
+    maxRetries: number;
+    /**
+     * The delay in milliseconds between retry attempts.
+     */
+    delayMs: number;
+    /**
+     * An optional function to determine if a retry should be attempted based on the error.
+     * If not provided, retries will be attempted for any error.
+     * @param error - The error that occurred during the operation.
+     * @returns `true` if a retry should be attempted, `false` otherwise.
+     */
+    shouldRetry?: (error: unknown) => boolean;
+    /**
+     * An optional function to execute before each retry attempt.
+     * Useful for custom logging or cleanup actions.
+     * @param attempt - The current retry attempt number.
+     * @param error - The error that triggered the retry.
+     */
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+/**
+ * Executes an asynchronous operation with a configurable retry mechanism.
+ * This function will attempt the operation up to `maxRetries` times, with a specified
+ * `delayMs` between attempts. It allows for custom logic to decide if an error
+ * warrants a retry and for actions to be taken before each retry.
+ *
+ * @template T The expected return type of the asynchronous operation.
+ * @param {() => Promise<T>} operation - The asynchronous function to execute.
+ *   This function should return a Promise resolving to type `T`.
+ * @param {RetryConfig<T>} config - Configuration options for the retry behavior,
+ *   including operation name, context, retry limits, delay, and custom handlers.
+ * @returns {Promise<T>} A promise that resolves with the result of the operation if successful.
+ * @throws {McpError} Throws an `McpError` if the operation fails after all retry attempts,
+ *   or if an unexpected error occurs during the retry logic. The error will contain details
+ *   about the operation name, context, and the last encountered error.
+ */
+export declare function retryWithDelay<T>(operation: () => Promise<T>, config: RetryConfig<T>): Promise<T>;

package/dist/utils/internal/asyncUtils.js

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview Provides utilities for handling asynchronous operations,
+ * such as retrying operations with delays.
+ * @module src/utils/internal/asyncUtils
+ */
+import { McpError, BaseErrorCode } from "../../types-global/errors.js";
+import { logger } from "./logger.js";
+/**
+ * Executes an asynchronous operation with a configurable retry mechanism.
+ * This function will attempt the operation up to `maxRetries` times, with a specified
+ * `delayMs` between attempts. It allows for custom logic to decide if an error
+ * warrants a retry and for actions to be taken before each retry.
+ *
+ * @template T The expected return type of the asynchronous operation.
+ * @param {() => Promise<T>} operation - The asynchronous function to execute.
+ *   This function should return a Promise resolving to type `T`.
+ * @param {RetryConfig<T>} config - Configuration options for the retry behavior,
+ *   including operation name, context, retry limits, delay, and custom handlers.
+ * @returns {Promise<T>} A promise that resolves with the result of the operation if successful.
+ * @throws {McpError} Throws an `McpError` if the operation fails after all retry attempts,
+ *   or if an unexpected error occurs during the retry logic. The error will contain details
+ *   about the operation name, context, and the last encountered error.
+ */
+export async function retryWithDelay(operation, config) {
+    const { operationName, context, maxRetries, delayMs, shouldRetry = () => true, // Default: retry on any error
+    onRetry, } = config;
+    let lastError;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            // Ensure the context for logging includes attempt details
+            const retryAttemptContext = {
+                ...context, // Spread existing context
+                operation: operationName, // Ensure operationName is part of the context for logger
+                attempt,
+                maxRetries,
+                lastError: error instanceof Error ? error.message : String(error),
+            };
+            if (attempt < maxRetries && shouldRetry(error)) {
+                if (onRetry) {
+                    onRetry(attempt, error); // Custom onRetry logic
+                }
+                else {
+                    // Default logging for retry attempt
+                    logger.warning(`Operation '${operationName}' failed on attempt ${attempt} of ${maxRetries}. Retrying in ${delayMs}ms...`, retryAttemptContext);
+                }
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
+            else {
+                // Max retries reached or shouldRetry returned false
+                const finalErrorMsg = `Operation '${operationName}' failed definitively after ${attempt} attempt(s).`;
+                // Log the final failure with the enriched context
+                logger.error(finalErrorMsg, error instanceof Error ? error : undefined, retryAttemptContext);
+                if (error instanceof McpError) {
+                    // If the last error was already an McpError, re-throw it but ensure its details are preserved/updated.
+                    error.details = {
+                        ...(typeof error.details === "object" && error.details !== null
+                            ? error.details
+                            : {}),
+                        ...retryAttemptContext, // Add retry context to existing details
+                        finalAttempt: true,
+                    };
+                    throw error;
+                }
+                // For other errors, wrap in a new McpError
+                throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, // Default to SERVICE_UNAVAILABLE, consider making this configurable or smarter
+                `${finalErrorMsg} Last error: ${error instanceof Error ? error.message : String(error)}`, {
+                    ...retryAttemptContext, // Include all retry context
+                    originalErrorName: error instanceof Error ? error.name : typeof error,
+                    originalErrorStack: error instanceof Error ? error.stack : undefined,
+                    finalAttempt: true,
+                });
+            }
+        }
+    }
+    // Fallback: This part should ideally not be reached if the loop logic is correct.
+    // If it is, it implies an issue with the loop or maxRetries logic.
+    const fallbackErrorContext = {
+        ...context,
+        operation: operationName,
+        maxRetries,
+        reason: "Fallback_Error_Path_Reached_In_Retry_Logic",
+    };
+    logger.crit(
+    // Log as critical because this path indicates a logic flaw
+    `Operation '${operationName}' failed unexpectedly after all retries (fallback path). This may indicate a logic error in retryWithDelay.`, lastError instanceof Error ? lastError : undefined, fallbackErrorContext);
+    throw new McpError(BaseErrorCode.INTERNAL_ERROR, // Indicates an issue with the retry utility itself
+    `Operation '${operationName}' failed unexpectedly after all retries (fallback path). Last error: ${lastError instanceof Error ? lastError.message : String(lastError)}`, {
+        ...fallbackErrorContext,
+        originalError: lastError instanceof Error
+            ? {
+                message: lastError.message,
+                name: lastError.name,
+                stack: lastError.stack,
+            }
+            : String(lastError),
+    });
+}

package/dist/utils/internal/errorHandler.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview This module provides utilities for robust error handling.
+ * It defines structures for error context, options for handling errors,
+ * and mappings for classifying errors. The main `ErrorHandler` class
+ * offers static methods for consistent error processing, logging, and transformation.
+ * @module src/utils/internal/errorHandler
+ */
+import { BaseErrorCode } from "../../types-global/errors.js";
+/**
+ * Defines a generic structure for providing context with errors.
+ * This context can include identifiers like `requestId` or any other relevant
+ * key-value pairs that aid in debugging or understanding the error's circumstances.
+ */
+export interface ErrorContext {
+    /**
+     * A unique identifier for the request or operation during which the error occurred.
+     * Useful for tracing errors through logs and distributed systems.
+     */
+    requestId?: string;
+    /**
+     * Allows for arbitrary additional context information.
+     * Keys are strings, and values can be of any type.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Configuration options for the `ErrorHandler.handleError` method.
+ * These options control how an error is processed, logged, and whether it's rethrown.
+ */
+export interface ErrorHandlerOptions {
+    /**
+     * The context of the operation that caused the error.
+     * This can include `requestId` and other relevant debugging information.
+     */
+    context?: ErrorContext;
+    /**
+     * A descriptive name of the operation being performed when the error occurred.
+     * This helps in identifying the source or nature of the error in logs.
+     * Example: "UserLogin", "ProcessPayment", "FetchUserProfile".
+     */
+    operation: string;
+    /**
+     * The input data or parameters that were being processed when the error occurred.
+     * This input will be sanitized before logging to prevent sensitive data exposure.
+     */
+    input?: unknown;
+    /**
+     * If true, the (potentially transformed) error will be rethrown after handling.
+     * Defaults to `false`.
+     */
+    rethrow?: boolean;
+    /**
+     * A specific `BaseErrorCode` to assign to the error, overriding any
+     * automatically determined error code.
+     */
+    errorCode?: BaseErrorCode;
+    /**
+     * A custom function to map or transform the original error into a new `Error` instance.
+     * If provided, this function is used instead of the default `McpError` creation.
+     * @param error - The original error that occurred.
+     * @returns The transformed error.
+     */
+    errorMapper?: (error: unknown) => Error;
+    /**
+     * If true, stack traces will be included in the logs.
+     * Defaults to `true`.
+     */
+    includeStack?: boolean;
+    /**
+     * If true, indicates that the error is critical and might require immediate attention
+     * or could lead to system instability. This is primarily for logging and alerting.
+     * Defaults to `false`.
+     */
+    critical?: boolean;
+}
+/**
+ * Defines a basic rule for mapping errors based on patterns.
+ * Used internally by `COMMON_ERROR_PATTERNS` and as a base for `ErrorMapping`.
+ */
+export interface BaseErrorMapping {
+    /**
+     * A string or regular expression to match against the error message.
+     * If a string is provided, it's typically used for substring matching (case-insensitive).
+     */
+    pattern: string | RegExp;
+    /**
+     * The `BaseErrorCode` to assign if the pattern matches.
+     */
+    errorCode: BaseErrorCode;
+    /**
+     * An optional custom message template for the mapped error.
+     * (Note: This property is defined but not directly used by `ErrorHandler.determineErrorCode`
+     * which focuses on `errorCode`. It's more relevant for custom mapping logic.)
+     */
+    messageTemplate?: string;
+}
+/**
+ * Extends `BaseErrorMapping` to include a factory function for creating
+ * specific error instances and additional context for the mapping.
+ * Used by `ErrorHandler.mapError`.
+ * @template T The type of `Error` this mapping will produce, defaults to `Error`.
+ */
+export interface ErrorMapping<T extends Error = Error> extends BaseErrorMapping {
+    /**
+     * A factory function that creates and returns an instance of the mapped error type `T`.
+     * @param error - The original error that occurred.
+     * @param context - Optional additional context provided in the mapping rule.
+     * @returns The newly created error instance.
+     */
+    factory: (error: unknown, context?: Record<string, unknown>) => T;
+    /**
+     * Additional static context to be merged or passed to the `factory` function
+     * when this mapping rule is applied.
+     */
+    additionalContext?: Record<string, unknown>;
+}
+/**
+ * A utility class providing static methods for comprehensive error handling.
+ */
+export declare class ErrorHandler {
+    /**
+     * Determines an appropriate `BaseErrorCode` for a given error.
+     * Checks `McpError` instances, `ERROR_TYPE_MAPPINGS`, and `COMMON_ERROR_PATTERNS`.
+     * Defaults to `BaseErrorCode.INTERNAL_ERROR`.
+     * @param error - The error instance or value to classify.
+     * @returns The determined error code.
+     */
+    static determineErrorCode(error: unknown): BaseErrorCode;
+    /**
+     * Handles an error with consistent logging and optional transformation.
+     * Sanitizes input, determines error code, logs details, and can rethrow.
+     * @param error - The error instance or value that occurred.
+     * @param options - Configuration for handling the error.
+     * @returns The handled (and potentially transformed) error instance.
+     */
+    static handleError(error: unknown, options: ErrorHandlerOptions): Error;
+    /**
+     * Maps an error to a specific error type `T` based on `ErrorMapping` rules.
+     * Returns original/default error if no mapping matches.
+     * @template T The target error type, extending `Error`.
+     * @param error - The error instance or value to map.
+     * @param mappings - An array of mapping rules to apply.
+     * @param defaultFactory - Optional factory for a default error if no mapping matches.
+     * @returns The mapped error of type `T`, or the original/defaulted error.
+     */
+    static mapError<T extends Error>(error: unknown, mappings: ReadonlyArray<ErrorMapping<T>>, defaultFactory?: (error: unknown, context?: Record<string, unknown>) => T): T | Error;
+    /**
+     * Formats an error into a consistent object structure for API responses or structured logging.
+     * @param error - The error instance or value to format.
+     * @returns A structured representation of the error.
+     */
+    static formatError(error: unknown): Record<string, unknown>;
+    /**
+     * Safely executes a function (sync or async) and handles errors using `ErrorHandler.handleError`.
+     * The error is always rethrown by default by `handleError` when `rethrow` is true.
+     * @template T The expected return type of the function `fn`.
+     * @param fn - The function to execute.
+     * @param options - Error handling options (excluding `rethrow`, as it's forced to true).
+     * @returns A promise resolving with the result of `fn` if successful.
+     * @throws {McpError | Error} The error processed by `ErrorHandler.handleError`.
+     * @example
+     * ```typescript
+     * async function fetchData(userId: string, context: RequestContext) {
+     *   return ErrorHandler.tryCatch(
+     *     async () => {
+     *       const response = await fetch(`/api/users/${userId}`);
+     *       if (!response.ok) throw new Error(`Failed to fetch user: ${response.status}`);
+     *       return response.json();
+     *     },
+     *     { operation: 'fetchUserData', context, input: { userId } } // rethrow is implicitly true
+     *   );
+     * }
+     * ```
+     */
+    static tryCatch<T>(fn: () => Promise<T> | T, options: Omit<ErrorHandlerOptions, "rethrow">): Promise<T>;
+}