scorm-again 2.0.0 → 2.2.0

package/src/Scorm2004API.ts

@@ -1,26 +1,31 @@
-import BaseAPI, { RefObject, ResultObject, Settings } from "./BaseAPI";
-import {
-  ADL,
-  CMI,
-  CMICommentsObject,
-  CMIInteractionsCorrectResponsesObject,
-  CMIInteractionsObject,
-  CMIInteractionsObjectivesObject,
-  CMIObjectivesObject,
-} from "./cmi/scorm2004_cmi";
+import BaseAPI from "./BaseAPI";
+import { CMI } from "./cmi/scorm2004/cmi";
 import * as Utilities from "./utilities";
+import { stringMatches } from "./utilities";
 import APIConstants from "./constants/api_constants";
 import ErrorCodes from "./constants/error_codes";
 import { CorrectResponses, ResponseType } from "./constants/response_constants";
 import ValidLanguages from "./constants/language_constants";
 import Regex from "./constants/regex";
-import { BaseCMI, CMIArray } from "./cmi/common";
-
-const scorm2004_constants = APIConstants.scorm2004;
-const global_constants = APIConstants.global;
-const scorm2004_error_codes = ErrorCodes.scorm2004;
-const correct_responses = CorrectResponses;
-const scorm2004_regex = Regex.scorm2004;
+import regex from "./constants/regex";
+import { CMIArray } from "./cmi/common/array";
+import { BaseCMI } from "./cmi/common/base_cmi";
+import {
+  CMIInteractionsCorrectResponsesObject,
+  CMIInteractionsObject,
+  CMIInteractionsObjectivesObject,
+} from "./cmi/scorm2004/interactions";
+import { CMICommentsObject } from "./cmi/scorm2004/comments";
+import { CMIObjectivesObject } from "./cmi/scorm2004/objectives";
+import { ADL } from "./cmi/scorm2004/adl";
+import {
+  CommitObject,
+  RefObject,
+  ResultObject,
+  ScoreObject,
+  Settings,
+} from "./types/api_types";
+import { CompletionStatus, SuccessStatus } from "./constants/enums";
 
 /**
  * API class for SCORM 2004
@@ -39,7 +44,7 @@ export default class Scorm2004API extends BaseAPI {
       }
     }
 
-    super(scorm2004_error_codes, settings);
+    super(ErrorCodes.scorm2004, settings);
 
     this.cmi = new CMI();
     this.adl = new ADL();
@@ -67,6 +72,16 @@ export default class Scorm2004API extends BaseAPI {
   public GetErrorString: (CMIErrorCode: string | number) => string;
   public GetDiagnostic: (CMIErrorCode: string | number) => string;
 
+  /**
+   * Called when the API needs to be reset
+   */
+  reset(settings?: Settings) {
+    this.commonReset(settings);
+
+    this.cmi = new CMI();
+    this.adl = new ADL();
+  }
+
   /**
    * Getter for _version
    * @return {string}
@@ -87,32 +102,39 @@ export default class Scorm2004API extends BaseAPI {
    * @return {string} bool
    */
   lmsFinish(): string {
-    const result = this.terminate("Terminate", true);
+    (async () => {
+      await this.internalFinish();
+    })();
+    return APIConstants.global.SCORM_TRUE;
+  }
+
+  async internalFinish(): Promise<string> {
+    const result = await this.terminate("Terminate", true);
 
-    if (result === global_constants.SCORM_TRUE) {
+    if (result === APIConstants.global.SCORM_TRUE) {
       if (this.adl.nav.request !== "_none_") {
-        switch (this.adl.nav.request) {
-          case "continue":
-            this.processListeners("SequenceNext");
-            break;
-          case "previous":
-            this.processListeners("SequencePrevious");
-            break;
-          case "choice":
-            this.processListeners("SequenceChoice");
-            break;
-          case "exit":
-            this.processListeners("SequenceExit");
-            break;
-          case "exitAll":
-            this.processListeners("SequenceExitAll");
-            break;
-          case "abandon":
-            this.processListeners("SequenceAbandon");
-            break;
-          case "abandonAll":
-            this.processListeners("SequenceAbandonAll");
-            break;
+        const navActions: { [key: string]: string } = {
+          continue: "SequenceNext",
+          previous: "SequencePrevious",
+          choice: "SequenceChoice",
+          jump: "SequenceJump",
+          exit: "SequenceExit",
+          exitAll: "SequenceExitAll",
+          abandon: "SequenceAbandon",
+          abandonAll: "SequenceAbandonAll",
+        };
+
+        let request = this.adl.nav.request;
+        const choiceJumpRegex = new RegExp(regex.scorm2004.NAVEvent);
+        const matches = request.match(choiceJumpRegex);
+        let target = "";
+        if (matches && matches.length > 2) {
+          target = matches[2];
+          request = matches[1].replace(target, "");
+        }
+        const action = navActions[request];
+        if (action) {
+          this.processListeners(action, "adl.nav.request", target);
         }
       } else if (this.settings.autoProgress) {
         this.processListeners("SequenceNext");
@@ -127,6 +149,19 @@ export default class Scorm2004API extends BaseAPI {
    * @return {string}
    */
   lmsGetValue(CMIElement: string): string {
+    const adlNavRequestRegex =
+      "^adl\\.nav\\.request_valid\\.(choice|jump)\\.{target=\\S{0,}([a-zA-Z0-9-_]+)}$";
+    if (stringMatches(CMIElement, adlNavRequestRegex)) {
+      const matches = CMIElement.match(adlNavRequestRegex);
+      const request = matches[1];
+      const target = matches[2].replace("{target=", "").replace("}", "");
+      if (request === "choice" || request === "jump") {
+        if (this.settings.scoItemIdValidator) {
+          return String(this.settings.scoItemIdValidator(target));
+        }
+        return String(this.settings.scoItemIds.includes(target));
+      }
+    }
     return this.getValue("GetValue", true, CMIElement);
   }
 
@@ -145,7 +180,10 @@ export default class Scorm2004API extends BaseAPI {
    * @return {string} bool
    */
   lmsCommit(): string {
-    return this.commit("Commit");
+    (async () => {
+      await this.commit("Commit");
+    })();
+    return APIConstants.global.SCORM_TRUE;
   }
 
   /**
@@ -201,66 +239,71 @@ export default class Scorm2004API extends BaseAPI {
     value: any,
     foundFirstIndex: boolean,
   ): BaseCMI | null {
-    if (this.stringMatches(CMIElement, "cmi\\.objectives\\.\\d+")) {
+    if (stringMatches(CMIElement, "cmi\\.objectives\\.\\d+")) {
       return new CMIObjectivesObject();
-    } else if (
-      foundFirstIndex &&
-      this.stringMatches(
-        CMIElement,
-        "cmi\\.interactions\\.\\d+\\.correct_responses\\.\\d+",
-      )
-    ) {
-      const parts = CMIElement.split(".");
-      const index = Number(parts[2]);
-      const interaction = this.cmi.interactions.childArray[index];
-      if (this.isInitialized()) {
-        if (!interaction.type) {
-          this.throwSCORMError(
-            scorm2004_error_codes.DEPENDENCY_NOT_ESTABLISHED,
-          );
-        } else {
-          this.checkDuplicateChoiceResponse(interaction, value);
+    }
 
-          const response_type = correct_responses[interaction.type];
-          if (response_type) {
-            this.checkValidResponseType(response_type, value, interaction.type);
-          } else {
-            this.throwSCORMError(
-              scorm2004_error_codes.GENERAL_SET_FAILURE,
-              "Incorrect Response Type: " + interaction.type,
-            );
-          }
-        }
-      }
-      if (this.lastErrorCode === "0") {
-        return new CMIInteractionsCorrectResponsesObject();
+    if (foundFirstIndex) {
+      if (
+        stringMatches(
+          CMIElement,
+          "cmi\\.interactions\\.\\d+\\.correct_responses\\.\\d+",
+        )
+      ) {
+        return this.createCorrectResponsesObject(CMIElement, value);
+      } else if (
+        stringMatches(
+          CMIElement,
+          "cmi\\.interactions\\.\\d+\\.objectives\\.\\d+",
+        )
+      ) {
+        return new CMIInteractionsObjectivesObject();
       }
-    } else if (
-      foundFirstIndex &&
-      this.stringMatches(
-        CMIElement,
-        "cmi\\.interactions\\.\\d+\\.objectives\\.\\d+",
-      )
-    ) {
-      return new CMIInteractionsObjectivesObject();
-    } else if (
-      !foundFirstIndex &&
-      this.stringMatches(CMIElement, "cmi\\.interactions\\.\\d+")
-    ) {
+    } else if (stringMatches(CMIElement, "cmi\\.interactions\\.\\d+")) {
       return new CMIInteractionsObject();
-    } else if (
-      this.stringMatches(CMIElement, "cmi\\.comments_from_learner\\.\\d+")
-    ) {
+    }
+
+    if (stringMatches(CMIElement, "cmi\\.comments_from_learner\\.\\d+")) {
       return new CMICommentsObject();
-    } else if (
-      this.stringMatches(CMIElement, "cmi\\.comments_from_lms\\.\\d+")
-    ) {
+    } else if (stringMatches(CMIElement, "cmi\\.comments_from_lms\\.\\d+")) {
       return new CMICommentsObject(true);
     }
 
     return null;
   }
 
+  private createCorrectResponsesObject(
+    CMIElement: string,
+    value: any,
+  ): BaseCMI | null {
+    const parts = CMIElement.split(".");
+    const index = Number(parts[2]);
+    const interaction = this.cmi.interactions.childArray[index];
+
+    if (this.isInitialized()) {
+      if (!interaction.type) {
+        this.throwSCORMError(ErrorCodes.scorm2004.DEPENDENCY_NOT_ESTABLISHED);
+      } else {
+        this.checkDuplicateChoiceResponse(interaction, value);
+        const response_type = CorrectResponses[interaction.type];
+        if (response_type) {
+          this.checkValidResponseType(response_type, value, interaction.type);
+        } else {
+          this.throwSCORMError(
+            ErrorCodes.scorm2004.GENERAL_SET_FAILURE,
+            "Incorrect Response Type: " + interaction.type,
+          );
+        }
+      }
+    }
+
+    if (this.lastErrorCode === "0") {
+      return new CMIInteractionsCorrectResponsesObject();
+    }
+
+    return null;
+  }
+
   /**
    * Checks for valid response types
    * @param {object} response_type
@@ -283,7 +326,7 @@ export default class Scorm2004API extends BaseAPI {
       this.checkCorrectResponseValue(interaction_type, nodes, value);
     } else if (nodes.length > response_type.max) {
       this.throwSCORMError(
-        scorm2004_error_codes.GENERAL_SET_FAILURE,
+        ErrorCodes.scorm2004.GENERAL_SET_FAILURE,
         "Data Model Element Pattern Too Long",
       );
     }
@@ -304,7 +347,7 @@ export default class Scorm2004API extends BaseAPI {
       ) {
         const response = interaction.correct_responses.childArray[i];
         if (response.pattern === value) {
-          this.throwSCORMError(scorm2004_error_codes.GENERAL_SET_FAILURE);
+          this.throwSCORMError(ErrorCodes.scorm2004.GENERAL_SET_FAILURE);
         }
       }
     }
@@ -324,7 +367,7 @@ export default class Scorm2004API extends BaseAPI {
     const interaction_count = interaction.correct_responses._count;
     this.checkDuplicateChoiceResponse(interaction, value);
 
-    const response_type = correct_responses[interaction.type];
+    const response_type = CorrectResponses[interaction.type];
     if (
       typeof response_type.limit === "undefined" ||
       interaction_count <= response_type.limit
@@ -345,14 +388,14 @@ export default class Scorm2004API extends BaseAPI {
       } else {
         if (this.lastErrorCode === "0") {
           this.throwSCORMError(
-            scorm2004_error_codes.GENERAL_SET_FAILURE,
+            ErrorCodes.scorm2004.GENERAL_SET_FAILURE,
             "Data Model Element Pattern Already Exists",
           );
         }
       }
     } else {
       this.throwSCORMError(
-        scorm2004_error_codes.GENERAL_SET_FAILURE,
+        ErrorCodes.scorm2004.GENERAL_SET_FAILURE,
         "Data Model Element Collection Limit Reached",
       );
     }
@@ -384,11 +427,11 @@ export default class Scorm2004API extends BaseAPI {
 
     // Set error number to string since inconsistent from modules if string or number
     errorNumber = String(errorNumber);
-    if (scorm2004_constants.error_descriptions[errorNumber]) {
+    if (APIConstants.scorm2004.error_descriptions[errorNumber]) {
       basicMessage =
-        scorm2004_constants.error_descriptions[errorNumber].basicMessage;
+        APIConstants.scorm2004.error_descriptions[errorNumber].basicMessage;
       detailMessage =
-        scorm2004_constants.error_descriptions[errorNumber].detailMessage;
+        APIConstants.scorm2004.error_descriptions[errorNumber].detailMessage;
     }
 
     return detail ? detailMessage : basicMessage;
@@ -427,7 +470,7 @@ export default class Scorm2004API extends BaseAPI {
     nodes: Array<any>,
     value: any,
   ) {
-    const response = correct_responses[interaction_type];
+    const response = CorrectResponses[interaction_type];
     const formatRegex = new RegExp(response.format);
     for (let i = 0; i < nodes.length && this.lastErrorCode === "0"; i++) {
       if (
@@ -443,17 +486,17 @@ export default class Scorm2004API extends BaseAPI {
         if (values.length === 2) {
           const matches = values[0].match(formatRegex);
           if (!matches) {
-            this.throwSCORMError(scorm2004_error_codes.TYPE_MISMATCH);
+            this.throwSCORMError(ErrorCodes.scorm2004.TYPE_MISMATCH);
           } else {
             if (
               !response.format2 ||
               !values[1].match(new RegExp(response.format2))
             ) {
-              this.throwSCORMError(scorm2004_error_codes.TYPE_MISMATCH);
+              this.throwSCORMError(ErrorCodes.scorm2004.TYPE_MISMATCH);
             }
           }
         } else {
-          this.throwSCORMError(scorm2004_error_codes.TYPE_MISMATCH);
+          this.throwSCORMError(ErrorCodes.scorm2004.TYPE_MISMATCH);
         }
       } else {
         const matches = nodes[i].match(formatRegex);
@@ -461,17 +504,17 @@ export default class Scorm2004API extends BaseAPI {
           (!matches && value !== "") ||
           (!matches && interaction_type === "true-false")
         ) {
-          this.throwSCORMError(scorm2004_error_codes.TYPE_MISMATCH);
+          this.throwSCORMError(ErrorCodes.scorm2004.TYPE_MISMATCH);
         } else {
           if (interaction_type === "numeric" && nodes.length > 1) {
             if (Number(nodes[0]) > Number(nodes[1])) {
-              this.throwSCORMError(scorm2004_error_codes.TYPE_MISMATCH);
+              this.throwSCORMError(ErrorCodes.scorm2004.TYPE_MISMATCH);
             }
           } else {
             if (nodes[i] !== "" && response.unique) {
               for (let j = 0; j < i && this.lastErrorCode === "0"; j++) {
                 if (nodes[i] === nodes[j]) {
-                  this.throwSCORMError(scorm2004_error_codes.TYPE_MISMATCH);
+                  this.throwSCORMError(ErrorCodes.scorm2004.TYPE_MISMATCH);
                 }
               }
             }
@@ -499,12 +542,12 @@ export default class Scorm2004API extends BaseAPI {
     while (matches) {
       switch (matches[2]) {
         case "lang":
-          langMatches = node.match(scorm2004_regex.CMILangcr);
+          langMatches = node.match(Regex.scorm2004.CMILangcr);
           if (langMatches) {
             const lang = langMatches[3];
             if (lang !== undefined && lang.length > 0) {
               if (!ValidLanguages.includes(lang.toLowerCase())) {
-                this.throwSCORMError(scorm2004_error_codes.TYPE_MISMATCH);
+                this.throwSCORMError(ErrorCodes.scorm2004.TYPE_MISMATCH);
               }
             }
           }
@@ -513,7 +556,7 @@ export default class Scorm2004API extends BaseAPI {
         case "case_matters":
           if (!seenLang && !seenOrder && !seenCase) {
             if (matches[3] !== "true" && matches[3] !== "false") {
-              this.throwSCORMError(scorm2004_error_codes.TYPE_MISMATCH);
+              this.throwSCORMError(ErrorCodes.scorm2004.TYPE_MISMATCH);
             }
           }
 
@@ -522,14 +565,12 @@ export default class Scorm2004API extends BaseAPI {
         case "order_matters":
           if (!seenCase && !seenLang && !seenOrder) {
             if (matches[3] !== "true" && matches[3] !== "false") {
-              this.throwSCORMError(scorm2004_error_codes.TYPE_MISMATCH);
+              this.throwSCORMError(ErrorCodes.scorm2004.TYPE_MISMATCH);
             }
           }
 
           seenOrder = true;
           break;
-        default:
-          break;
       }
       node = node.substring(matches[1].length);
       matches = node.match(prefixRegex);
@@ -579,13 +620,74 @@ export default class Scorm2004API extends BaseAPI {
     }
   }
 
+  /**
+   * Render the cmi object to the proper format for LMS commit
+   * @param {boolean} terminateCommit
+   * @return {CommitObject}
+   */
+  renderCommitObject(terminateCommit: boolean): CommitObject {
+    const cmiExport = this.renderCommitCMI(terminateCommit);
+    const totalTimeDuration = this.cmi.getCurrentTotalTime();
+    const totalTimeSeconds = Utilities.getDurationAsSeconds(
+      totalTimeDuration,
+      Regex.scorm2004.CMITimespan,
+    );
+
+    let completionStatus = CompletionStatus.unknown;
+    let successStatus = SuccessStatus.unknown;
+    if (this.cmi.completion_status) {
+      if (this.cmi.completion_status === "completed") {
+        completionStatus = CompletionStatus.completed;
+      } else if (this.cmi.completion_status === "incomplete") {
+        completionStatus = CompletionStatus.incomplete;
+      }
+    }
+    if (this.cmi.success_status) {
+      if (this.cmi.success_status === "passed") {
+        successStatus = SuccessStatus.passed;
+      } else if (this.cmi.success_status === "failed") {
+        successStatus = SuccessStatus.failed;
+      }
+    }
+
+    const score = this.cmi.score;
+    let scoreObject: ScoreObject = null;
+    if (score) {
+      scoreObject = {};
+
+      if (!Number.isNaN(Number.parseFloat(score.raw))) {
+        scoreObject.raw = Number.parseFloat(score.raw);
+      }
+      if (!Number.isNaN(Number.parseFloat(score.min))) {
+        scoreObject.min = Number.parseFloat(score.min);
+      }
+      if (!Number.isNaN(Number.parseFloat(score.max))) {
+        scoreObject.max = Number.parseFloat(score.max);
+      }
+      if (!Number.isNaN(Number.parseFloat(score.scaled))) {
+        scoreObject.scaled = Number.parseFloat(score.scaled);
+      }
+    }
+
+    const commitObject: CommitObject = {
+      completionStatus: completionStatus,
+      successStatus: successStatus,
+      totalTimeSeconds: totalTimeSeconds,
+      runtimeData: cmiExport,
+    };
+    if (scoreObject) {
+      commitObject.score = scoreObject;
+    }
+    return commitObject;
+  }
+
   /**
    * Attempts to store the data to the LMS
    *
    * @param {boolean} terminateCommit
    * @return {ResultObject}
    */
-  storeData(terminateCommit: boolean): ResultObject {
+  async storeData(terminateCommit: boolean): Promise<ResultObject> {
     if (terminateCommit) {
       if (this.cmi.mode === "normal") {
         if (this.cmi.credit === "credit") {
@@ -616,18 +718,20 @@ export default class Scorm2004API extends BaseAPI {
       navRequest = true;
     }
 
-    const commitObject = this.renderCommitCMI(
-      terminateCommit || this.settings.alwaysSendTotalTime,
-    );
+    const shouldTerminateCommit =
+      terminateCommit || this.settings.alwaysSendTotalTime;
+    const commitObject = this.settings.renderCommonCommitFields
+      ? this.renderCommitObject(shouldTerminateCommit)
+      : this.renderCommitCMI(shouldTerminateCommit);
 
-    if (this.apiLogLevel === global_constants.LOG_LEVEL_DEBUG) {
+    if (this.apiLogLevel === APIConstants.global.LOG_LEVEL_DEBUG) {
       console.debug(
         "Commit (terminated: " + (terminateCommit ? "yes" : "no") + "): ",
       );
       console.debug(commitObject);
     }
     if (typeof this.settings.lmsCommitUrl === "string") {
-      const result = this.processHttpRequest(
+      const result = await this.processHttpRequest(
         this.settings.lmsCommitUrl,
         commitObject,
         terminateCommit,
@@ -646,7 +750,7 @@ export default class Scorm2004API extends BaseAPI {
       return result;
     } else {
       return {
-        result: global_constants.SCORM_TRUE,
+        result: APIConstants.global.SCORM_TRUE,
         errorCode: 0,
       };
     }

package/src/cmi/aicc/attempts.ts

@@ -0,0 +1,94 @@
+import {BaseCMI} from "../common/base_cmi";
+import {CMIScore} from "../common/score";
+import APIConstants from "../../constants/api_constants";
+import Regex from "../../constants/regex";
+import ErrorCodes from "../../constants/error_codes";
+import {AICCValidationError} from "../../exceptions";
+import {checkAICCValidFormat} from "./validation";
+import {CMIArray} from "../common/array";
+
+/**
+ * Class for cmi.student_data.attempt_records array
+ */
+export class CMIAttemptRecords extends CMIArray {
+  /**
+   * Constructor for inline Tries Array class
+   */
+  constructor() {
+    super({
+      children: APIConstants.aicc.attempt_records_children,
+    });
+  }
+}
+
+/**
+ * Class for AICC Attempt Records
+ */
+export class CMIAttemptRecordsObject extends BaseCMI {
+  /**
+   * Constructor for AICC Attempt Records object
+   */
+  constructor() {
+    super();
+    this.score = new CMIScore({
+      score_children: APIConstants.aicc.score_children,
+      score_range: Regex.aicc.score_range,
+      invalidErrorCode: ErrorCodes.scorm12.INVALID_SET_VALUE,
+      invalidTypeCode: ErrorCodes.scorm12.TYPE_MISMATCH,
+      invalidRangeCode: ErrorCodes.scorm12.VALUE_OUT_OF_RANGE,
+      errorClass: AICCValidationError,
+    });
+  }
+
+  public score: CMIScore;
+
+  /**
+   * Called when the API has been initialized after the CMI has been created
+   */
+  initialize() {
+    super.initialize();
+    this.score?.initialize();
+  }
+
+  private _lesson_status = "";
+
+  /**
+   * Getter for _lesson_status
+   * @return {string}
+   */
+  get lesson_status(): string {
+    return this._lesson_status;
+  }
+
+  /**
+   * Setter for _lesson_status
+   * @param {string} lesson_status
+   */
+  set lesson_status(lesson_status: string) {
+    if (checkAICCValidFormat(lesson_status, Regex.aicc.CMIStatus2)) {
+      this._lesson_status = lesson_status;
+    }
+  }
+
+  /**
+   * toJSON for cmi.student_data.attempt_records.n object
+   * @return {
+   *    {
+   *         lesson_status: string,
+   *         score: CMIScore
+   *     }
+   *  }
+   */
+  toJSON(): {
+    lesson_status: string;
+    score: CMIScore;
+  } {
+    this.jsonString = true;
+    const result = {
+      lesson_status: this.lesson_status,
+      score: this.score,
+    };
+    delete this.jsonString;
+    return result;
+  }
+}