scorm-again 2.1.0 → 2.3.0

package/index.d.ts

@@ -0,0 +1,5 @@
+import Scorm2004API from "./src/Scorm2004API.ts";
+import Scorm12API from "./src/Scorm12API.ts";
+import AICC from "./src/AICC.ts";
+
+export { Scorm2004API, Scorm12API, AICC };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "scorm-again",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "A modern SCORM JavaScript run-time library for AICC, SCORM 1.2, and SCORM 2004",
-  "main": "dist/scorm-again.min.js",
+  "main": "index.d.ts",
   "type": "module",
   "browser": {
     "electron": false
@@ -20,17 +20,16 @@
     "test": "test"
   },
   "devDependencies": {
-    "@babel/cli": "^7.25.7",
-    "@babel/core": "^7.25.7",
-    "@babel/eslint-parser": "^7.25.7",
-    "@babel/node": "^7.25.7",
-    "@babel/preset-env": "^7.25.7",
-    "@babel/preset-typescript": "^7.25.7",
+    "@babel/cli": "^7.25.9",
+    "@babel/core": "^7.25.9",
+    "@babel/eslint-parser": "^7.25.9",
+    "@babel/node": "^7.25.9",
+    "@babel/preset-env": "^7.25.9",
+    "@babel/preset-typescript": "^7.25.9",
     "@eslint/eslintrc": "^3.1.0",
-    "@eslint/js": "^9.12.0",
+    "@eslint/js": "^9.13.0",
     "@istanbuljs/nyc-config-typescript": "^1.0.2",
     "@types/eslint__js": "^8.42.3",
-    "@types/expect": "^24.3.0",
     "@types/mocha": "^10.0.9",
     "@types/sinon": "^17.0.3",
     "babel-eslint": "^11.0.0-beta.2",
@@ -39,15 +38,15 @@
     "browserify": "^17.0.1",
     "c8": "^10.1.2",
     "c8-as-nyc": "^1.1.11",
-    "eslint": "^9.12.0",
+    "eslint": "^9.13.0",
     "eslint-formatter-junit": "^8.40.0",
     "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-jsdoc": "^50.3.1",
+    "eslint-plugin-jsdoc": "^50.4.3",
     "eslint-webpack-plugin": "^4.2.0",
     "expect": "^29.7.0",
     "fetch-pretender": "https://github.com/jcputney/fetch-pretender#master",
     "globals": "^15.11.0",
-    "jsdoc": "^4.0.3",
+    "jsdoc": "^4.0.4",
     "jsdoc-babel": "^0.5.0",
     "minimist": "^1.2.8",
     "miragejs": "^0.2.0-alpha.3",
@@ -60,7 +59,7 @@
     "ts-loader": "^9.5.1",
     "tsx": "^4.19.1",
     "typescript": "^5.6.3",
-    "typescript-eslint": "^8.8.1",
+    "typescript-eslint": "^8.11.0",
     "webpack": "^5.91.0",
     "webpack-cli": "^5.1.4"
   },

package/src/BaseAPI.ts

@@ -5,7 +5,12 @@ import APIConstants from "./constants/api_constants";
 import { formatMessage, stringMatches, unflatten } from "./utilities";
 import { BaseCMI } from "./cmi/common/base_cmi";
 import { debounce } from "./utilities/debounce";
-import { RefObject, ResultObject, Settings } from "./types/api_types";
+import {
+  RefObject,
+  CommitObject,
+  ResultObject,
+  Settings,
+} from "./types/api_types";
 import { DefaultSettings } from "./constants/default_settings";
 import { IBaseAPI } from "./interfaces/IBaseAPI";
 import { ScheduledCommit } from "./helpers/scheduled_commit";
@@ -165,6 +170,13 @@ export default abstract class BaseAPI implements IBaseAPI {
    */
   abstract renderCommitCMI(_terminateCommit: boolean): RefObject | Array<any>;
 
+  /**
+   * Render the commit object to the shortened format for LMS commit
+   * @param {boolean} _terminateCommit
+   * @return {CommitObject}
+   */
+  abstract renderCommitObject(_terminateCommit: boolean): CommitObject;
+
   /**
    * Logging for all SCORM actions
    *
@@ -1114,13 +1126,13 @@ export default abstract class BaseAPI implements IBaseAPI {
   /**
    * Send the request to the LMS
    * @param {string} url
-   * @param {RefObject|Array} params
+   * @param {CommitObject|RefObject|Array} params
    * @param {boolean} immediate
    * @return {ResultObject}
    */
   async processHttpRequest(
     url: string,
-    params: RefObject | Array<any>,
+    params: CommitObject | RefObject | Array<any>,
     immediate: boolean = false,
   ): Promise<ResultObject> {
     const api = this;
@@ -1143,7 +1155,7 @@ export default abstract class BaseAPI implements IBaseAPI {
 
     const process = async (
       url: string,
-      params: RefObject | Array<any>,
+      params: CommitObject | RefObject | Array<any>,
       settings: Settings,
     ): Promise<ResultObject> => {
       try {

package/src/Scorm12API.ts

@@ -1,6 +1,7 @@
 import BaseAPI from "./BaseAPI";
 import { CMI } from "./cmi/scorm12/cmi";
 import * as Utilities from "./utilities";
+import { stringMatches } from "./utilities";
 import APIConstants from "./constants/api_constants";
 import ErrorCodes from "./constants/error_codes";
 
@@ -12,8 +13,15 @@ import {
   CMIInteractionsObjectivesObject,
 } from "./cmi/scorm12/interactions";
 import { NAV } from "./cmi/scorm12/nav";
-import { RefObject, ResultObject, Settings } from "./types/api_types";
-import { stringMatches } from "./utilities";
+import {
+  CommitObject,
+  RefObject,
+  ResultObject,
+  ScoreObject,
+  Settings,
+} from "./types/api_types";
+import Regex from "./constants/regex";
+import { CompletionStatus, SuccessStatus } from "./constants/enums";
 
 /**
  * API class for SCORM 1.2
@@ -320,6 +328,61 @@ export default class Scorm12API 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 totalTimeHHMMSS = this.cmi.getCurrentTotalTime();
+    const totalTimeSeconds = Utilities.getTimeAsSeconds(
+      totalTimeHHMMSS,
+      Regex.scorm12.CMITimespan,
+    );
+    const lessonStatus = this.cmi.core.lesson_status;
+    let completionStatus = CompletionStatus.unknown;
+    let successStatus = SuccessStatus.unknown;
+    if (lessonStatus) {
+      completionStatus =
+        lessonStatus === "completed" || lessonStatus === "passed"
+          ? CompletionStatus.completed
+          : CompletionStatus.incomplete;
+      if (lessonStatus === "passed") {
+        successStatus = SuccessStatus.passed;
+      } else if (lessonStatus === "failed") {
+        successStatus = SuccessStatus.failed;
+      }
+    }
+
+    const score = this.cmi.core.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);
+      }
+    }
+
+    const commitObject: CommitObject = {
+      successStatus: successStatus,
+      completionStatus: completionStatus,
+      runtimeData: cmiExport,
+      totalTimeSeconds: totalTimeSeconds,
+    };
+    if (scoreObject) {
+      commitObject.score = scoreObject;
+    }
+    return commitObject;
+  }
+
   /**
    * Attempts to store the data to the LMS
    *
@@ -361,9 +424,11 @@ export default class Scorm12API extends BaseAPI {
       }
     }
 
-    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 === APIConstants.global.LOG_LEVEL_DEBUG) {
       console.debug(

package/src/Scorm2004API.ts

@@ -18,7 +18,14 @@ import {
 import { CMICommentsObject } from "./cmi/scorm2004/comments";
 import { CMIObjectivesObject } from "./cmi/scorm2004/objectives";
 import { ADL } from "./cmi/scorm2004/adl";
-import { RefObject, ResultObject, Settings } from "./types/api_types";
+import {
+  CommitObject,
+  RefObject,
+  ResultObject,
+  ScoreObject,
+  Settings,
+} from "./types/api_types";
+import { CompletionStatus, SuccessStatus } from "./constants/enums";
 
 /**
  * API class for SCORM 2004
@@ -613,6 +620,67 @@ 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
    *
@@ -650,9 +718,11 @@ 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 === APIConstants.global.LOG_LEVEL_DEBUG) {
       console.debug(

package/src/constants/default_settings.ts

@@ -16,6 +16,7 @@ export const DefaultSettings: Settings = {
   logLevel: APIConstants.global.LOG_LEVEL_ERROR,
   selfReportSessionTime: false,
   alwaysSendTotalTime: false,
+  renderCommonCommitFields: false,
   strict_errors: true,
   xhrHeaders: {},
   xhrWithCredentials: false,

package/src/constants/enums.ts

@@ -3,3 +3,15 @@ export enum NAVBoolean {
   true = "true",
   false = "false",
 }
+
+export enum SuccessStatus {
+  passed = "passed",
+  failed = "failed",
+  unknown = "unknown",
+}
+
+export enum CompletionStatus {
+  completed = "completed",
+  incomplete = "incomplete",
+  unknown = "unknown",
+}

package/src/types/api_types.ts

@@ -1,3 +1,5 @@
+import { CompletionStatus, SuccessStatus } from "../constants/enums";
+
 export type Settings = {
   autocommit?: boolean;
   autocommitSeconds?: number;
@@ -19,6 +21,7 @@ export type Settings = {
   scoItemIds?: string[];
   scoItemIdValidator?: false | ((scoItemId: string) => boolean);
   mastery_override?: boolean;
+  renderCommonCommitFields?: boolean;
 };
 
 export type RefObject = {
@@ -30,3 +33,18 @@ export type ResultObject = {
   errorCode: number;
   navRequest?: string;
 };
+
+export type ScoreObject = {
+  raw?: number;
+  min?: number;
+  max?: number;
+  scaled?: number;
+};
+
+export type CommitObject = {
+  successStatus: SuccessStatus;
+  completionStatus: CompletionStatus;
+  totalTimeSeconds: number;
+  runtimeData: RefObject;
+  score?: ScoreObject;
+};

package/test/Scorm12API.spec.ts

@@ -358,6 +358,116 @@ describe("SCORM 1.2 API Tests", () => {
       const cmiExport: RefObject = scorm12API.renderCommitCMI(true);
       expect(cmiExport.cmi.core.total_time).toEqual("23:59:59");
     });
+    it("should return flattened format when dataCommitFormat is 'flattened'", function () {
+      const scorm12API = api({
+        ...DefaultSettings,
+        ...{ dataCommitFormat: "flattened" },
+      });
+      scorm12API.cmi.core.student_id = "student_1";
+      scorm12API.cmi.core.student_name = "Student 1";
+      scorm12API.cmi.core.lesson_status = "completed";
+      scorm12API.cmi.core.score.raw = "100";
+      scorm12API.cmi.core.score.max = "100";
+      scorm12API.cmi.core.score.min = "0";
+      scorm12API.cmi.core.session_time = "23:59:59";
+      const cmiExport: RefObject = scorm12API.renderCommitCMI(true);
+      expect(cmiExport["cmi.core.student_id"]).toEqual("student_1");
+      expect(cmiExport["cmi.core.student_name"]).toEqual("Student 1");
+      expect(cmiExport["cmi.core.lesson_status"]).toEqual("completed");
+      expect(cmiExport["cmi.core.score.raw"]).toEqual("100");
+      expect(cmiExport["cmi.core.score.max"]).toEqual("100");
+      expect(cmiExport["cmi.core.score.min"]).toEqual("0");
+      expect(cmiExport["cmi.core.session_time"]).toEqual("23:59:59");
+    });
+    it("should return params format when dataCommitFormat is 'params'", function () {
+      const scorm12API = api({
+        ...DefaultSettings,
+        ...{ dataCommitFormat: "params" },
+      });
+      scorm12API.cmi.core.student_id = "student_1";
+      scorm12API.cmi.core.student_name = "Student 1";
+      scorm12API.cmi.core.lesson_status = "completed";
+      scorm12API.cmi.core.score.raw = "100";
+      scorm12API.cmi.core.score.max = "100";
+      scorm12API.cmi.core.score.min = "0";
+      scorm12API.cmi.core.session_time = "23:59:59";
+      const result = scorm12API.renderCommitCMI(true);
+      expect(result).toBeInstanceOf(Array);
+      expect(result).toContain("cmi.core.lesson_status=completed");
+      expect(result).toContain("cmi.core.score.max=100");
+      expect(result).toContain("cmi.core.score.min=0");
+      expect(result).toContain("cmi.core.score.raw=100");
+      expect(result).toContain("cmi.core.session_time=23:59:59");
+      expect(result).toContain("cmi.core.student_id=student_1");
+    });
+  });
+
+  describe("renderCommitObject()", () => {
+    it("should render commit object with default settings and no score", () => {
+      const scorm12API = api();
+      scorm12API.cmi.core.lesson_status = "incomplete";
+      scorm12API.cmi.core.total_time = "12:34:56";
+      scorm12API.cmi.core.session_time = "23:59:59";
+      const commitObject = scorm12API.renderCommitObject(true);
+      expect(commitObject.successStatus).toEqual("unknown");
+      expect(commitObject.completionStatus).toEqual("incomplete");
+      expect(commitObject.runtimeData.cmi.core.lesson_status).toEqual(
+        "incomplete",
+      );
+      expect(commitObject.totalTimeSeconds).toEqual(
+        12 * 3600 + 34 * 60 + 56 + (23 * 3600 + 59 * 60 + 59),
+      );
+      expect(commitObject.score.max).toEqual(100);
+    });
+
+    it("should render commit object with score data", () => {
+      const scorm12API = api();
+      scorm12API.cmi.core.lesson_status = "completed";
+      scorm12API.cmi.core.score.raw = "85";
+      scorm12API.cmi.core.score.min = "0";
+      scorm12API.cmi.core.score.max = "100";
+      const commitObject = scorm12API.renderCommitObject(true);
+      expect(commitObject.successStatus).toEqual("unknown");
+      expect(commitObject.completionStatus).toEqual("completed");
+      expect(commitObject.runtimeData.cmi.core.lesson_status).toEqual(
+        "completed",
+      );
+      expect(commitObject.runtimeData.cmi.core.score.raw).toEqual("85");
+      expect(commitObject.runtimeData.cmi.core.score.min).toEqual("0");
+      expect(commitObject.runtimeData.cmi.core.score.max).toEqual("100");
+      expect(commitObject.totalTimeSeconds).toEqual(0);
+      expect(commitObject.score).toEqual({
+        raw: 85,
+        min: 0,
+        max: 100,
+      });
+    });
+
+    it("should render commit object with completion and success status", () => {
+      const scorm12API = api();
+      scorm12API.cmi.core.lesson_status = "passed";
+      const commitObject = scorm12API.renderCommitObject(true);
+      expect(commitObject.successStatus).toEqual("passed");
+      expect(commitObject.completionStatus).toEqual("completed");
+      expect(commitObject.runtimeData.cmi.core.lesson_status).toEqual("passed");
+    });
+
+    it("should render commit object with failed success status", () => {
+      const scorm12API = api();
+      scorm12API.cmi.core.lesson_status = "failed";
+      const commitObject = scorm12API.renderCommitObject(true);
+      expect(commitObject.successStatus).toEqual("failed");
+      expect(commitObject.completionStatus).toEqual("incomplete");
+      expect(commitObject.runtimeData.cmi.core.lesson_status).toEqual("failed");
+    });
+
+    it("should calculate total time when terminateCommit is true", () => {
+      const scorm12API = api();
+      scorm12API.cmi.core.total_time = "12:34:56";
+      scorm12API.cmi.core.session_time = "23:59:59";
+      const commitObject = scorm12API.renderCommitObject(true);
+      expect(commitObject.runtimeData.cmi.core.total_time).toEqual("36:34:55");
+    });
   });
 
   describe("storeData()", () => {

package/test/Scorm2004API.spec.ts

@@ -827,6 +827,76 @@ describe("SCORM 2004 API Tests", () => {
     });
   });
 
+  describe("renderCommitObject()", () => {
+    it("should render commit object with default settings and no score", () => {
+      const scorm2004API = api();
+      scorm2004API.cmi.completion_status = "incomplete";
+      scorm2004API.cmi.total_time = "P12H34M56S";
+      scorm2004API.cmi.session_time = "P23H59M59S";
+      const commitObject = scorm2004API.renderCommitObject(true);
+      expect(commitObject.successStatus).toEqual("unknown");
+      expect(commitObject.completionStatus).toEqual("incomplete");
+      expect(commitObject.runtimeData.cmi.completion_status).toEqual(
+        "incomplete",
+      );
+      expect(commitObject.totalTimeSeconds).toEqual(
+        12 * 3600 + 34 * 60 + 56 + (23 * 3600 + 59 * 60 + 59),
+      );
+    });
+
+    it("should render commit object with score data", () => {
+      const scorm2004API = api();
+      scorm2004API.cmi.completion_status = "completed";
+      scorm2004API.cmi.score.raw = "85";
+      scorm2004API.cmi.score.min = "0";
+      scorm2004API.cmi.score.max = "100";
+      scorm2004API.cmi.score.scaled = "0.85";
+      const commitObject = scorm2004API.renderCommitObject(true);
+      expect(commitObject.successStatus).toEqual("unknown");
+      expect(commitObject.completionStatus).toEqual("completed");
+      expect(commitObject.runtimeData.cmi.completion_status).toEqual(
+        "completed",
+      );
+      expect(commitObject.runtimeData.cmi.score.raw).toEqual("85");
+      expect(commitObject.runtimeData.cmi.score.min).toEqual("0");
+      expect(commitObject.runtimeData.cmi.score.max).toEqual("100");
+      expect(commitObject.runtimeData.cmi.score.scaled).toEqual("0.85");
+      expect(commitObject.totalTimeSeconds).toEqual(0);
+      expect(commitObject.score).toEqual({
+        raw: 85,
+        min: 0,
+        max: 100,
+        scaled: 0.85,
+      });
+    });
+
+    it("should render commit object with completion and success status", () => {
+      const scorm2004API = api();
+      scorm2004API.cmi.success_status = "passed";
+      const commitObject = scorm2004API.renderCommitObject(true);
+      expect(commitObject.successStatus).toEqual("passed");
+      expect(commitObject.completionStatus).toEqual("unknown");
+      expect(commitObject.runtimeData.cmi.success_status).toEqual("passed");
+    });
+
+    it("should render commit object with failed success status", () => {
+      const scorm2004API = api();
+      scorm2004API.cmi.success_status = "failed";
+      const commitObject = scorm2004API.renderCommitObject(true);
+      expect(commitObject.successStatus).toEqual("failed");
+      expect(commitObject.completionStatus).toEqual("unknown");
+      expect(commitObject.runtimeData.cmi.success_status).toEqual("failed");
+    });
+
+    it("should calculate total time when terminateCommit is true", () => {
+      const scorm2004API = api();
+      scorm2004API.cmi.total_time = "P12H34M56S";
+      scorm2004API.cmi.session_time = "P23H59M59S";
+      const commitObject = scorm2004API.renderCommitObject(true);
+      expect(commitObject.runtimeData.cmi.total_time).toEqual("P1DT12H34M55S");
+    });
+  });
+
   describe("lmsGetDiagnostic()", () => {
     it("should return diagnostic information for a given error code", () => {
       const scorm2004API = api();