scorm-again 2.0.0 → 2.1.0

package/src/cmi/aicc/student_preferences.ts

@@ -0,0 +1,176 @@
+import { CMIArray } from "../common/array";
+import { AICCValidationError } from "../../exceptions";
+import { checkAICCValidFormat } from "./validation";
+import ErrorCodes from "../../constants/error_codes";
+import Regex from "../../constants/regex";
+import APIConstants from "../../constants/api_constants";
+import { CMIStudentPreference } from "../scorm12/student_preference";
+
+/**
+ * StudentPreferences class for AICC
+ */
+export class AICCStudentPreferences extends CMIStudentPreference {
+  /**
+   * Constructor for AICC Student Preferences object
+   */
+  constructor() {
+    super(APIConstants.aicc.student_preference_children);
+    this.windows = new CMIArray({
+      errorCode: ErrorCodes.scorm12.INVALID_SET_VALUE,
+      errorClass: AICCValidationError,
+      children: "",
+    });
+  }
+
+  public windows: CMIArray;
+
+  /**
+   * Called when the API has been initialized after the CMI has been created
+   */
+  initialize() {
+    super.initialize();
+    this.windows?.initialize();
+  }
+
+  private _lesson_type = "";
+  private _text_color = "";
+  private _text_location = "";
+  private _text_size = "";
+  private _video = "";
+
+  /**
+   * Getter for _lesson_type
+   * @return {string}
+   */
+  get lesson_type(): string {
+    return this._lesson_type;
+  }
+
+  /**
+   * Setter for _lesson_type
+   * @param {string} lesson_type
+   */
+  set lesson_type(lesson_type: string) {
+    if (checkAICCValidFormat(lesson_type, Regex.aicc.CMIString256)) {
+      this._lesson_type = lesson_type;
+    }
+  }
+
+  /**
+   * Getter for _text_color
+   * @return {string}
+   */
+  get text_color(): string {
+    return this._text_color;
+  }
+
+  /**
+   * Setter for _text_color
+   * @param {string} text_color
+   */
+  set text_color(text_color: string) {
+    if (checkAICCValidFormat(text_color, Regex.aicc.CMIString256)) {
+      this._text_color = text_color;
+    }
+  }
+
+  /**
+   * Getter for _text_location
+   * @return {string}
+   */
+  get text_location(): string {
+    return this._text_location;
+  }
+
+  /**
+   * Setter for _text_location
+   * @param {string} text_location
+   */
+  set text_location(text_location: string) {
+    if (checkAICCValidFormat(text_location, Regex.aicc.CMIString256)) {
+      this._text_location = text_location;
+    }
+  }
+
+  /**
+   * Getter for _text_size
+   * @return {string}
+   */
+  get text_size(): string {
+    return this._text_size;
+  }
+
+  /**
+   * Setter for _text_size
+   * @param {string} text_size
+   */
+  set text_size(text_size: string) {
+    if (checkAICCValidFormat(text_size, Regex.aicc.CMIString256)) {
+      this._text_size = text_size;
+    }
+  }
+
+  /**
+   * Getter for _video
+   * @return {string}
+   */
+  get video(): string {
+    return this._video;
+  }
+
+  /**
+   * Setter for _video
+   * @param {string} video
+   */
+  set video(video: string) {
+    if (checkAICCValidFormat(video, Regex.aicc.CMIString256)) {
+      this._video = video;
+    }
+  }
+
+  /**
+   * toJSON for cmi.student_preference
+   *
+   * @return {
+   *    {
+   *      audio: string,
+   *      language: string,
+   *      speed: string,
+   *      text: string,
+   *      text_color: string,
+   *      text_location: string,
+   *      text_size: string,
+   *      video: string,
+   *      windows: CMIArray
+   *    }
+   *  }
+   */
+  toJSON(): {
+    audio: string;
+    language: string;
+    lesson_type: string;
+    speed: string;
+    text: string;
+    text_color: string;
+    text_location: string;
+    text_size: string;
+    video: string;
+    windows: CMIArray;
+  } {
+    this.jsonString = true;
+    const result = {
+      audio: this.audio,
+      language: this.language,
+      lesson_type: this.lesson_type,
+      speed: this.speed,
+      text: this.text,
+      text_color: this.text_color,
+      text_location: this.text_location,
+      text_size: this.text_size,
+      video: this.video,
+      windows: this.windows,
+    };
+    delete this.jsonString;
+    return result;
+  }
+}

package/src/cmi/aicc/tries.ts

@@ -0,0 +1,116 @@
+import {CMIArray} from "../common/array";
+import APIConstants from "../../constants/api_constants";
+import {BaseCMI} from "../common/base_cmi";
+import {CMIScore} from "../common/score";
+import Regex from "../../constants/regex";
+import ErrorCodes from "../../constants/error_codes";
+import {AICCValidationError} from "../../exceptions";
+import {checkAICCValidFormat} from "./validation";
+
+/**
+ * Class representing the AICC cmi.student_data.tries object
+ */
+export class CMITries extends CMIArray {
+  /**
+   * Constructor for inline Tries Array class
+   */
+  constructor() {
+    super({
+      children: APIConstants.aicc.tries_children,
+    });
+  }
+}
+
+/**
+ * Class for AICC Tries
+ */
+export class CMITriesObject extends BaseCMI {
+  /**
+   * Constructor for AICC Tries 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 _status = "";
+  private _time = "";
+
+  /**
+   * Getter for _status
+   * @return {string}
+   */
+  get status(): string {
+    return this._status;
+  }
+
+  /**
+   * Setter for _status
+   * @param {string} status
+   */
+  set status(status: string) {
+    if (checkAICCValidFormat(status, Regex.aicc.CMIStatus2)) {
+      this._status = status;
+    }
+  }
+
+  /**
+   * Getter for _time
+   * @return {string}
+   */
+  get time(): string {
+    return this._time;
+  }
+
+  /**
+   * Setter for _time
+   * @param {string} time
+   */
+  set time(time: string) {
+    if (checkAICCValidFormat(time, Regex.aicc.CMITime)) {
+      this._time = time;
+    }
+  }
+
+  /**
+   * toJSON for cmi.student_data.tries.n object
+   * @return {
+   *    {
+   *      status: string,
+   *      time: string,
+   *      score: CMIScore
+   *    }
+   *  }
+   */
+  toJSON(): {
+    status: string;
+    time: string;
+    score: CMIScore;
+  } {
+    this.jsonString = true;
+    const result = {
+      status: this.status,
+      time: this.time,
+      score: this.score,
+    };
+    delete this.jsonString;
+    return result;
+  }
+}

package/src/cmi/aicc/validation.ts

@@ -0,0 +1,25 @@
+import { checkValidFormat } from "../common/validation";
+import { AICCValidationError } from "../../exceptions";
+import ErrorCodes from "../../constants/error_codes";
+const aicc_error_codes = ErrorCodes.scorm12;
+
+/**
+ * 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 checkAICCValidFormat(
+  value: string,
+  regexPattern: string,
+  allowEmptyString?: boolean,
+): boolean {
+  return checkValidFormat(
+    value,
+    regexPattern,
+    aicc_error_codes.TYPE_MISMATCH,
+    AICCValidationError,
+    allowEmptyString,
+  );
+}

package/src/cmi/common/array.ts

@@ -0,0 +1,77 @@
+import { BaseCMI } from "./base_cmi";
+import ErrorCodes from "../../constants/error_codes";
+import { BaseScormValidationError } from "../../exceptions";
+
+export const scorm12_error_codes = ErrorCodes.scorm12;
+
+/**
+ * Base class for cmi *.n objects
+ */
+export class CMIArray extends BaseCMI {
+  private readonly _errorCode: number;
+  private readonly _errorClass: typeof BaseScormValidationError;
+  private readonly __children: string;
+  childArray: any[];
+
+  /**
+   * Constructor cmi *.n arrays
+   * @param {object} params
+   */
+  constructor(params: {
+    children: string;
+    errorCode?: number;
+    errorClass?: typeof BaseScormValidationError;
+  }) {
+    super();
+    this.__children = params.children;
+    this._errorCode = params.errorCode || scorm12_error_codes.GENERAL;
+    this._errorClass = params.errorClass || BaseScormValidationError;
+    this.childArray = [];
+  }
+
+  /**
+   * Getter for _children
+   * @return {string}
+   */
+  get _children(): string {
+    return this.__children;
+  }
+
+  /**
+   * Setter for _children. Just throws an error.
+   * @param {string} _children
+   */
+  set _children(_children: string) {
+    throw new this._errorClass(this._errorCode);
+  }
+
+  /**
+   * Getter for _count
+   * @return {number}
+   */
+  get _count(): number {
+    return this.childArray.length;
+  }
+
+  /**
+   * Setter for _count. Just throws an error.
+   * @param {number} _count
+   */
+  set _count(_count: number) {
+    throw new this._errorClass(this._errorCode);
+  }
+
+  /**
+   * toJSON for *.n arrays
+   * @return {object}
+   */
+  toJSON(): object {
+    this.jsonString = true;
+    const result: { [key: string]: any } = {};
+    for (let i = 0; i < this.childArray.length; i++) {
+      result[i + ""] = this.childArray[i];
+    }
+    delete this.jsonString;
+    return result;
+  }
+}

package/src/cmi/common/base_cmi.ts

@@ -0,0 +1,46 @@
+/**
+ * Base class for API cmi objects
+ */
+export abstract class BaseCMI {
+  jsonString? = false;
+  private _initialized = false;
+  private _start_time: number | undefined;
+
+  /**
+   * Getter for _initialized
+   * @return {boolean}
+   */
+  get initialized(): boolean {
+    return this._initialized;
+  }
+
+  /**
+   * Getter for _start_time
+   * @return {number | undefined}
+   */
+  get start_time(): number | undefined {
+    return this._start_time;
+  }
+
+  /**
+   * Called when the API has been initialized after the CMI has been created
+   */
+  initialize(): void {
+    this._initialized = true;
+  }
+
+  /**
+   * Called when the player should override the 'session_time' provided by
+   * the module
+   */
+  setStartTime(): void {
+    this._start_time = new Date().getTime();
+  }
+}
+
+/**
+ * Base class for cmi root objects
+ */
+export abstract class BaseRootCMI extends BaseCMI {
+  abstract getCurrentTotalTime(): string;
+}

package/src/cmi/common/score.ts

@@ -0,0 +1,203 @@
+import APIConstants from "../../constants/api_constants";
+import Regex from "../../constants/regex";
+import { BaseCMI } from "./base_cmi";
+import { checkValidFormat, checkValidRange } from "./validation";
+import ErrorCodes from "../../constants/error_codes";
+import { BaseScormValidationError } from "../../exceptions";
+
+const scorm12_constants = APIConstants.scorm12;
+const scorm12_regex = Regex.scorm12;
+export const scorm12_error_codes = ErrorCodes.scorm12;
+
+/**
+ * Base class for cmi *.score objects
+ */
+export class CMIScore extends BaseCMI {
+  private readonly __children: string;
+  private readonly __score_range: string | false;
+  private readonly __invalid_error_code: number;
+  private readonly __invalid_type_code: number;
+  private readonly __invalid_range_code: number;
+  private readonly __decimal_regex: string;
+  private readonly __error_class: typeof BaseScormValidationError;
+  private _raw = "";
+  private _min = "";
+  private _max: string;
+
+  /**
+   * Constructor for *.score
+   * @param {
+   *     score_children: string,
+   *     score_range: string,
+   *     max: string,
+   *     invalidErrorCode: number,
+   *     invalidTypeCode: number,
+   *     invalidRangeCode: number,
+   *     decimalRegex: string,
+   *     errorClass: typeof BaseScormValidationError
+   * } params
+   */
+  constructor(params: {
+    score_children?: string;
+    score_range?: string;
+    max?: string;
+    invalidErrorCode?: number;
+    invalidTypeCode?: number;
+    invalidRangeCode?: number;
+    decimalRegex?: string;
+    errorClass: typeof BaseScormValidationError;
+  }) {
+    super();
+
+    this.__children = params.score_children || scorm12_constants.score_children;
+    this.__score_range = !params.score_range
+      ? false
+      : scorm12_regex.score_range;
+    this._max = params.max || params.max === "" ? params.max : "100";
+    this.__invalid_error_code =
+      params.invalidErrorCode || scorm12_error_codes.INVALID_SET_VALUE;
+    this.__invalid_type_code =
+      params.invalidTypeCode || scorm12_error_codes.TYPE_MISMATCH;
+    this.__invalid_range_code =
+      params.invalidRangeCode || scorm12_error_codes.VALUE_OUT_OF_RANGE;
+    this.__decimal_regex = params.decimalRegex || scorm12_regex.CMIDecimal;
+    this.__error_class = params.errorClass;
+  }
+
+  /**
+   * Getter for _children
+   * @return {string}
+   */
+  get _children(): string {
+    return this.__children;
+  }
+
+  /**
+   * Setter for _children. Just throws an error.
+   * @param {string} _children
+   */
+  set _children(_children: string) {
+    throw new this.__error_class(this.__invalid_error_code);
+  }
+
+  /**
+   * Getter for _raw
+   * @return {string}
+   */
+  get raw(): string {
+    return this._raw;
+  }
+
+  /**
+   * Setter for _raw
+   * @param {string} raw
+   */
+  set raw(raw: string) {
+    if (
+      checkValidFormat(
+        raw,
+        this.__decimal_regex,
+        this.__invalid_type_code,
+        this.__error_class,
+      ) &&
+      (!this.__score_range ||
+        checkValidRange(
+          raw,
+          this.__score_range,
+          this.__invalid_range_code,
+          this.__error_class,
+        ))
+    ) {
+      this._raw = raw;
+    }
+  }
+
+  /**
+   * Getter for _min
+   * @return {string}
+   */
+  get min(): string {
+    return this._min;
+  }
+
+  /**
+   * Setter for _min
+   * @param {string} min
+   */
+  set min(min: string) {
+    if (
+      checkValidFormat(
+        min,
+        this.__decimal_regex,
+        this.__invalid_type_code,
+        this.__error_class,
+      ) &&
+      (!this.__score_range ||
+        checkValidRange(
+          min,
+          this.__score_range,
+          this.__invalid_range_code,
+          this.__error_class,
+        ))
+    ) {
+      this._min = min;
+    }
+  }
+
+  /**
+   * Getter for _max
+   * @return {string}
+   */
+  get max(): string {
+    return this._max;
+  }
+
+  /**
+   * Setter for _max
+   * @param {string} max
+   */
+  set max(max: string) {
+    if (
+      checkValidFormat(
+        max,
+        this.__decimal_regex,
+        this.__invalid_type_code,
+        this.__error_class,
+      ) &&
+      (!this.__score_range ||
+        checkValidRange(
+          max,
+          this.__score_range,
+          this.__invalid_range_code,
+          this.__error_class,
+        ))
+    ) {
+      this._max = max;
+    }
+  }
+
+  /**
+   * toJSON for *.score
+   * @return {
+   *    {
+   *      min: string,
+   *      max: string,
+   *      raw: string
+   *    }
+   *    }
+   */
+  toJSON(): {
+    min: string;
+    max: string;
+    raw: string;
+  } {
+    this.jsonString = true;
+    const result = {
+      raw: this.raw,
+      min: this.min,
+      max: this.max,
+    };
+    delete this.jsonString;
+    return result;
+  }
+}

package/src/cmi/common/validation.ts

@@ -0,0 +1,60 @@
+import { BaseScormValidationError } from "../../exceptions";
+
+/**
+ * Check if the value matches the proper format. If not, throw proper error code.
+ *
+ * @param {string} value
+ * @param {string} regexPattern
+ * @param {number} errorCode
+ * @param {typeof BaseScormValidationError} errorClass
+ * @param {boolean} [allowEmptyString]
+ * @return {boolean}
+ */
+export function checkValidFormat(
+  value: string,
+  regexPattern: string,
+  errorCode: number,
+  errorClass: typeof BaseScormValidationError,
+  allowEmptyString?: boolean,
+): boolean {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const formatRegex = new RegExp(regexPattern);
+  const matches = value.match(formatRegex);
+  if (allowEmptyString && value === "") {
+    return true;
+  }
+  if (value === undefined || !matches || matches[0] === "") {
+    throw new errorClass(errorCode);
+  }
+  return true;
+}
+
+/**
+ * Check if the value matches the proper range. If not, throw proper error code.
+ *
+ * @param {any} value
+ * @param {string} rangePattern
+ * @param {number} errorCode
+ * @param {typeof BaseScormValidationError} errorClass
+ * @return {boolean}
+ */
+export function checkValidRange(
+  value: any,
+  rangePattern: string,
+  errorCode: number,
+  errorClass: typeof BaseScormValidationError,
+): boolean {
+  const ranges = rangePattern.split("#");
+  value = value * 1.0;
+  if (value >= ranges[0]) {
+    if (ranges[1] === "*" || value <= ranges[1]) {
+      return true;
+    } else {
+      throw new errorClass(errorCode);
+    }
+  } else {
+    throw new errorClass(errorCode);
+  }
+}