coursecode 0.1.0

package/framework/js/managers/objective-manager.js

@@ -0,0 +1,423 @@
+/**
+ * @file objective-manager.js
+ * @description Manages learning objectives. It is the single source of truth for
+ * all objective-related data and persists its state through the StateManager.
+ */
+
+import { deepClone } from '../utilities/utilities.js';
+import { logger } from '../utilities/logger.js';
+import stateManager from '../state/index.js';
+import { eventBus } from '../core/event-bus.js';
+
+class ObjectiveManager {
+    constructor() {
+        this.objectives = {};
+        this.isInitialized = false;
+        this.earlyQueue = []; // Queue for calls made before initialization
+        this.DOMAIN_KEY = 'objectives';
+        this.SOURCE = 'objective-manager';
+        this.criteriaConfig = []; // Store objectives with criteria
+    }
+
+    /**
+     * Initializes the manager by loading state from the StateManager and setting up objectives from config.
+     * @param {Array<object>} [objectivesConfig] - Optional array of objective configurations from course-config.js
+     * @throws {Error} If already initialized
+     */
+    initialize(objectivesConfig = []) {
+        if (this.isInitialized) {
+            throw new Error('ObjectiveManager: Already initialized. Do not call initialize() more than once.');
+        }
+
+        // Build set of configured objective IDs for validation
+        const configuredIds = new Set(objectivesConfig.map(obj => obj.id));
+
+        // Load from stateManager domain (transparently routed to CMI by stateManager)
+        const storedObjectives = stateManager.getDomainState(this.DOMAIN_KEY);
+        if (storedObjectives && typeof storedObjectives === 'object') {
+            // Validate stored objectives against current config
+            const storedIds = Object.keys(storedObjectives);
+            const orphanedIds = storedIds.filter(id => !configuredIds.has(id));
+            
+            if (orphanedIds.length > 0 && objectivesConfig.length > 0) {
+                // Found objectives in storage that aren't in current config
+                const message = `Found ${orphanedIds.length} stored objective(s) not in current config: ${orphanedIds.join(', ')}. ` +
+                    'These may be from a previous version of the course.';
+                
+                if (import.meta.env.DEV) {
+                    // Dev mode: Warn about orphaned objectives (could indicate config issue)
+                    logger.warn(`[ObjectiveManager] ${message}`);
+                }
+                // In both modes, we keep orphaned objectives in CMI (can't remove from LMS)
+                // but they won't affect course logic since they're not in config
+            }
+            
+            this.objectives = storedObjectives;
+        }
+
+        // Mark the manager initialized before seeding new objectives so SCORM syncs work immediately
+        this.isInitialized = true;
+
+        // Initialize objectives from config if provided (only if they don't exist)
+        if (objectivesConfig.length > 0) {
+            objectivesConfig.forEach(objective => {
+                if (!this.objectives[objective.id]) {
+                    // OPTIMIZATION: Do NOT store description - it's in course-config.js
+                    this.setObjective({
+                        id: objective.id,
+                        completion_status: objective.initialCompletion ?? 'incomplete',
+                        success_status: objective.initialSuccess ?? 'unknown',
+                        score: objective.initialScore ?? null
+                    });
+                }
+            });
+            logger.debug(`[ObjectiveManager] Initialized ${objectivesConfig.length} objective(s) from configuration.`);
+
+            // Enable automatic criteria tracking
+            this.enableCriteriaTracking(objectivesConfig);
+        }
+        logger.debug('[ObjectiveManager] Initialized with objectives:', this.objectives);
+
+        // Process any calls that were queued before initialization was complete
+        this._processEarlyQueue();
+    }
+
+    /**
+     * Processes and executes method calls that were queued before the manager was initialized.
+     * @private
+     */
+    _processEarlyQueue() {
+        if (this.earlyQueue.length > 0) {
+            logger.debug(`[ObjectiveManager] Processing ${this.earlyQueue.length} early-queued call(s).`);
+            this.earlyQueue.forEach(({ method, args }) => {
+                if (typeof this[method] === 'function') {
+                    this[method](...args);
+                }
+            });
+            this.earlyQueue = []; // Clear the queue
+        }
+    }
+
+    /**
+     * Retrieves all objectives.
+     * @returns {Array<object>} A deep-cloned array of all objective objects.
+     */
+    getObjectives() {
+        return deepClone(Object.values(this.objectives));
+    }
+
+    /**
+     * Retrieves a single objective by its ID.
+     * @param {string} id - The unique identifier for the objective.
+     * @returns {object|null} A deep-cloned objective object or null if not found.
+     */
+    getObjective(id) {
+        if (!id || !this.objectives[id]) {
+            return null;
+        }
+        return deepClone(this.objectives[id]);
+    }
+
+    /**
+     * Creates or updates an objective.
+     * @param {object} objectiveData - The data for the objective.
+     * @param {string} objectiveData.id - The unique identifier for the objective.
+     * @param {string} [objectiveData.success_status] - The success status ('passed', 'failed', 'unknown').
+     * @param {string} [objectiveData.completion_status] - The completion status ('completed', 'incomplete').
+     * @param {number} [objectiveData.score] - The score (0-100).
+     * @param {string} [objectiveData.description] - A description of the objective.
+     * @returns {object|undefined} The updated objective object, or undefined if queued before initialization.
+     * @throws {Error} If objectiveData is missing or id is not provided
+     */
+    setObjective(objectiveData) {
+        if (!this.isInitialized) {
+            this.earlyQueue.push({ method: 'setObjective', args: [objectiveData] });
+            return;
+        }
+
+        const { id } = objectiveData;
+        if (!id) {
+            throw new Error('ObjectiveManager: setObjective requires an id.');
+        }
+
+        const existing = this.objectives[id] || { id };
+        const updated = { ...existing, ...objectiveData };
+
+        this.objectives[id] = updated;
+
+        // Persist via stateManager domain (transparently routed to CMI by stateManager)
+        stateManager.setDomainState(this.DOMAIN_KEY, this.objectives, { source: this.SOURCE });
+
+        eventBus.emit('objective:updated', updated);
+
+        // Emit specific score event if score was updated (for ScoreManager)
+        if (typeof updated.score === 'number') {
+            eventBus.emit('objective:score:updated', {
+                objectiveId: id,
+                score: updated.score
+            });
+        }
+
+        return deepClone(updated);
+    }
+
+    /**
+     * Valid success status values per SCORM spec.
+     * @private
+     */
+    static VALID_SUCCESS_STATUSES = ['passed', 'failed', 'unknown'];
+
+    /**
+     * Valid completion status values per SCORM spec.
+     * @private
+     */
+    static VALID_COMPLETION_STATUSES = ['completed', 'incomplete'];
+
+    /**
+     * A helper method to specifically update the success status of an objective.
+     * @param {string} id - The objective ID.
+     * @param {string} success_status - The success status ('passed', 'failed', 'unknown').
+     * @param {number|null} [score] - An optional score to set along with the status.
+     * @throws {Error} If objective with given ID is not found
+     * @throws {Error} If success_status is not a valid value
+     */
+    setSuccessStatus(id, success_status, score = null) {
+        if (!this.isInitialized) {
+            this.earlyQueue.push({ method: 'setSuccessStatus', args: [id, success_status, score] });
+            return;
+        }
+        if (!ObjectiveManager.VALID_SUCCESS_STATUSES.includes(success_status)) {
+            throw new Error(`ObjectiveManager: Invalid success_status "${success_status}". Must be one of: ${ObjectiveManager.VALID_SUCCESS_STATUSES.join(', ')}`);
+        }
+        const objective = this.getObjective(id);
+        if (!objective) {
+            throw new Error(`ObjectiveManager: Objective with id "${id}" not found.`);
+        }
+        objective.success_status = success_status;
+        this.setObjective(objective);
+        if (score !== null) {
+            // Validate score through setScore's guard (which will persist separately)
+            this.setScore(id, score);
+        }
+    }
+
+    /**
+     * A helper method to specifically update the completion status of an objective.
+     * @param {string} id - The objective ID.
+     * @param {string} completion_status - The completion status ('completed', 'incomplete').
+     * @throws {Error} If objective with given ID is not found
+     * @throws {Error} If completion_status is not a valid value
+     */
+    setCompletionStatus(id, completion_status) {
+        if (!this.isInitialized) {
+            this.earlyQueue.push({ method: 'setCompletionStatus', args: [id, completion_status] });
+            return;
+        }
+        if (!ObjectiveManager.VALID_COMPLETION_STATUSES.includes(completion_status)) {
+            throw new Error(`ObjectiveManager: Invalid completion_status "${completion_status}". Must be one of: ${ObjectiveManager.VALID_COMPLETION_STATUSES.join(', ')}`);
+        }
+        const objective = this.getObjective(id);
+        if (!objective) {
+            throw new Error(`ObjectiveManager: Objective with id "${id}" not found.`);
+        }
+        objective.completion_status = completion_status;
+        this.setObjective(objective);
+    }
+
+    /**
+     * A helper method to specifically update the score of an objective.
+     * @param {string} id - The objective ID.
+     * @param {number} score - The score (0-100).
+     * @throws {Error} If objective with given ID is not found
+     * @throws {Error} If score is not a number or out of range
+     */
+    setScore(id, score) {
+        if (!this.isInitialized) {
+            this.earlyQueue.push({ method: 'setScore', args: [id, score] });
+            return;
+        }
+        const objective = this.getObjective(id);
+        if (!objective) {
+            throw new Error(`ObjectiveManager: Objective with id "${id}" not found.`);
+        }
+        if (typeof score !== 'number' || isNaN(score) || score < 0 || score > 100) {
+            throw new Error(`ObjectiveManager: Score must be a number between 0 and 100, got ${score}`);
+        }
+        objective.score = score;
+        this.setObjective(objective);
+    }
+
+    /**
+     * Enables automatic criteria tracking for objectives with built-in criteria.
+     * @param {Array<object>} objectivesConfig - Array of objective configurations from course-config.js
+     */
+    enableCriteriaTracking(objectivesConfig = []) {
+        this.criteriaConfig = objectivesConfig.filter(obj => obj.criteria);
+
+        if (this.criteriaConfig.length === 0) {
+            logger.debug('[ObjectiveManager] No objectives with built-in criteria found.');
+            return;
+        }
+
+        // Guard against duplicate listener registration
+        if (this._criteriaTrackingEnabled) {
+            logger.debug('[ObjectiveManager] Criteria tracking already enabled, updating config only.');
+            return;
+        }
+        this._criteriaTrackingEnabled = true;
+
+        // Listen for view changes to track slide visits
+        eventBus.on('view:change', ({ view }) => {
+            this._handleSlideVisit(view);
+            this._checkTimeBasedObjectives(view);
+        });
+
+        // Listen for flag changes to track flag-based objectives
+        eventBus.on('flag:updated', ({ key, value }) => {
+            this._checkFlagBasedObjectives(key, value);
+        });
+
+        // Also listen for flag removals — a removed flag is effectively undefined/falsy
+        eventBus.on('flag:removed', ({ key }) => {
+            this._checkFlagBasedObjectives(key, undefined);
+        });
+
+        logger.debug(`[ObjectiveManager] Criteria tracking enabled for ${this.criteriaConfig.length} objective(s).`);
+    }
+
+    /**
+     * Handles slide visit event and checks objectives with visit-based criteria.
+     * @private
+     * @param {string} slideId - The ID of the visited slide
+     */
+    _handleSlideVisit(slideId) {
+        // Get visited slides from state manager
+        const navigationState = stateManager.getDomainState('navigation');
+        const visitedSlides = navigationState?.visitedSlides || [];
+
+        // Create a new set of visited slides including the current one for this check
+        const allVisitedSlides = new Set([...visitedSlides, slideId]);
+
+        this.criteriaConfig.forEach(objective => {
+            // Skip if already completed
+            const current = this.objectives[objective.id];
+            if (current && current.completion_status === 'completed') {
+                return;
+            }
+
+            const { criteria } = objective;
+
+            switch (criteria.type) {
+                case 'slideVisited': {
+                    if (criteria.slideId === slideId) {
+                        this.setCompletionStatus(objective.id, 'completed');
+                        logger.debug(`[ObjectiveManager] Objective "${objective.id}" completed: slideVisited`);
+                    }
+                    break;
+                }
+
+                case 'allSlidesVisited': {
+                    const requiredSlides = criteria.slideIds || [];
+                    const allVisited = requiredSlides.every(sid => allVisitedSlides.has(sid));
+                    if (allVisited) {
+                        this.setCompletionStatus(objective.id, 'completed');
+                        logger.debug(`[ObjectiveManager] Objective "${objective.id}" completed: allSlidesVisited`);
+                    }
+                    break;
+                }
+            }
+        });
+    }
+
+    /**
+     * Checks if any time-based objectives are met for a given slide.
+     * Uses centralized timing data from AppActions (stored in sessionData domain).
+     * @private
+     * @param {string} slideId - The ID of the slide
+     */
+    _checkTimeBasedObjectives(slideId) {
+        // Get slide durations from centralized session data
+        const sessionData = stateManager.getDomainState('sessionData');
+        const slideDurations = sessionData?.slideDurations || {};
+
+        this.criteriaConfig.forEach(objective => {
+            // Skip if already completed
+            const current = this.objectives[objective.id];
+            if (current && current.completion_status === 'completed') {
+                return;
+            }
+
+            const { criteria } = objective;
+
+            if (criteria.type === 'timeOnSlide' && criteria.slideId === slideId) {
+                const totalMilliseconds = slideDurations[slideId] || 0;
+                const totalSeconds = totalMilliseconds / 1000;
+
+                if (totalSeconds >= (criteria.minSeconds || 0)) {
+                    this.setCompletionStatus(objective.id, 'completed');
+                    logger.debug(`[ObjectiveManager] Objective "${objective.id}" completed: timeOnSlide (${totalSeconds.toFixed(1)}s)`);
+                }
+            }
+        });
+    }
+
+    /**
+     * Checks if any flag-based objectives are met.
+     * @private
+     * @param {string} flagKey - The key of the flag that was updated
+     * @param {any} flagValue - The new value of the flag
+     */
+    _checkFlagBasedObjectives(flagKey, flagValue) {
+        // Get all current flags
+        const flags = stateManager.getDomainState('flags') || {};
+
+        this.criteriaConfig.forEach(objective => {
+            // Skip if already completed
+            const current = this.objectives[objective.id];
+            if (current && current.completion_status === 'completed') {
+                return;
+            }
+
+            const { criteria } = objective;
+
+            if (criteria.type === 'flag') {
+                // Single flag check
+                if (criteria.key === flagKey) {
+                    let isMet = false;
+
+                    if (criteria.equals !== undefined) {
+                        isMet = flagValue === criteria.equals;
+                    } else {
+                        // Default: check if flag is truthy
+                        isMet = !!flagValue;
+                    }
+
+                    if (isMet) {
+                        this.setCompletionStatus(objective.id, 'completed');
+                        logger.debug(`[ObjectiveManager] Objective "${objective.id}" completed: flag "${flagKey}" = ${flagValue}`);
+                    }
+                }
+            } else if (criteria.type === 'allFlags') {
+                // Multiple flags check - all must be truthy (or match equals values)
+                const requiredFlags = criteria.flags || [];
+                const allMet = requiredFlags.every(flagConfig => {
+                    const key = typeof flagConfig === 'string' ? flagConfig : flagConfig.key;
+                    const value = flags[key];
+
+                    if (typeof flagConfig === 'object' && flagConfig.equals !== undefined) {
+                        return value === flagConfig.equals;
+                    }
+                    return !!value;
+                });
+
+                if (allMet) {
+                    this.setCompletionStatus(objective.id, 'completed');
+                    logger.debug(`[ObjectiveManager] Objective "${objective.id}" completed: allFlags`);
+                }
+            }
+        });
+    }
+}
+
+const instance = new ObjectiveManager();
+export default instance;