qnce-engine 1.2.0 → 1.2.2

package/dist/engine/validation.js

@@ -0,0 +1,261 @@
+"use strict";
+// QNCE Choice Validation System - Sprint 3.2
+// Ensures only valid choices can be executed, providing robust error handling
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultChoiceValidator = exports.StandardValidationRules = void 0;
+exports.createChoiceValidator = createChoiceValidator;
+exports.createValidationContext = createValidationContext;
+/**
+ * Built-in validation rules for common scenarios
+ */
+class StandardValidationRules {
+    /**
+     * Validates that choice exists in the current node's choices
+     */
+    static CHOICE_EXISTS = {
+        name: 'choice-exists',
+        priority: 1,
+        validate(choice, context) {
+            const exists = context.currentNode.choices.some(c => c.text === choice.text && c.nextNodeId === choice.nextNodeId);
+            return {
+                isValid: exists,
+                reason: exists ? undefined : `Choice "${choice.text}" is not available from current node`,
+                suggestedChoices: exists ? undefined : context.currentNode.choices
+            };
+        }
+    };
+    /**
+     * Validates flag-based conditions for choice availability
+     */
+    static FLAG_CONDITIONS = {
+        name: 'flag-conditions',
+        priority: 2,
+        validate(choice, context) {
+            // Check if choice has flag requirements
+            if (choice.flagRequirements) {
+                const missingFlags = [];
+                const conflictingFlags = [];
+                for (const [flagName, requiredValue] of Object.entries(choice.flagRequirements)) {
+                    const currentValue = context.state.flags[flagName];
+                    if (requiredValue === true && !currentValue) {
+                        missingFlags.push(flagName);
+                    }
+                    else if (requiredValue === false && currentValue) {
+                        conflictingFlags.push(flagName);
+                    }
+                    else if (typeof requiredValue !== 'boolean' && currentValue !== requiredValue) {
+                        missingFlags.push(`${flagName}=${requiredValue}`);
+                    }
+                }
+                if (missingFlags.length > 0 || conflictingFlags.length > 0) {
+                    const reasons = [];
+                    if (missingFlags.length > 0) {
+                        reasons.push(`Missing required flags: ${missingFlags.join(', ')}`);
+                    }
+                    if (conflictingFlags.length > 0) {
+                        reasons.push(`Conflicting flags: ${conflictingFlags.join(', ')}`);
+                    }
+                    return {
+                        isValid: false,
+                        reason: `Flag conditions not met: ${reasons.join('; ')}`,
+                        failedConditions: [...missingFlags, ...conflictingFlags],
+                        metadata: {
+                            missingFlags,
+                            conflictingFlags,
+                            currentFlags: context.state.flags
+                        }
+                    };
+                }
+            }
+            return {
+                isValid: true,
+                reason: undefined
+            };
+        }
+    };
+    /**
+     * Validates choice is not disabled or marked as unavailable
+     */
+    static CHOICE_ENABLED = {
+        name: 'choice-enabled',
+        priority: 3,
+        validate(choice, _context) {
+            if (choice.enabled === false) {
+                return {
+                    isValid: false,
+                    reason: `Choice "${choice.text}" is currently disabled`,
+                    failedConditions: ['choice-disabled']
+                };
+            }
+            return {
+                isValid: true,
+                reason: undefined
+            };
+        }
+    };
+    /**
+     * Validates time-based requirements for choice availability
+     */
+    static TIME_CONDITIONS = {
+        name: 'time-conditions',
+        priority: 4,
+        validate(choice, context) {
+            if (choice.timeRequirements) {
+                const now = new Date();
+                const currentTime = context.timestamp || now.getTime();
+                const failures = [];
+                if (choice.timeRequirements.availableAfter) {
+                    const afterTime = new Date(choice.timeRequirements.availableAfter).getTime();
+                    if (currentTime < afterTime) {
+                        failures.push(`not available until ${choice.timeRequirements.availableAfter}`);
+                    }
+                }
+                if (choice.timeRequirements.availableBefore) {
+                    const beforeTime = new Date(choice.timeRequirements.availableBefore).getTime();
+                    if (currentTime > beforeTime) {
+                        failures.push(`no longer available after ${choice.timeRequirements.availableBefore}`);
+                    }
+                }
+                if (choice.timeRequirements.minTime && currentTime < choice.timeRequirements.minTime) {
+                    failures.push(`minimum time not reached`);
+                }
+                if (choice.timeRequirements.maxTime && currentTime > choice.timeRequirements.maxTime) {
+                    failures.push(`maximum time exceeded`);
+                }
+                if (failures.length > 0) {
+                    return {
+                        isValid: false,
+                        reason: `Time conditions not met: ${failures.join(', ')}`,
+                        failedConditions: failures,
+                        metadata: {
+                            currentTime,
+                            timeRequirements: choice.timeRequirements
+                        }
+                    };
+                }
+            }
+            return {
+                isValid: true,
+                reason: undefined
+            };
+        }
+    };
+    /**
+     * Validates inventory-based requirements for choice availability
+     */
+    static INVENTORY_CONDITIONS = {
+        name: 'inventory-conditions',
+        priority: 5,
+        validate(choice, context) {
+            if (choice.inventoryRequirements) {
+                const inventory = context.state.flags.inventory || {};
+                const missingItems = [];
+                for (const [itemName, requiredQuantity] of Object.entries(choice.inventoryRequirements)) {
+                    const currentQuantity = inventory[itemName] || 0;
+                    if (currentQuantity < requiredQuantity) {
+                        missingItems.push(`${itemName} (need ${requiredQuantity}, have ${currentQuantity})`);
+                    }
+                }
+                if (missingItems.length > 0) {
+                    return {
+                        isValid: false,
+                        reason: `Insufficient inventory: ${missingItems.join(', ')}`,
+                        failedConditions: missingItems,
+                        metadata: {
+                            currentInventory: inventory,
+                            requirements: choice.inventoryRequirements
+                        }
+                    };
+                }
+            }
+            return {
+                isValid: true,
+                reason: undefined
+            };
+        }
+    };
+}
+exports.StandardValidationRules = StandardValidationRules;
+/**
+ * Default implementation of ChoiceValidator
+ * Uses a rule-based system for extensible validation logic
+ */
+class DefaultChoiceValidator {
+    rules = [];
+    constructor() {
+        // Add standard validation rules by default
+        this.addRule(StandardValidationRules.CHOICE_EXISTS);
+        this.addRule(StandardValidationRules.FLAG_CONDITIONS);
+        this.addRule(StandardValidationRules.CHOICE_ENABLED);
+        this.addRule(StandardValidationRules.TIME_CONDITIONS);
+        this.addRule(StandardValidationRules.INVENTORY_CONDITIONS);
+    }
+    validate(choice, context) {
+        // Run all validation rules in priority order
+        const sortedRules = this.getRules();
+        for (const rule of sortedRules) {
+            const result = rule.validate(choice, context);
+            // If any rule fails, return that failure
+            if (!result.isValid) {
+                return {
+                    ...result,
+                    metadata: {
+                        ...result.metadata,
+                        failedRule: rule.name,
+                        rulesPassed: sortedRules.indexOf(rule)
+                    }
+                };
+            }
+        }
+        // All rules passed
+        return {
+            isValid: true,
+            metadata: {
+                rulesChecked: sortedRules.length,
+                allRulesPassed: true
+            }
+        };
+    }
+    getAvailableChoices(context) {
+        // Use the availableChoices from context (which may have been pre-filtered by conditions)
+        // instead of all choices from the node
+        return context.availableChoices.filter(choice => {
+            const result = this.validate(choice, context);
+            return result.isValid;
+        });
+    }
+    addRule(rule) {
+        // Remove any existing rule with the same name
+        this.removeRule(rule.name);
+        // Add the new rule
+        this.rules.push(rule);
+        // Sort by priority
+        this.rules.sort((a, b) => a.priority - b.priority);
+    }
+    removeRule(ruleName) {
+        this.rules = this.rules.filter(rule => rule.name !== ruleName);
+    }
+    getRules() {
+        return [...this.rules].sort((a, b) => a.priority - b.priority);
+    }
+}
+exports.DefaultChoiceValidator = DefaultChoiceValidator;
+/**
+ * Factory function to create a choice validator with default rules
+ */
+function createChoiceValidator() {
+    return new DefaultChoiceValidator();
+}
+/**
+ * Utility function to create validation context from engine state
+ */
+function createValidationContext(currentNode, state, availableChoices, metadata) {
+    return {
+        currentNode,
+        state,
+        availableChoices,
+        timestamp: performance.now(),
+        metadata
+    };
+}
+//# sourceMappingURL=validation.js.map

package/dist/engine/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/engine/validation.ts"],"names":[],"mappings":"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"}

package/dist/examples/examples/autosave-undo-demo.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * QNCE Autosave & Undo/Redo Demo
+ *
+ * Demonstrates the Sprint 3.5 autosave and undo/redo functionality
+ * with interactive examples and performance metrics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_js_1 = require("../src/engine/core.js");
+const demo_story_js_1 = require("../src/engine/demo-story.js");
+console.log('🔄 QNCE Autosave & Undo/Redo Demo - Sprint 3.5');
+console.log('='.repeat(50));
+async function demonstrateUndoRedo() {
+    console.log('\n📝 Demonstrating Undo/Redo Functionality');
+    console.log('-'.repeat(40));
+    const engine = (0, core_js_1.createQNCEEngine)(demo_story_js_1.DEMO_STORY);
+    // Configure undo/redo with detailed logging
+    engine.configureUndoRedo({
+        enabled: true,
+        maxUndoEntries: 10,
+        maxRedoEntries: 5
+    });
+    console.log('Initial state:', engine.getCurrentNode().text.substring(0, 50) + '...');
+    console.log('Can undo:', engine.canUndo());
+    console.log('Can redo:', engine.canRedo());
+    // Make some choices
+    console.log('\n🎮 Making choices...');
+    const choices1 = engine.getAvailableChoices();
+    if (choices1.length > 0) {
+        console.log(`Selecting: "${choices1[0].text}"`);
+        engine.selectChoice(choices1[0]);
+        console.log('New state:', engine.getCurrentNode().text.substring(0, 50) + '...');
+        console.log('Undo count:', engine.getUndoCount());
+    }
+    const choices2 = engine.getAvailableChoices();
+    if (choices2.length > 0) {
+        console.log(`Selecting: "${choices2[0].text}"`);
+        engine.selectChoice(choices2[0]);
+        console.log('New state:', engine.getCurrentNode().text.substring(0, 50) + '...');
+        console.log('Undo count:', engine.getUndoCount());
+    }
+    // Demonstrate undo
+    console.log('\n⏪ Testing undo...');
+    const undoResult1 = engine.undo();
+    if (undoResult1.success) {
+        console.log('✅ Undo successful');
+        console.log('Restored to:', engine.getCurrentNode().text.substring(0, 50) + '...');
+        console.log('Can redo:', engine.canRedo());
+    }
+    const undoResult2 = engine.undo();
+    if (undoResult2.success) {
+        console.log('✅ Second undo successful');
+        console.log('Restored to:', engine.getCurrentNode().text.substring(0, 50) + '...');
+        console.log('Undo count:', engine.getUndoCount());
+        console.log('Redo count:', engine.getRedoCount());
+    }
+    // Demonstrate redo
+    console.log('\n⏩ Testing redo...');
+    const redoResult = engine.redo();
+    if (redoResult.success) {
+        console.log('✅ Redo successful');
+        console.log('Restored to:', engine.getCurrentNode().text.substring(0, 50) + '...');
+        console.log('Final state - Undo:', engine.getUndoCount(), 'Redo:', engine.getRedoCount());
+    }
+    // Show history summary
+    const history = engine.getHistorySummary();
+    console.log('\n📊 History Summary:');
+    console.log(`- Undo entries: ${history.undoEntries.length}`);
+    console.log(`- Redo entries: ${history.redoEntries.length}`);
+    return engine;
+}
+async function demonstrateAutosave() {
+    console.log('\n💾 Demonstrating Autosave Functionality');
+    console.log('-'.repeat(40));
+    const engine = (0, core_js_1.createQNCEEngine)(demo_story_js_1.DEMO_STORY);
+    // Configure autosave with custom settings
+    engine.configureAutosave({
+        enabled: true,
+        triggers: ['choice', 'flag-change'],
+        throttleMs: 50, // Very fast for demo
+        maxEntries: 5,
+        includeMetadata: true
+    });
+    console.log('Autosave configured with 50ms throttle');
+    // Track autosave events
+    let autosaveCount = 0;
+    const originalMethod = engine.manualAutosave.bind(engine);
+    engine.manualAutosave = async (metadata) => {
+        autosaveCount++;
+        console.log(`🔄 Autosave #${autosaveCount} triggered`);
+        return originalMethod(metadata);
+    };
+    // Make choices to trigger autosave
+    console.log('\n🎮 Making choices (autosave should trigger)...');
+    for (let i = 0; i < 3; i++) {
+        const choices = engine.getAvailableChoices();
+        if (choices.length > 0) {
+            console.log(`Choice ${i + 1}: "${choices[0].text}"`);
+            engine.selectChoice(choices[0]);
+            // Small delay to observe throttling
+            await new Promise(resolve => setTimeout(resolve, 25));
+        }
+    }
+    // Set some flags to trigger more autosaves
+    console.log('\n🏁 Setting flags (autosave should trigger)...');
+    engine.setFlag('demo_flag_1', true);
+    await new Promise(resolve => setTimeout(resolve, 60));
+    engine.setFlag('demo_flag_2', 'test_value');
+    await new Promise(resolve => setTimeout(resolve, 60));
+    // Manual autosave
+    console.log('\n💾 Triggering manual autosave...');
+    await engine.manualAutosave({ demo: 'manual_save' });
+    console.log(`\n📊 Total autosaves triggered: ${autosaveCount}`);
+    return engine;
+}
+async function demonstratePerformance() {
+    console.log('\n⚡ Performance Testing');
+    console.log('-'.repeat(40));
+    const engine = (0, core_js_1.createQNCEEngine)(demo_story_js_1.DEMO_STORY);
+    // Configure for performance testing
+    engine.configureUndoRedo({
+        enabled: true,
+        maxUndoEntries: 100,
+        maxRedoEntries: 50
+    });
+    // Build up some history
+    console.log('Building up history for performance test...');
+    for (let i = 0; i < 20; i++) {
+        const choices = engine.getAvailableChoices();
+        if (choices.length > 0) {
+            engine.selectChoice(choices[0]);
+        }
+        // Set some flags
+        engine.setFlag(`test_flag_${i}`, i * 2);
+    }
+    console.log(`History built: ${engine.getUndoCount()} undo entries`);
+    // Performance test undo operations
+    console.log('\n⏪ Testing undo performance...');
+    const undoTimes = [];
+    for (let i = 0; i < 10; i++) {
+        const startTime = performance.now();
+        const result = engine.undo();
+        const endTime = performance.now();
+        if (result.success) {
+            undoTimes.push(endTime - startTime);
+        }
+    }
+    const avgUndoTime = undoTimes.reduce((a, b) => a + b, 0) / undoTimes.length;
+    const maxUndoTime = Math.max(...undoTimes);
+    console.log(`Average undo time: ${avgUndoTime.toFixed(3)}ms`);
+    console.log(`Maximum undo time: ${maxUndoTime.toFixed(3)}ms`);
+    console.log(`Target: <1ms ${avgUndoTime < 1 ? '✅' : '❌'}`);
+    // Performance test redo operations
+    console.log('\n⏩ Testing redo performance...');
+    const redoTimes = [];
+    for (let i = 0; i < Math.min(10, engine.getRedoCount()); i++) {
+        const startTime = performance.now();
+        const result = engine.redo();
+        const endTime = performance.now();
+        if (result.success) {
+            redoTimes.push(endTime - startTime);
+        }
+    }
+    if (redoTimes.length > 0) {
+        const avgRedoTime = redoTimes.reduce((a, b) => a + b, 0) / redoTimes.length;
+        const maxRedoTime = Math.max(...redoTimes);
+        console.log(`Average redo time: ${avgRedoTime.toFixed(3)}ms`);
+        console.log(`Maximum redo time: ${maxRedoTime.toFixed(3)}ms`);
+        console.log(`Target: <1ms ${avgRedoTime < 1 ? '✅' : '❌'}`);
+    }
+    // Test autosave performance
+    console.log('\n💾 Testing autosave performance...');
+    const autosaveTimes = [];
+    for (let i = 0; i < 5; i++) {
+        const startTime = performance.now();
+        await engine.manualAutosave({ test: `performance_${i}` });
+        const endTime = performance.now();
+        autosaveTimes.push(endTime - startTime);
+    }
+    const avgAutosaveTime = autosaveTimes.reduce((a, b) => a + b, 0) / autosaveTimes.length;
+    const maxAutosaveTime = Math.max(...autosaveTimes);
+    console.log(`Average autosave time: ${avgAutosaveTime.toFixed(3)}ms`);
+    console.log(`Maximum autosave time: ${maxAutosaveTime.toFixed(3)}ms`);
+    console.log(`Target: <1ms ${avgAutosaveTime < 1 ? '✅' : '❌'}`);
+}
+async function demonstrateIntegration() {
+    console.log('\n🔗 Integration with Existing Features');
+    console.log('-'.repeat(40));
+    const engine = (0, core_js_1.createQNCEEngine)(demo_story_js_1.DEMO_STORY);
+    // Enable all features
+    engine.configureUndoRedo({ enabled: true, maxUndoEntries: 50, maxRedoEntries: 25 });
+    engine.configureAutosave({
+        enabled: true,
+        triggers: ['choice', 'flag-change', 'state-load'],
+        throttleMs: 100,
+        maxEntries: 10,
+        includeMetadata: true
+    });
+    console.log('✅ Undo/redo and autosave configured');
+    // Test with state persistence
+    console.log('\n💾 Testing state save/load with undo/redo...');
+    // Make some changes
+    const choices = engine.getAvailableChoices();
+    if (choices.length > 0) {
+        engine.selectChoice(choices[0]);
+    }
+    engine.setFlag('integration_test', true);
+    console.log(`State before save - Undo count: ${engine.getUndoCount()}`);
+    // Save state
+    const savedState = await engine.saveState();
+    console.log('✅ State saved successfully');
+    // Make more changes
+    const choices2 = engine.getAvailableChoices();
+    if (choices2.length > 0) {
+        engine.selectChoice(choices2[0]);
+    }
+    engine.setFlag('after_save', 'test');
+    console.log(`State after more changes - Undo count: ${engine.getUndoCount()}`);
+    // Load previous state
+    await engine.loadState(savedState);
+    console.log('✅ State loaded successfully');
+    console.log(`State after load - Undo count: ${engine.getUndoCount()}`);
+    console.log('Flags:', Object.keys(engine.getState().flags));
+    // Test undo after load
+    const undoAfterLoad = engine.undo();
+    console.log(`Undo after load: ${undoAfterLoad.success ? '✅ Success' : '❌ Failed'}`);
+}
+async function main() {
+    try {
+        await demonstrateUndoRedo();
+        await demonstrateAutosave();
+        await demonstratePerformance();
+        await demonstrateIntegration();
+        console.log('\n🎉 Demo completed successfully!');
+        console.log('\nSprint 3.5 Features Demonstrated:');
+        console.log('✅ Undo/Redo with configurable history limits');
+        console.log('✅ Autosave with throttling and event triggers');
+        console.log('✅ Sub-millisecond performance for operations');
+        console.log('✅ Integration with existing state persistence');
+        console.log('✅ Memory-efficient history management');
+    }
+    catch (error) {
+        console.error('❌ Demo failed:', error);
+        process.exit(1);
+    }
+}
+// Run the demo
+main();

package/dist/examples/examples/persistence-demo.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const src_1 = require("../src");
+/**
+ * Demonstrates the state persistence and checkpoint features of the QNCE Engine.
+ * This example covers:
+ * 1. Saving the complete narrative state.
+ * 2. Loading that state into a new engine instance.
+ * 3. Creating lightweight checkpoints for undo/redo functionality.
+ * 4. Restoring the state from a checkpoint.
+ */
+async function runPersistenceDemo() {
+    console.log('🚀 Starting QNCE Engine Persistence Demo 🚀\n');
+    // 1. Initialize the engine and advance the story
+    const engine = (0, src_1.createQNCEEngine)(src_1.DEMO_STORY);
+    console.log('Initial Node:', engine.getCurrentNode().text);
+    let choices = engine.getAvailableChoices();
+    engine.selectChoice(choices[1]); // Choose "Examine the shimmering portal."
+    console.log('\nChoice Made. Current Node:', engine.getCurrentNode().text);
+    choices = engine.getAvailableChoices();
+    engine.selectChoice(choices[0]); // Choose "Step through the portal."
+    console.log('Choice Made. Current Node:', engine.getCurrentNode().text);
+    console.log('Current Flags:', engine.getFlags());
+    // 2. Create a checkpoint before making another choice
+    console.log('\n💾 Creating a checkpoint...');
+    const checkpoint = await engine.createCheckpoint('Before the final choice');
+    console.log(`Checkpoint '${checkpoint.name}' created with ID: ${checkpoint.id}`);
+    // 3. Save the complete engine state to a string
+    console.log('\n💾 Saving engine state to JSON...');
+    const savedState = await engine.saveState({ prettyPrint: true });
+    const savedStateJSON = JSON.stringify(savedState);
+    console.log('State saved successfully! Size:', savedStateJSON.length, 'bytes');
+    // In a real application, you would store this JSON string in localStorage,
+    // a file, or a remote database.
+    // 4. Continue the story
+    choices = engine.getAvailableChoices();
+    engine.selectChoice(choices[0]);
+    console.log('\nMade one more choice. Current Node:', engine.getCurrentNode().text);
+    console.log('Final Flags:', engine.getFlags());
+    // 5. Restore from the checkpoint to "undo" the last choice
+    console.log(`\n🔄 Restoring from checkpoint '${checkpoint.name}'...`);
+    await engine.restoreFromCheckpoint(checkpoint.id);
+    console.log('State restored from checkpoint!');
+    console.log('Current Node after restore:', engine.getCurrentNode().text);
+    console.log('Flags after restore:', engine.getFlags());
+    // 6. Create a new engine instance and load the saved state
+    console.log('\n🔄 Creating a new engine and loading the saved state...');
+    const newEngine = (0, src_1.createQNCEEngine)(src_1.DEMO_STORY);
+    // The state can be loaded from a JSON string or a parsed object
+    await newEngine.loadState(savedState);
+    console.log('State loaded into new engine instance!');
+    // 7. Verify that the state was restored correctly
+    console.log('\n🔍 Verifying restored state...');
+    console.log('Restored Node:', newEngine.getCurrentNode().text);
+    console.log('Restored Flags:', newEngine.getFlags());
+    console.log('History length:', newEngine.getHistory().length, '| Expected:', 2);
+    const areFlagsEqual = JSON.stringify(engine.getFlags()) === JSON.stringify(newEngine.getFlags());
+    console.log('Verification successful:', areFlagsEqual);
+    console.log('\n✅ Persistence Demo Completed Successfully! ✅');
+}
+runPersistenceDemo().catch(error => {
+    console.error('An error occurred during the persistence demo:', error);
+});