qnce-engine/dist/engine/errors.js

Core QNCE (Quantum Narrative Convergence Engine) - Framework agnostic narrative engine with performance optimization

"use strict";
// QNCE Error Classes - Sprint 3.2
// Custom error types for robust error handling and debugging
Object.defineProperty(exports, "__esModule", { value: true });
exports.StateError = exports.StoryDataError = exports.ChoiceValidationError = exports.QNCENavigationError = exports.QNCEError = void 0;
exports.isQNCEError = isQNCEError;
exports.isChoiceValidationError = isChoiceValidationError;
exports.isNavigationError = isNavigationError;
exports.createErrorResponse = createErrorResponse;
/**
 * Base class for all QNCE-specific errors
 */
class QNCEError extends Error {
    errorCode;
    timestamp;
    metadata;
    constructor(message, errorCode, metadata) {
        super(message);
        this.name = this.constructor.name;
        this.errorCode = errorCode;
        this.timestamp = performance.now();
        this.metadata = metadata;
        // Maintains proper stack trace for where our error was thrown
        if (Error.captureStackTrace) {
            Error.captureStackTrace(this, this.constructor);
        }
    }
}
exports.QNCEError = QNCEError;
/**
 * Error thrown when navigation to a node fails
 * Used by goToNodeById() and related navigation methods
 */
class QNCENavigationError extends QNCEError {
    nodeId;
    constructor(message, nodeId, metadata) {
        super(message, 'NAVIGATION_ERROR', {
            ...metadata,
            nodeId
        });
        this.nodeId = nodeId;
    }
}
exports.QNCENavigationError = QNCENavigationError;
/**
 * Error thrown when choice validation fails
 * Provides detailed information about why the choice is invalid
 */
class ChoiceValidationError extends QNCEError {
    choice;
    validationResult;
    availableChoices;
    constructor(choice, validationResult, availableChoices) {
        const message = validationResult.reason || `Choice "${choice.text}" is not valid`;
        super(message, 'CHOICE_VALIDATION_ERROR', {
            choiceText: choice.text,
            nextNodeId: choice.nextNodeId,
            failedConditions: validationResult.failedConditions,
            validationMetadata: validationResult.metadata,
            availableChoiceCount: availableChoices?.length || 0
        });
        this.choice = choice;
        this.validationResult = validationResult;
        this.availableChoices = availableChoices;
    }
    /**
     * Get a user-friendly error message with suggestions
     */
    getUserFriendlyMessage() {
        let message = this.message;
        if (this.availableChoices && this.availableChoices.length > 0) {
            message += `\n\nAvailable choices:`;
            this.availableChoices.forEach((choice, index) => {
                message += `\n  ${index + 1}. ${choice.text}`;
            });
        }
        if (this.validationResult.suggestedChoices) {
            message += `\n\nSuggested alternatives:`;
            this.validationResult.suggestedChoices.forEach((choice, index) => {
                message += `\n  ${index + 1}. ${choice.text}`;
            });
        }
        return message;
    }
    /**
     * Get debugging information for developers
     */
    getDebugInfo() {
        return {
            error: this.name,
            errorCode: this.errorCode,
            timestamp: this.timestamp,
            choice: {
                text: this.choice.text,
                nextNodeId: this.choice.nextNodeId,
                flagEffects: this.choice.flagEffects
            },
            validationResult: this.validationResult,
            availableChoices: this.availableChoices?.map(c => ({
                text: c.text,
                nextNodeId: c.nextNodeId
            })),
            metadata: this.metadata
        };
    }
}
exports.ChoiceValidationError = ChoiceValidationError;
/**
 * Error thrown when story data is invalid or corrupted
 */
class StoryDataError extends QNCEError {
    storyId;
    constructor(message, storyId, metadata) {
        super(message, 'STORY_DATA_ERROR', {
            ...metadata,
            storyId
        });
        this.storyId = storyId;
    }
}
exports.StoryDataError = StoryDataError;
/**
 * Error thrown when engine state becomes inconsistent
 */
class StateError extends QNCEError {
    stateSnapshot;
    constructor(message, stateSnapshot) {
        super(message, 'STATE_ERROR', {
            stateSnapshot
        });
        this.stateSnapshot = stateSnapshot;
    }
}
exports.StateError = StateError;
/**
 * Utility function to check if an error is a QNCE error
 */
function isQNCEError(error) {
    return error instanceof QNCEError;
}
/**
 * Utility function to check if an error is a choice validation error
 */
function isChoiceValidationError(error) {
    return error instanceof ChoiceValidationError;
}
/**
 * Utility function to check if an error is a navigation error
 */
function isNavigationError(error) {
    return error instanceof QNCENavigationError;
}
/**
 * Create a standardized error response for API consumers
 */
function createErrorResponse(error) {
    if (isQNCEError(error)) {
        return {
            success: false,
            error: {
                name: error.name,
                message: error.message,
                code: error.errorCode,
                metadata: error.metadata
            }
        };
    }
    // Handle non-QNCE errors
    const err = error;
    return {
        success: false,
        error: {
            name: err.name || 'UnknownError',
            message: err.message || 'An unknown error occurred'
        }
    };
}
//# sourceMappingURL=errors.js.map