scorm-again 2.0.0 → 2.2.0

package/src/cmi/scorm2004/learner_preference.ts

@@ -0,0 +1,152 @@
+/**
+ * Class for SCORM 2004's cmi.learner_preference object
+ */
+import { BaseCMI } from "../common/base_cmi";
+import APIConstants from "../../constants/api_constants";
+import { Scorm2004ValidationError } from "../../exceptions";
+import ErrorCodes from "../../constants/error_codes";
+import { check2004ValidFormat, check2004ValidRange } from "./validation";
+import Regex from "../../constants/regex";
+
+export class CMILearnerPreference extends BaseCMI {
+  private __children = APIConstants.scorm2004.student_preference_children;
+  private _audio_level = "1";
+  private _language = "";
+  private _delivery_speed = "1";
+  private _audio_captioning = "0";
+
+  /**
+   * Constructor for cmi.learner_preference
+   */
+  constructor() {
+    super();
+  }
+
+  /**
+   * Getter for __children
+   * @return {string}
+   * @private
+   */
+  get _children(): string {
+    return this.__children;
+  }
+
+  /**
+   * Setter for __children. Just throws an error.
+   * @param {string} _children
+   * @private
+   */
+  set _children(_children: string) {
+    throw new Scorm2004ValidationError(ErrorCodes.scorm2004.READ_ONLY_ELEMENT);
+  }
+
+  /**
+   * Getter for _audio_level
+   * @return {string}
+   */
+  get audio_level(): string {
+    return this._audio_level;
+  }
+
+  /**
+   * Setter for _audio_level
+   * @param {string} audio_level
+   */
+  set audio_level(audio_level: string) {
+    if (
+      check2004ValidFormat(audio_level, Regex.scorm2004.CMIDecimal) &&
+      check2004ValidRange(audio_level, Regex.scorm2004.audio_range)
+    ) {
+      this._audio_level = audio_level;
+    }
+  }
+
+  /**
+   * Getter for _language
+   * @return {string}
+   */
+  get language(): string {
+    return this._language;
+  }
+
+  /**
+   * Setter for _language
+   * @param {string} language
+   */
+  set language(language: string) {
+    if (check2004ValidFormat(language, Regex.scorm2004.CMILang)) {
+      this._language = language;
+    }
+  }
+
+  /**
+   * Getter for _delivery_speed
+   * @return {string}
+   */
+  get delivery_speed(): string {
+    return this._delivery_speed;
+  }
+
+  /**
+   * Setter for _delivery_speed
+   * @param {string} delivery_speed
+   */
+  set delivery_speed(delivery_speed: string) {
+    if (
+      check2004ValidFormat(delivery_speed, Regex.scorm2004.CMIDecimal) &&
+      check2004ValidRange(delivery_speed, Regex.scorm2004.speed_range)
+    ) {
+      this._delivery_speed = delivery_speed;
+    }
+  }
+
+  /**
+   * Getter for _audio_captioning
+   * @return {string}
+   */
+  get audio_captioning(): string {
+    return this._audio_captioning;
+  }
+
+  /**
+   * Setter for _audio_captioning
+   * @param {string} audio_captioning
+   */
+  set audio_captioning(audio_captioning: string) {
+    if (
+      check2004ValidFormat(audio_captioning, Regex.scorm2004.CMISInteger) &&
+      check2004ValidRange(audio_captioning, Regex.scorm2004.text_range)
+    ) {
+      this._audio_captioning = audio_captioning;
+    }
+  }
+
+  /**
+   * toJSON for cmi.learner_preference
+   *
+   * @return {
+   *    {
+   *      audio_level: string,
+   *      language: string,
+   *      delivery_speed: string,
+   *      audio_captioning: string
+   *    }
+   *  }
+   */
+  toJSON(): {
+    audio_level: string;
+    language: string;
+    delivery_speed: string;
+    audio_captioning: string;
+  } {
+    this.jsonString = true;
+    const result = {
+      audio_level: this.audio_level,
+      language: this.language,
+      delivery_speed: this.delivery_speed,
+      audio_captioning: this.audio_captioning,
+    };
+    delete this.jsonString;
+    return result;
+  }
+}

package/src/cmi/scorm2004/objectives.ts

@@ -0,0 +1,212 @@
+import { CMIArray } from "../common/array";
+import APIConstants from "../../constants/api_constants";
+import ErrorCodes from "../../constants/error_codes";
+import { Scorm2004ValidationError } from "../../exceptions";
+import { BaseCMI } from "../common/base_cmi";
+import { Scorm2004CMIScore } from "./score";
+import { check2004ValidFormat, check2004ValidRange } from "./validation";
+import Regex from "../../constants/regex";
+
+/**
+ * Class representing SCORM 2004's `cmi.objectives` object
+ * @extends CMIArray
+ */
+export class CMIObjectives extends CMIArray {
+  /**
+   * Constructor for `cmi.objectives` Array
+   */
+  constructor() {
+    super({
+      children: APIConstants.scorm2004.objectives_children,
+      errorCode: ErrorCodes.scorm2004.READ_ONLY_ELEMENT,
+      errorClass: Scorm2004ValidationError,
+    });
+  }
+}
+
+/**
+ * Class for SCORM 2004's cmi.objectives.n object
+ */
+export class CMIObjectivesObject extends BaseCMI {
+  private _id = "";
+  private _success_status = "unknown";
+  private _completion_status = "unknown";
+  private _progress_measure = "";
+  private _description = "";
+
+  /**
+   * Constructor for cmi.objectives.n
+   */
+  constructor() {
+    super();
+    this.score = new Scorm2004CMIScore();
+  }
+
+  public score: Scorm2004CMIScore;
+
+  /**
+   * Called when the API has been initialized after the CMI has been created
+   */
+  initialize() {
+    super.initialize();
+    this.score?.initialize();
+  }
+
+  /**
+   * Getter for _id
+   * @return {string}
+   */
+  get id(): string {
+    return this._id;
+  }
+
+  /**
+   * Setter for _id
+   * @param {string} id
+   */
+  set id(id: string) {
+    if (check2004ValidFormat(id, Regex.scorm2004.CMILongIdentifier)) {
+      this._id = id;
+    }
+  }
+
+  /**
+   * Getter for _success_status
+   * @return {string}
+   */
+  get success_status(): string {
+    return this._success_status;
+  }
+
+  /**
+   * Setter for _success_status
+   * @param {string} success_status
+   */
+  set success_status(success_status: string) {
+    if (this.initialized && this._id === "") {
+      throw new Scorm2004ValidationError(
+        ErrorCodes.scorm2004.DEPENDENCY_NOT_ESTABLISHED,
+      );
+    } else {
+      if (check2004ValidFormat(success_status, Regex.scorm2004.CMISStatus)) {
+        this._success_status = success_status;
+      }
+    }
+  }
+
+  /**
+   * Getter for _completion_status
+   * @return {string}
+   */
+  get completion_status(): string {
+    return this._completion_status;
+  }
+
+  /**
+   * Setter for _completion_status
+   * @param {string} completion_status
+   */
+  set completion_status(completion_status: string) {
+    if (this.initialized && this._id === "") {
+      throw new Scorm2004ValidationError(
+        ErrorCodes.scorm2004.DEPENDENCY_NOT_ESTABLISHED,
+      );
+    } else {
+      if (check2004ValidFormat(completion_status, Regex.scorm2004.CMICStatus)) {
+        this._completion_status = completion_status;
+      }
+    }
+  }
+
+  /**
+   * Getter for _progress_measure
+   * @return {string}
+   */
+  get progress_measure(): string {
+    return this._progress_measure;
+  }
+
+  /**
+   * Setter for _progress_measure
+   * @param {string} progress_measure
+   */
+  set progress_measure(progress_measure: string) {
+    if (this.initialized && this._id === "") {
+      throw new Scorm2004ValidationError(
+        ErrorCodes.scorm2004.DEPENDENCY_NOT_ESTABLISHED,
+      );
+    } else {
+      if (
+        check2004ValidFormat(progress_measure, Regex.scorm2004.CMIDecimal) &&
+        check2004ValidRange(progress_measure, Regex.scorm2004.progress_range)
+      ) {
+        this._progress_measure = progress_measure;
+      }
+    }
+  }
+
+  /**
+   * Getter for _description
+   * @return {string}
+   */
+  get description(): string {
+    return this._description;
+  }
+
+  /**
+   * Setter for _description
+   * @param {string} description
+   */
+  set description(description: string) {
+    if (this.initialized && this._id === "") {
+      throw new Scorm2004ValidationError(
+        ErrorCodes.scorm2004.DEPENDENCY_NOT_ESTABLISHED,
+      );
+    } else {
+      if (
+        check2004ValidFormat(
+          description,
+          Regex.scorm2004.CMILangString250,
+          true,
+        )
+      ) {
+        this._description = description;
+      }
+    }
+  }
+
+  /**
+   * toJSON for cmi.objectives.n
+   *
+   * @return {
+   *    {
+   *      id: string,
+   *      success_status: string,
+   *      completion_status: string,
+   *      progress_measure: string,
+   *      description: string,
+   *      score: Scorm2004CMIScore
+   *    }
+   *  }
+   */
+  toJSON(): {
+    id: string;
+    success_status: string;
+    completion_status: string;
+    progress_measure: string;
+    description: string;
+    score: Scorm2004CMIScore;
+  } {
+    this.jsonString = true;
+    const result = {
+      id: this.id,
+      success_status: this.success_status,
+      completion_status: this.completion_status,
+      progress_measure: this.progress_measure,
+      description: this.description,
+      score: this.score,
+    };
+    delete this.jsonString;
+    return result;
+  }
+}

package/src/cmi/scorm2004/score.ts

@@ -0,0 +1,78 @@
+/**
+ * Class for SCORM 2004's cmi *.score object
+ */
+import { CMIScore } from "../common/score";
+import APIConstants from "../../constants/api_constants";
+import ErrorCodes from "../../constants/error_codes";
+import Regex from "../../constants/regex";
+import { Scorm2004ValidationError } from "../../exceptions";
+import { check2004ValidFormat, check2004ValidRange } from "./validation";
+
+export class Scorm2004CMIScore extends CMIScore {
+  private _scaled = "";
+
+  /**
+   * Constructor for cmi *.score
+   */
+  constructor() {
+    super({
+      score_children: APIConstants.scorm2004.score_children,
+      max: "",
+      invalidErrorCode: ErrorCodes.scorm2004.READ_ONLY_ELEMENT,
+      invalidTypeCode: ErrorCodes.scorm2004.TYPE_MISMATCH,
+      invalidRangeCode: ErrorCodes.scorm2004.VALUE_OUT_OF_RANGE,
+      decimalRegex: Regex.scorm2004.CMIDecimal,
+      errorClass: Scorm2004ValidationError,
+    });
+  }
+
+  /**
+   * Getter for _scaled
+   * @return {string}
+   */
+  get scaled(): string {
+    return this._scaled;
+  }
+
+  /**
+   * Setter for _scaled
+   * @param {string} scaled
+   */
+  set scaled(scaled: string) {
+    if (
+      check2004ValidFormat(scaled, Regex.scorm2004.CMIDecimal) &&
+      check2004ValidRange(scaled, Regex.scorm2004.scaled_range)
+    ) {
+      this._scaled = scaled;
+    }
+  }
+
+  /**
+   * toJSON for cmi *.score
+   *
+   * @return {
+   *    {
+   *      scaled: string,
+   *      raw: string,
+   *      min: string,
+   *      max: string
+   *    }
+   *  }
+   */
+  toJSON(): {
+    scaled: string;
+    raw: string;
+    min: string;
+    max: string;
+  } {
+    this.jsonString = true;
+    const result = {
+      scaled: this.scaled,
+      raw: this.raw,
+      min: this.min,
+      max: this.max,
+    };
+    delete this.jsonString;
+    return result;
+  }
+}

package/src/cmi/scorm2004/validation.ts

@@ -0,0 +1,42 @@
+import { checkValidFormat, checkValidRange } from "../common/validation";
+import ErrorCodes from "../../constants/error_codes";
+import { Scorm2004ValidationError } from "../../exceptions";
+
+/**
+ * Helper method, no reason to have to pass the same error codes every time
+ * @param {string} value
+ * @param {string} regexPattern
+ * @param {boolean} allowEmptyString
+ * @return {boolean}
+ */
+export function check2004ValidFormat(
+  value: string,
+  regexPattern: string,
+  allowEmptyString?: boolean,
+): boolean {
+  return checkValidFormat(
+    value,
+    regexPattern,
+    ErrorCodes.scorm2004.TYPE_MISMATCH,
+    Scorm2004ValidationError,
+    allowEmptyString,
+  );
+}
+
+/**
+ * Helper method, no reason to have to pass the same error codes every time
+ * @param {string} value
+ * @param {string} rangePattern
+ * @return {boolean}
+ */
+export function check2004ValidRange(
+  value: string,
+  rangePattern: string,
+): boolean {
+  return checkValidRange(
+    value,
+    rangePattern,
+    ErrorCodes.scorm2004.VALUE_OUT_OF_RANGE,
+    Scorm2004ValidationError,
+  );
+}

package/src/constants/default_settings.ts

@@ -0,0 +1,82 @@
+import { ResultObject, Settings } from "../types/api_types";
+import APIConstants from "./api_constants";
+
+/**
+ * Default settings for the SCORM API
+ */
+export const DefaultSettings: Settings = {
+  autocommit: false,
+  autocommitSeconds: 10,
+  asyncCommit: false,
+  sendFullCommit: true,
+  lmsCommitUrl: false,
+  dataCommitFormat: "json",
+  commitRequestDataType: "application/json;charset=UTF-8",
+  autoProgress: false,
+  logLevel: APIConstants.global.LOG_LEVEL_ERROR,
+  selfReportSessionTime: false,
+  alwaysSendTotalTime: false,
+  renderCommonCommitFields: false,
+  strict_errors: true,
+  xhrHeaders: {},
+  xhrWithCredentials: false,
+  responseHandler: async function (response: Response): Promise<ResultObject> {
+    if (typeof response !== "undefined") {
+      const httpResult = JSON.parse(await response.text());
+      if (
+        httpResult === null ||
+        !{}.hasOwnProperty.call(httpResult, "result")
+      ) {
+        if (response.status === 200) {
+          return {
+            result: APIConstants.global.SCORM_TRUE,
+            errorCode: 0,
+          };
+        } else {
+          return {
+            result: APIConstants.global.SCORM_FALSE,
+            errorCode: 101,
+          };
+        }
+      } else {
+        return {
+          result: httpResult.result,
+          errorCode: httpResult.errorCode
+            ? httpResult.errorCode
+            : httpResult.result === APIConstants.global.SCORM_TRUE
+              ? 0
+              : 101,
+        };
+      }
+    }
+    return {
+      result: APIConstants.global.SCORM_FALSE,
+      errorCode: 101,
+    };
+  },
+  requestHandler: function (commitObject) {
+    return commitObject;
+  },
+  onLogMessage: function (messageLevel, logMessage) {
+    switch (messageLevel) {
+      case APIConstants.global.LOG_LEVEL_ERROR:
+        console.error(logMessage);
+        break;
+      case APIConstants.global.LOG_LEVEL_WARNING:
+        console.warn(logMessage);
+        break;
+      case APIConstants.global.LOG_LEVEL_INFO:
+        console.info(logMessage);
+        break;
+      case APIConstants.global.LOG_LEVEL_DEBUG:
+        if (console.debug) {
+          console.debug(logMessage);
+        } else {
+          console.log(logMessage);
+        }
+        break;
+    }
+  },
+  scoItemIds: [],
+  scoItemIdValidator: false,
+};

package/src/constants/enums.ts

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

package/src/constants/regex.ts

@@ -78,10 +78,10 @@ const scorm2004 = {
   CMIResult:
     "^(correct|incorrect|unanticipated|neutral|-?([0-9]{1,4})(\\.[0-9]{1,18})?)$",
   NAVEvent:
-    "^(previous|continue|exit|exitAll|abandon|abandonAll|suspendAll|{target=\\S{0,200}[a-zA-Z0-9]}choice|jump)$",
+    "^(previous|continue|exit|exitAll|abandon|abandonAll|suspendAll|_none_|(\\{target=\\S{0,}[a-zA-Z0-9-_]+})?choice|(\\{target=\\S{0,}[a-zA-Z0-9-_]+})?jump)$",
 
   NAVBoolean: "^(unknown|true|false$)",
-  NAVTarget: "^(previous|continue|choice.{target=\\S{0,200}[a-zA-Z0-9]})$",
+  NAVTarget: "^{target=\\S{0,}[a-zA-Z0-9-_]+}$",
   // Data ranges
   scaled_range: "-1#1",
   audio_range: "0#*",

package/src/constants/response_constants.ts

@@ -111,6 +111,7 @@ export const CorrectResponses: Responses = {
     max: 250,
     delimiter: "[,]",
     delimiter2: "[.]",
+    delimiter3: "[:]",
     unique: false,
     duplicate: false,
     format: "^$|" + scorm2004_regex.CMIShortIdentifier,
@@ -159,6 +160,7 @@ export type ResponseType = {
   format2?: string;
   delimiter2?: string;
   limit?: number;
+  delimiter3?: string;
 };
 
 export type Responses = {

package/src/exceptions.ts

@@ -1,5 +1,4 @@
 import APIConstants from "./constants/api_constants";
-import { BaseScormValidationError } from "./cmi/common";
 
 const scorm12_errors = APIConstants.scorm12.error_descriptions;
 const aicc_errors = APIConstants.aicc.error_descriptions;
@@ -11,6 +10,28 @@ type APIError = {
   detailedMessage: string;
 };
 
+export class BaseScormValidationError extends Error {
+  constructor(errorCode: number) {
+    super(errorCode.toString());
+    this._errorCode = errorCode;
+    this.name = "ScormValidationError";
+  }
+
+  private readonly _errorCode: number;
+
+  /**
+   * Getter for _errorCode
+   * @return {number}
+   */
+  get errorCode(): number {
+    return this._errorCode;
+  }
+
+  setMessage(message: string) {
+    this.message = message;
+  }
+}
+
 /**
  * Base Validation Exception
  */

package/src/helpers/scheduled_commit.ts

@@ -0,0 +1,42 @@
+import BaseAPI from "../BaseAPI";
+
+/**
+ * Private class that wraps a timeout call to the commit() function
+ */
+export class ScheduledCommit {
+  private _API;
+  private _cancelled = false;
+  private readonly _timeout;
+  private readonly _callback;
+
+  /**
+   * Constructor for ScheduledCommit
+   * @param {BaseAPI} API
+   * @param {number} when
+   * @param {string} callback
+   */
+  constructor(API: BaseAPI, when: number, callback: string) {
+    this._API = API;
+    this._timeout = setTimeout(this.wrapper.bind(this), when);
+    this._callback = callback;
+  }
+
+  /**
+   * Cancel any currently scheduled commit
+   */
+  cancel() {
+    this._cancelled = true;
+    if (this._timeout) {
+      clearTimeout(this._timeout);
+    }
+  }
+
+  /**
+   * Wrap the API commit call to check if the call has already been cancelled
+   */
+  wrapper() {
+    if (!this._cancelled) {
+      (async () => await this._API.commit(this._callback))();
+    }
+  }
+}