scorm-again 1.7.1 → 2.1.0

package/src/exceptions.ts

@@ -0,0 +1,154 @@
+import APIConstants from "./constants/api_constants";
+
+const scorm12_errors = APIConstants.scorm12.error_descriptions;
+const aicc_errors = APIConstants.aicc.error_descriptions;
+const scorm2004_errors = APIConstants.scorm2004.error_descriptions;
+
+type APIError = {
+  errorCode: number;
+  errorMessage: string;
+  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
+ */
+export class ValidationError
+  extends BaseScormValidationError
+  implements APIError
+{
+  /**
+   * Constructor to take in an error message and code
+   * @param {number} errorCode
+   * @param {string} errorMessage
+   * @param {string} detailedMessage
+   */
+  constructor(
+    errorCode: number,
+    errorMessage: string,
+    detailedMessage?: string,
+  ) {
+    super(errorCode);
+    this.setMessage(errorMessage);
+    this._errorMessage = errorMessage;
+    if (detailedMessage) {
+      this._detailedMessage = detailedMessage;
+    }
+  }
+
+  private readonly _errorMessage: string;
+  private readonly _detailedMessage: string = "";
+
+  /**
+   * Getter for _errorMessage
+   * @return {string}
+   */
+  get errorMessage(): string {
+    return this._errorMessage;
+  }
+
+  /**
+   * Getter for _detailedMessage
+   * @return {string}
+   */
+  get detailedMessage(): string {
+    return this._detailedMessage;
+  }
+}
+
+/**
+ * SCORM 1.2 Validation Error
+ */
+export class Scorm12ValidationError extends ValidationError {
+  /**
+   * Constructor to take in an error code
+   * @param {number} errorCode
+   */
+  constructor(errorCode: number) {
+    if ({}.hasOwnProperty.call(scorm12_errors, String(errorCode))) {
+      super(
+        errorCode,
+        scorm12_errors[String(errorCode)].basicMessage,
+        scorm12_errors[String(errorCode)].detailMessage,
+      );
+    } else {
+      super(
+        101,
+        scorm12_errors["101"].basicMessage,
+        scorm12_errors["101"].detailMessage,
+      );
+    }
+  }
+}
+
+/**
+ * AICC Validation Error
+ */
+export class AICCValidationError extends ValidationError {
+  /**
+   * Constructor to take in an error code
+   * @param {number} errorCode
+   */
+  constructor(errorCode: number) {
+    if ({}.hasOwnProperty.call(aicc_errors, String(errorCode))) {
+      super(
+        errorCode,
+        aicc_errors[String(errorCode)].basicMessage,
+        aicc_errors[String(errorCode)].detailMessage,
+      );
+    } else {
+      super(
+        101,
+        aicc_errors["101"].basicMessage,
+        aicc_errors["101"].detailMessage,
+      );
+    }
+  }
+}
+
+/**
+ * SCORM 2004 Validation Error
+ */
+export class Scorm2004ValidationError extends ValidationError {
+  /**
+   * Constructor to take in an error code
+   * @param {number} errorCode
+   */
+  constructor(errorCode: number) {
+    if ({}.hasOwnProperty.call(scorm2004_errors, String(errorCode))) {
+      super(
+        errorCode,
+        scorm2004_errors[String(errorCode)].basicMessage,
+        scorm2004_errors[String(errorCode)].detailMessage,
+      );
+    } else {
+      super(
+        101,
+        scorm2004_errors["101"].basicMessage,
+        scorm2004_errors["101"].detailMessage,
+      );
+    }
+  }
+}

package/src/exports/aicc.js

@@ -1,3 +1,3 @@
-import AICC from '../AICC';
+import AICC from "../AICC.ts";
 
 window.AICC = AICC;

package/src/exports/scorm-again.js

@@ -1,6 +1,6 @@
-import Scorm2004API from '../Scorm2004API';
-import Scorm12API from '../Scorm12API';
-import AICC from '../AICC';
+import Scorm2004API from "../Scorm2004API.ts";
+import Scorm12API from "../Scorm12API.ts";
+import AICC from "../AICC.ts";
 
 window.Scorm12API = Scorm12API;
 window.Scorm2004API = Scorm2004API;

package/src/exports/scorm12.js

@@ -1,3 +1,3 @@
-import Scorm12API from '../Scorm12API';
+import Scorm12API from "../Scorm12API.ts";
 
 window.Scorm12API = Scorm12API;

package/src/exports/scorm2004.js

@@ -1,3 +1,3 @@
-import Scorm2004API from '../Scorm2004API';
+import Scorm2004API from "../Scorm2004API.ts";
 
 window.Scorm2004API = Scorm2004API;

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))();
+    }
+  }
+}

package/src/interfaces/IBaseAPI.ts

@@ -0,0 +1,35 @@
+import { RefObject, ResultObject } from "../types/api_types";
+import { BaseCMI } from "../cmi/common/base_cmi";
+
+export interface IBaseAPI {
+  cmi: BaseCMI;
+  startingData?: RefObject;
+
+  initialize(
+    callbackName: string,
+    initializeMessage?: string,
+    terminationMessage?: string,
+  ): string;
+  lmsInitialize(): string;
+  lmsFinish(): string;
+  lmsGetValue(CMIElement: string): string;
+  lmsSetValue(CMIElement: string, value: any): string;
+  lmsCommit(): string;
+  lmsGetLastError(): string;
+  lmsGetErrorString(CMIErrorCode: string | number): string;
+  lmsGetDiagnostic(CMIErrorCode: string | number): string;
+  storeData(_calculateTotalTime: boolean): Promise<ResultObject>;
+  renderCommitCMI(_terminateCommit: boolean): RefObject | Array<any>;
+  getLmsErrorMessageDetails(
+    _errorNumber: string | number,
+    _detail?: boolean,
+  ): string;
+  getCMIValue(_CMIElement: string): string;
+  setCMIValue(_CMIElement: string, _value: any): string;
+  validateCorrectResponse(_CMIElement: string, _value: any): void;
+  getChildElement(
+    _CMIElement: string,
+    _value: any,
+    _foundFirstIndex: boolean,
+  ): BaseCMI | null;
+}

package/src/types/api_types.ts

@@ -0,0 +1,32 @@
+export type Settings = {
+  autocommit?: boolean;
+  autocommitSeconds?: number;
+  asyncCommit?: boolean;
+  sendFullCommit?: boolean;
+  lmsCommitUrl?: boolean | string;
+  dataCommitFormat?: string;
+  commitRequestDataType?: string;
+  autoProgress?: boolean;
+  logLevel?: number;
+  selfReportSessionTime?: boolean;
+  alwaysSendTotalTime?: boolean;
+  strict_errors?: boolean;
+  xhrHeaders?: RefObject;
+  xhrWithCredentials?: boolean;
+  responseHandler?: (response: Response) => Promise<ResultObject>;
+  requestHandler?: (commitObject: any) => any;
+  onLogMessage?: (messageLevel: number, logMessage: string) => void;
+  scoItemIds?: string[];
+  scoItemIdValidator?: false | ((scoItemId: string) => boolean);
+  mastery_override?: boolean;
+};
+
+export type RefObject = {
+  [key: string]: any;
+};
+
+export type ResultObject = {
+  result: string;
+  errorCode: number;
+  navRequest?: string;
+};

package/src/utilities/debounce.ts

@@ -0,0 +1,31 @@
+/**
+ * Debounce function to delay the execution of a given function.
+ *
+ * @param func - The function to debounce.
+ * @param wait - The number of milliseconds to delay.
+ * @param immediate - If `true`, the function will be triggered on the leading edge instead of the trailing.
+ * @returns A debounced version of the provided function.
+ */
+export function debounce<T extends (...args: any[]) => void>(
+  func: T,
+  wait: number,
+  immediate = false,
+): (...args: Parameters<T>) => void {
+  let timeout: ReturnType<typeof setTimeout> | null;
+
+  return function (this: any, ...args: Parameters<T>) {
+    const context = this;
+
+    const later = () => {
+      timeout = null;
+      if (!immediate) func.apply(context, args);
+    };
+
+    const callNow = immediate && !timeout;
+
+    if (timeout) clearTimeout(timeout);
+    timeout = setTimeout(later, wait);
+
+    if (callNow) func.apply(context, args);
+  };
+}

package/src/utilities.ts

@@ -0,0 +1,338 @@
+export const SECONDS_PER_SECOND = 1.0;
+export const SECONDS_PER_MINUTE = 60;
+export const SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE;
+export const SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR;
+
+type Designation = {
+  [key: string]: number;
+};
+
+type StringKeyMap = {
+  [key: string]: any;
+};
+
+const designations: Designation = {
+  D: SECONDS_PER_DAY,
+  H: SECONDS_PER_HOUR,
+  M: SECONDS_PER_MINUTE,
+  S: SECONDS_PER_SECOND,
+};
+
+/**
+ * Converts a Number to a String of HH:MM:SS
+ *
+ * @param {number} totalSeconds
+ * @return {string}
+ */
+export function getSecondsAsHHMMSS(totalSeconds: number | null): string {
+  // SCORM spec does not deal with negative durations, give zero back
+  if (!totalSeconds || totalSeconds <= 0) {
+    return "00:00:00";
+  }
+
+  const hours = Math.floor(totalSeconds / SECONDS_PER_HOUR);
+  const dateObj = new Date(totalSeconds * 1000);
+  const minutes = dateObj.getUTCMinutes();
+  // make sure we add any possible decimal value
+  const seconds = dateObj.getSeconds();
+  const ms = totalSeconds % 1.0;
+  let msStr = "";
+
+  if (countDecimals(ms) > 0) {
+    if (countDecimals(ms) > 2) {
+      msStr = ms.toFixed(2);
+    } else {
+      msStr = String(ms);
+    }
+
+    msStr = "." + msStr.split(".")[1];
+  }
+
+  return (
+    (hours + ":" + minutes + ":" + seconds).replace(/\b\d\b/g, "0$&") + msStr
+  );
+}
+
+/**
+ * Calculate the number of seconds from ISO 8601 Duration
+ *
+ * @param {number} seconds
+ * @return {string}
+ */
+export function getSecondsAsISODuration(seconds: number | null): string {
+  // SCORM spec does not deal with negative durations, give zero back
+  if (!seconds || seconds <= 0) {
+    return "PT0S";
+  }
+
+  let duration = "P";
+  let remainder = seconds;
+  for (const designationsKey in designations) {
+    const current_seconds = designations[designationsKey];
+    let value = Math.floor(remainder / current_seconds);
+    remainder = remainder % current_seconds;
+
+    if (countDecimals(remainder) > 2) {
+      remainder = Number(Number(remainder).toFixed(2));
+    }
+
+    // If we have anything left in the remainder, and we're currently adding
+    // seconds to the duration, go ahead and add the decimal to the seconds
+    if (designationsKey === "S" && remainder > 0) {
+      value += remainder;
+    }
+
+    if (value) {
+      if (
+        (duration.indexOf("D") > 0 ||
+          designationsKey === "H" ||
+          designationsKey === "M" ||
+          designationsKey === "S") &&
+        duration.indexOf("T") === -1
+      ) {
+        duration += "T";
+      }
+
+      duration += `${value}${designationsKey}`;
+    }
+  }
+  return duration;
+}
+
+/**
+ * Calculate the number of seconds from HH:MM:SS.DDDDDD
+ *
+ * @param {string} timeString
+ * @param {RegExp} timeRegex
+ * @return {number}
+ */
+export function getTimeAsSeconds(
+  timeString: string | number | boolean | null,
+  timeRegex: RegExp | string,
+): number {
+  if (typeof timeString === "number" || typeof timeString === "boolean") {
+    timeString = String(timeString);
+  }
+  if (typeof timeRegex === "string") {
+    timeRegex = new RegExp(timeRegex);
+  }
+  if (!timeString || !timeString.match(timeRegex)) {
+    return 0;
+  }
+
+  const parts = timeString.split(":");
+  const hours = Number(parts[0]);
+  const minutes = Number(parts[1]);
+  const seconds = Number(parts[2]);
+  return hours * 3600 + minutes * 60 + seconds;
+}
+
+/**
+ * Calculate the number of seconds from ISO 8601 Duration
+ *
+ * @param {string} duration
+ * @param {RegExp} durationRegex
+ * @return {number}
+ */
+export function getDurationAsSeconds(
+  duration: string | null,
+  durationRegex: RegExp | string,
+): number {
+  if (typeof durationRegex === "string") {
+    durationRegex = new RegExp(durationRegex);
+  }
+
+  if (!duration || !duration.match(durationRegex)) {
+    return 0;
+  }
+
+  const [, years, _, , days, hours, minutes, seconds] =
+    new RegExp(durationRegex).exec(duration) || [];
+  let result = 0.0;
+  result += Number(seconds) || 0.0;
+  result += Number(minutes) * 60.0 || 0.0;
+  result += Number(hours) * 3600.0 || 0.0;
+  result += Number(days) * (60 * 60 * 24.0) || 0.0;
+  result += Number(years) * (60 * 60 * 24 * 365.0) || 0.0;
+  return result;
+}
+
+/**
+ * Adds together two ISO8601 Duration strings
+ *
+ * @param {string} first
+ * @param {string} second
+ * @param {RegExp|string} durationRegex
+ * @return {string}
+ */
+export function addTwoDurations(
+  first: string,
+  second: string,
+  durationRegex: RegExp | string,
+): string {
+  const regex: RegExp =
+    typeof durationRegex === "string"
+      ? new RegExp(durationRegex)
+      : durationRegex;
+  return getSecondsAsISODuration(
+    getDurationAsSeconds(first, regex) + getDurationAsSeconds(second, regex),
+  );
+}
+
+/**
+ * Add together two HH:MM:SS.DD strings
+ *
+ * @param {string} first
+ * @param {string} second
+ * @param {RegExp} timeRegex
+ * @return {string}
+ */
+export function addHHMMSSTimeStrings(
+  first: string,
+  second: string,
+  timeRegex: RegExp | string,
+): string {
+  if (typeof timeRegex === "string") {
+    timeRegex = new RegExp(timeRegex);
+  }
+  return getSecondsAsHHMMSS(
+    getTimeAsSeconds(first, timeRegex) + getTimeAsSeconds(second, timeRegex),
+  );
+}
+
+/**
+ * Flatten a JSON object down to string paths for each values
+ * @param {object} data
+ * @return {object}
+ */
+export function flatten(data: StringKeyMap): object {
+  const result: StringKeyMap = {};
+
+  /**
+   * Recurse through the object
+   * @param {*} cur
+   * @param {*} prop
+   */
+  function recurse(cur: any, prop: any) {
+    if (Object(cur) !== cur) {
+      result[prop] = cur;
+    } else if (Array.isArray(cur)) {
+      for (let i = 0, l = cur.length; i < l; i++) {
+        recurse(cur[i], prop + "[" + i + "]");
+        if (l === 0) result[prop] = [];
+      }
+    } else {
+      let isEmpty = true;
+
+      for (const p in cur) {
+        if ({}.hasOwnProperty.call(cur, p)) {
+          isEmpty = false;
+          recurse(cur[p], prop ? prop + "." + p : p);
+        }
+      }
+
+      if (isEmpty && prop) result[prop] = {};
+    }
+  }
+
+  recurse(data, "");
+  return result;
+}
+
+/**
+ * Un-flatten a flat JSON object
+ * @param {object} data
+ * @return {object}
+ */
+export function unflatten(data: StringKeyMap): object {
+  "use strict";
+
+  if (Object(data) !== data || Array.isArray(data)) return data;
+  const regex = /\.?([^.[\]]+)|\[(\d+)]/g;
+  const result: StringKeyMap = {};
+
+  for (const p in data) {
+    if ({}.hasOwnProperty.call(data, p)) {
+      let cur = result;
+      let prop = "";
+      let m = regex.exec(p);
+
+      while (m) {
+        cur = cur[prop] || (cur[prop] = m[2] ? [] : {});
+        prop = m[2] || m[1];
+        m = regex.exec(p);
+      }
+
+      cur[prop] = data[p];
+    }
+  }
+
+  return result[""] || result;
+}
+
+/**
+ * Counts the number of decimal places
+ * @param {number} num
+ * @return {number}
+ */
+export function countDecimals(num: number): number {
+  if (Math.floor(num) === num || String(num).indexOf(".") < 0) return 0;
+  const parts = num.toString().split(".")[1];
+  return parts.length || 0;
+}
+
+/**
+ * Formats the SCORM messages for easy reading
+ *
+ * @param {string} functionName
+ * @param {string} message
+ * @param {string} CMIElement
+ * @return {string}
+ */
+export function formatMessage(
+  functionName: string,
+  message: string,
+  CMIElement?: string,
+): string {
+  const baseLength = 20;
+  let messageString = "";
+
+  messageString += functionName;
+
+  let fillChars = baseLength - messageString.length;
+
+  for (let i = 0; i < fillChars; i++) {
+    messageString += " ";
+  }
+
+  messageString += ": ";
+
+  if (CMIElement) {
+    const CMIElementBaseLength = 70;
+
+    messageString += CMIElement;
+
+    fillChars = CMIElementBaseLength - messageString.length;
+
+    for (let j = 0; j < fillChars; j++) {
+      messageString += " ";
+    }
+  }
+
+  if (message) {
+    messageString += message;
+  }
+
+  return messageString;
+}
+
+/**
+ * Checks to see if {str} contains {tester}
+ *
+ * @param {string} str String to check against
+ * @param {string} tester String to check for
+ * @return {boolean}
+ */
+export function stringMatches(str: string, tester: string): boolean {
+  return str?.match(tester) !== null;
+}

package/tea.yaml

@@ -0,0 +1,6 @@
+# https://tea.xyz/what-is-this-file
+---
+version: 1.0.0
+codeOwners:
+  - '0x1bfc0b2fc65c3eEE1AfFB43E07fbD8F00E18B93E'
+quorum: 1