@longsightgroup/qti3-core 0.9.1 → 0.9.3

package/src/processing-mapping.ts

@@ -0,0 +1,153 @@
+import type { QtiDocument, QtiResponseDeclaration, QtiValue } from "./types.js";
+import { qtiScalarToString, qtiValueToStringList } from "./value-format.js";
+import { isRecordValue, numericValue, valuesEqual } from "./processing-values.js";
+
+export function lookupOutcomeValue(
+  document: QtiDocument,
+  identifier: string,
+  value: QtiValue,
+): QtiValue {
+  const declaration = document.item.outcomeDeclarations.find(
+    (outcome) => outcome.identifier === identifier,
+  );
+  const lookupTable = declaration?.lookupTable;
+  if (!lookupTable) return null;
+  if (value === null) return lookupTable.defaultValue;
+  const numeric = numericValue(value);
+  if (lookupTable.type === "match") {
+    return (
+      lookupTable.entries.find((entry) => entry.sourceValue === numeric)?.targetValue ??
+      lookupTable.defaultValue
+    );
+  }
+  const entry = [...lookupTable.entries]
+    .toSorted((left, right) => left.sourceValue - right.sourceValue)
+    .find(
+      (candidate) =>
+        numeric < candidate.sourceValue ||
+        (candidate.includeBoundary !== false && numeric === candidate.sourceValue),
+    );
+  return entry?.targetValue ?? lookupTable.defaultValue;
+}
+
+export function mapOrMatchResponse(
+  declaration: QtiResponseDeclaration,
+  response: QtiValue,
+  correctResponse: QtiValue,
+): number {
+  if (declaration.areaMapping) return scoreAreaMapping(response, declaration.areaMapping);
+  if (declaration.mapping) return scoreMapping(response, declaration.mapping);
+  return valuesEqual(response, correctResponse, declaration.cardinality === "ordered") ? 1 : 0;
+}
+
+export function scoreAreaMapping(
+  response: QtiValue,
+  areaMapping: NonNullable<QtiResponseDeclaration["areaMapping"]>,
+): number {
+  const points = Array.isArray(response)
+    ? response.map(qtiScalarToString)
+    : response === null
+      ? []
+      : qtiValueToStringList(response);
+  let score = 0;
+  for (const point of points) {
+    const parsed = parsePoint(point);
+    if (!parsed) {
+      score += areaMapping.defaultValue;
+      continue;
+    }
+    const entry = areaMapping.entries.find((candidate) => pointInsideArea(parsed, candidate));
+    score += entry?.mappedValue ?? areaMapping.defaultValue;
+  }
+  return clampMappedScore(score, areaMapping.attributes);
+}
+
+export function parsePoint(value: string): { x: number; y: number } | undefined {
+  const [x, y] = value
+    .trim()
+    .split(/[,\s]+/)
+    .map((part) => Number(part));
+  if (x === undefined || y === undefined || !Number.isFinite(x) || !Number.isFinite(y)) {
+    return undefined;
+  }
+  return { x, y };
+}
+
+export function pointInsideArea(
+  point: { x: number; y: number },
+  entry: NonNullable<QtiResponseDeclaration["areaMapping"]>["entries"][number],
+): boolean {
+  if (entry.shape === "circle") {
+    const [cx, cy, radius] = entry.coords;
+    if (cx === undefined || cy === undefined || radius === undefined) return false;
+    return Math.hypot(point.x - cx, point.y - cy) <= radius;
+  }
+
+  if (entry.shape === "rect") {
+    const [left, top, right, bottom] = entry.coords;
+    if (left === undefined || top === undefined || right === undefined || bottom === undefined) {
+      return false;
+    }
+    return point.x >= left && point.x <= right && point.y >= top && point.y <= bottom;
+  }
+
+  if (entry.shape === "poly") {
+    return pointInsidePolygon(point, entry.coords);
+  }
+
+  return false;
+}
+
+function pointInsidePolygon(point: { x: number; y: number }, coords: number[]): boolean {
+  if (coords.length < 6 || coords.length % 2 !== 0) return false;
+  let inside = false;
+  for (let index = 0, previous = coords.length - 2; index < coords.length; index += 2) {
+    const xi = coords[index]!;
+    const yi = coords[index + 1]!;
+    const xj = coords[previous]!;
+    const yj = coords[previous + 1]!;
+    const intersects =
+      yi > point.y !== yj > point.y && point.x < ((xj - xi) * (point.y - yi)) / (yj - yi) + xi;
+    if (intersects) inside = !inside;
+    previous = index;
+  }
+  return inside;
+}
+
+function scoreMapping(
+  response: QtiValue,
+  mapping: NonNullable<QtiResponseDeclaration["mapping"]>,
+): number {
+  const values = Object.fromEntries(
+    mapping.entries
+      .filter((entry) => entry.mapKey !== undefined)
+      .map((entry) => [entry.mapKey!, entry.mappedValue]),
+  );
+  if (Array.isArray(response)) {
+    const score = response.reduce<number>(
+      (sum, value) => sum + (values[String(value)] ?? mapping.defaultValue),
+      0,
+    );
+    return clampMappedScore(score, mapping.attributes);
+  }
+  const score =
+    response === null || isRecordValue(response)
+      ? 0
+      : (values[String(response)] ?? mapping.defaultValue);
+  return clampMappedScore(score, mapping.attributes);
+}
+
+function clampMappedScore(score: number, attributes: Record<string, string>): number {
+  const lower = numericBound(attributes["lower-bound"]);
+  const upper = numericBound(attributes["upper-bound"]);
+  let clamped = score;
+  if (lower !== undefined) clamped = Math.max(clamped, lower);
+  if (upper !== undefined) clamped = Math.min(clamped, upper);
+  return clamped;
+}
+
+function numericBound(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const numberValue = Number(value);
+  return Number.isFinite(numberValue) ? numberValue : undefined;
+}

package/src/processing-operators.ts

@@ -0,0 +1,184 @@
+import type { QtiValue } from "./types.js";
+
+export const MATH_OPERATOR_NAMES = [
+  "abs",
+  "acos",
+  "acot",
+  "acsc",
+  "asec",
+  "asin",
+  "atan",
+  "atan2",
+  "ceil",
+  "cos",
+  "cosh",
+  "cot",
+  "coth",
+  "csc",
+  "csch",
+  "exp",
+  "floor",
+  "ln",
+  "log",
+  "sec",
+  "sech",
+  "signum",
+  "sin",
+  "sinh",
+  "tan",
+  "tanh",
+  "toDegrees",
+  "toRadians",
+] as const;
+
+export const STATS_OPERATOR_NAMES = [
+  "mean",
+  "sampleVariance",
+  "sampleSD",
+  "popVariance",
+  "popSD",
+] as const;
+
+export function roundToDecimalPlaces(value: number, figures: number): number {
+  const factor = 10 ** figures;
+  return Math.round(value * factor) / factor;
+}
+
+export function roundToSignificantFigures(value: number, figures: number): number {
+  if (value === 0 || figures <= 0) return 0;
+  const factor = 10 ** (figures - 1 - Math.floor(Math.log10(Math.abs(value))));
+  return Math.round(value * factor) / factor;
+}
+
+export function roundWithMode(value: number, roundingMode: string, figures: number): number | null {
+  if (!Number.isFinite(value)) return null;
+  if (roundingMode === "decimalPlaces") return roundToDecimalPlaces(value, figures);
+  if (roundingMode === "significantFigures") return roundToSignificantFigures(value, figures);
+  return null;
+}
+
+export function generalizedGcd(values: number[]): number {
+  let result = 0;
+  for (const value of values) {
+    result = gcd(result, Math.abs(value));
+  }
+  return result;
+}
+
+export function generalizedLcm(values: number[]): number {
+  if (values.some((value) => value === 0)) return 0;
+  return values.reduce((result, value) => lcm(result, Math.abs(value)), 1);
+}
+
+function gcd(left: number, right: number): number {
+  let a = Math.abs(left);
+  let b = Math.abs(right);
+  while (b !== 0) {
+    const next = a % b;
+    a = b;
+    b = next;
+  }
+  return a;
+}
+
+function lcm(left: number, right: number): number {
+  return Math.abs(left * right) / gcd(left, right);
+}
+
+export function mathOperatorValue(name: string, values: number[]): QtiValue {
+  const [first, second] = values;
+  if (first === undefined) return null;
+  switch (name) {
+    case "abs":
+      return finiteOrNull(Math.abs(first));
+    case "acos":
+      return Math.abs(first) > 1 ? null : finiteOrNull(Math.acos(first));
+    case "acot":
+      return finiteOrNull(Math.PI / 2 - Math.atan(1 / first));
+    case "acsc":
+      return Math.abs(first) < 1 ? null : finiteOrNull(Math.PI / 2 - Math.asin(1 / first));
+    case "asec":
+      return Math.abs(first) < 1 ? null : finiteOrNull(Math.PI / 2 - Math.acos(1 / first));
+    case "asin":
+      return Math.abs(first) > 1 ? null : finiteOrNull(Math.asin(first));
+    case "atan":
+      return finiteOrNull(Math.atan(first));
+    case "atan2":
+      return second === undefined ? null : finiteOrNull(Math.atan2(first, second));
+    case "ceil":
+      return finiteOrNull(Math.ceil(first));
+    case "cos":
+      return finiteOrNull(Math.cos(first));
+    case "cosh":
+      return finiteOrNull(Math.cosh(first));
+    case "cot":
+      return finiteOrNull(1 / Math.tan(first));
+    case "coth":
+      return finiteOrNull(1 / Math.tanh(first));
+    case "csc":
+      return finiteOrNull(1 / Math.sin(first));
+    case "csch":
+      return finiteOrNull(1 / Math.sinh(first));
+    case "exp":
+      return finiteOrNull(Math.exp(first));
+    case "floor":
+      return finiteOrNull(Math.floor(first));
+    case "ln":
+      return first < 0 ? null : finiteOrNull(Math.log(first));
+    case "log":
+      return first < 0 ? null : finiteOrNull(Math.log10(first));
+    case "sec":
+      return finiteOrNull(1 / Math.cos(first));
+    case "sech":
+      return finiteOrNull(1 / Math.cosh(first));
+    case "signum":
+      return finiteOrNull(Math.sign(first));
+    case "sin":
+      return finiteOrNull(Math.sin(first));
+    case "sinh":
+      return finiteOrNull(Math.sinh(first));
+    case "tan":
+      return finiteOrNull(Math.tan(first));
+    case "tanh":
+      return finiteOrNull(Math.tanh(first));
+    case "toDegrees":
+      return finiteOrNull((first * 180) / Math.PI);
+    case "toRadians":
+      return finiteOrNull((first * Math.PI) / 180);
+    default:
+      return null;
+  }
+}
+
+export function statsOperatorValue(name: string, values: number[]): QtiValue {
+  if (values.length === 0) return 0;
+  const meanValue = mean(values);
+  const squareDiffs = values.map((value) => (value - meanValue) ** 2);
+  switch (name) {
+    case "mean":
+      return meanValue;
+    case "sampleVariance":
+      return meanWithDivisor(squareDiffs, values.length > 1 ? values.length - 1 : 1);
+    case "sampleSD":
+      return Math.sqrt(meanWithDivisor(squareDiffs, values.length > 1 ? values.length - 1 : 1));
+    case "popVariance":
+      return mean(squareDiffs);
+    case "popSD":
+      return Math.sqrt(mean(squareDiffs));
+    default:
+      return null;
+  }
+}
+
+function mean(values: number[]): number {
+  return meanWithDivisor(values, values.length);
+}
+
+function meanWithDivisor(values: number[], divisor: number): number {
+  if (values.length === 0) return 0;
+  return values.reduce((sum, value) => sum + value, 0) / divisor;
+}
+
+function finiteOrNull(value: number): QtiValue {
+  return Number.isFinite(value) ? value : null;
+}

package/src/processing-random.ts

@@ -0,0 +1,16 @@
+export function seededRandom(seed: string | number): () => number {
+  let state = typeof seed === "number" ? seed >>> 0 : hashSeed(seed);
+  return () => {
+    state = (1664525 * state + 1013904223) >>> 0;
+    return state / 0x100000000;
+  };
+}
+
+function hashSeed(seed: string): number {
+  let hash = 2166136261;
+  for (let index = 0; index < seed.length; index += 1) {
+    hash ^= seed.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}

package/src/processing-state.ts

@@ -0,0 +1,69 @@
+import type {
+  QtiAttemptStateV1,
+  QtiAttemptStatus,
+  QtiDiagnostic,
+  QtiPortableCustomStateValue,
+  QtiValue,
+} from "./types.js";
+import { ATTEMPT_STATE_SCHEMA } from "./attempt-state-constants.js";
+import { isRecordValue } from "./processing-values.js";
+
+export function serialize(
+  itemIdentifier: string,
+  status: QtiAttemptStatus,
+  responses: Record<string, QtiValue>,
+  outcomes: Record<string, QtiValue>,
+  templateValues: Record<string, QtiValue>,
+  interactionStates: Record<string, QtiPortableCustomStateValue>,
+  validationMessages: QtiDiagnostic[],
+): QtiAttemptStateV1 {
+  return {
+    schema: ATTEMPT_STATE_SCHEMA,
+    itemIdentifier,
+    status,
+    responses: cloneValueRecord(responses),
+    outcomes: cloneValueRecord(outcomes),
+    templateValues: cloneValueRecord(templateValues),
+    interactionStates: clonePortableCustomStateRecord(interactionStates),
+    validationMessages: cloneDiagnostics(validationMessages),
+  };
+}
+
+export function cloneValueRecord(record: Record<string, QtiValue>): Record<string, QtiValue> {
+  return Object.fromEntries(Object.entries(record).map(([key, value]) => [key, cloneValue(value)]));
+}
+
+export function clonePortableCustomStateRecord(
+  record: Record<string, QtiPortableCustomStateValue>,
+): Record<string, QtiPortableCustomStateValue> {
+  return Object.fromEntries(
+    Object.entries(record).map(([key, value]) => [key, clonePortableCustomState(value)]),
+  );
+}
+
+export function cloneValue(value: QtiValue): QtiValue {
+  if (Array.isArray(value)) return [...value];
+  if (isRecordValue(value)) return cloneValueRecord(value);
+  return value;
+}
+
+export function clonePortableCustomState(
+  value: QtiPortableCustomStateValue,
+): QtiPortableCustomStateValue {
+  if (Array.isArray(value)) return value.map(clonePortableCustomState);
+  if (isPortableCustomStateObject(value)) return clonePortableCustomStateRecord(value);
+  return value;
+}
+
+function isPortableCustomStateObject(
+  value: QtiPortableCustomStateValue,
+): value is { [key: string]: QtiPortableCustomStateValue } {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function cloneDiagnostics(diagnostics: QtiDiagnostic[]): QtiDiagnostic[] {
+  return diagnostics.map((diagnostic) => ({
+    ...diagnostic,
+    source: diagnostic.source ? { ...diagnostic.source } : undefined,
+  }));
+}

package/src/processing-templates.ts

@@ -0,0 +1,12 @@
+export type ResponseProcessingTemplateKind = "matchCorrect" | "mapResponse" | "mapResponsePoint";
+
+export function responseProcessingTemplateKind(
+  template: string,
+): ResponseProcessingTemplateKind | undefined {
+  const path = template.split(/[?#]/, 1)[0] ?? "";
+  const name = path.slice(path.lastIndexOf("/") + 1).replace(/\.xml$/i, "");
+  if (name === "match_correct") return "matchCorrect";
+  if (name === "map_response") return "mapResponse";
+  if (name === "map_response_point") return "mapResponsePoint";
+  return undefined;
+}

package/src/processing-values.ts

@@ -0,0 +1,162 @@
+import type { QtiRecordValue, QtiResponseDeclaration, QtiScalarValue, QtiValue } from "./types.js";
+import { qtiValueToString } from "./value-format.js";
+
+export function isNullResponse(response: QtiValue): boolean {
+  return response === null || response === "" || (Array.isArray(response) && response.length === 0);
+}
+
+export function valuesEqual(actual: QtiValue, expected: QtiValue, ordered = false): boolean {
+  if (isRecordValue(actual) || isRecordValue(expected)) {
+    if (!isRecordValue(actual) || !isRecordValue(expected)) return false;
+    const actualKeys = Object.keys(actual).toSorted();
+    const expectedKeys = Object.keys(expected).toSorted();
+    return (
+      valuesEqual(actualKeys, expectedKeys, true) &&
+      actualKeys.every((key) => valuesEqual(actual[key] ?? null, expected[key] ?? null, ordered))
+    );
+  }
+  if (Array.isArray(actual) || Array.isArray(expected)) {
+    const actualValues = valueContainer(actual);
+    const expectedValues = Array.isArray(expected) ? expected : expected === null ? [] : [expected];
+    if (actualValues.length !== expectedValues.length) return false;
+    if (ordered)
+      return actualValues.every((value, index) => scalarValuesEqual(value, expectedValues[index]!));
+    const sortedExpected = [...expectedValues].toSorted(compareScalarValues);
+    return [...actualValues]
+      .toSorted(compareScalarValues)
+      .every((value, index) => scalarValuesEqual(value, sortedExpected[index]!));
+  }
+  return scalarValuesEqual(actual, expected);
+}
+
+export function qtiMatchValues(
+  actual: QtiValue,
+  expected: QtiValue,
+  ordered = false,
+): boolean | null {
+  if (actual === null || expected === null) return null;
+  return valuesEqual(actual, expected, ordered);
+}
+
+function scalarValuesEqual(actual: QtiValue, expected: QtiValue): boolean {
+  if (typeof actual === "boolean" && typeof expected === "string") {
+    return String(actual) === expected;
+  }
+  if (typeof actual === "string" && typeof expected === "boolean") {
+    return actual === String(expected);
+  }
+  if (typeof actual === "number" && typeof expected === "string") {
+    return String(actual) === expected;
+  }
+  if (typeof actual === "string" && typeof expected === "number") {
+    return actual === String(expected);
+  }
+  return actual === expected;
+}
+
+export function normalizeValueForCardinality(
+  value: QtiValue,
+  cardinality: QtiResponseDeclaration["cardinality"],
+): QtiValue {
+  if (
+    (cardinality === "multiple" || cardinality === "ordered") &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !isRecordValue(value)
+  ) {
+    return [value];
+  }
+  return value;
+}
+
+export function valueContainer(value: QtiValue): QtiScalarValue[] {
+  if (value === null) return [];
+  if (isRecordValue(value)) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+export function isRecordValue(value: QtiValue): value is QtiRecordValue {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function containsValues(collection: QtiScalarValue[], values: QtiScalarValue[]): boolean {
+  const remaining = [...collection];
+  for (const value of values) {
+    const index = remaining.findIndex((candidate) => valuesEqual(candidate, value));
+    if (index === -1) return false;
+    remaining.splice(index, 1);
+  }
+  return true;
+}
+
+function compareScalarValues(left: QtiScalarValue, right: QtiScalarValue): number {
+  return String(left).localeCompare(String(right));
+}
+
+export function numericValue(value: QtiValue): number {
+  if (typeof value === "number") return value;
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "string") return Number(value);
+  return 0;
+}
+
+export function numericValueOrNull(value: QtiValue): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+export function durationSeconds(value: QtiValue): number | null {
+  if (value === null || Array.isArray(value) || isRecordValue(value)) return null;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  const raw = String(value).trim();
+  if (raw.length === 0) return null;
+  const numeric = Number(raw);
+  if (Number.isFinite(numeric)) return numeric;
+  const match =
+    /^P(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/i.exec(
+      raw,
+    );
+  if (!match) return null;
+  const [, days, hours, minutes, seconds] = match;
+  if (!days && !hours && !minutes && !seconds) return null;
+  const total =
+    Number(days ?? 0) * 86_400 +
+    Number(hours ?? 0) * 3_600 +
+    Number(minutes ?? 0) * 60 +
+    Number(seconds ?? 0);
+  return Number.isFinite(total) ? total : null;
+}
+
+export function booleanValue(value: QtiValue): boolean {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") return value.length > 0 && value !== "false";
+  if (Array.isArray(value)) return value.length > 0;
+  return false;
+}
+
+export function booleanValueOrNull(value: QtiValue): boolean | null {
+  if (value === null) return null;
+  return booleanValue(value);
+}
+
+export function stringMatch(
+  left: QtiValue,
+  right: QtiValue,
+  caseSensitive: boolean,
+  substring: boolean,
+): boolean | null {
+  if (left === null || right === null) return null;
+  let actual = qtiValueToString(left);
+  let expected = qtiValueToString(right);
+  if (!caseSensitive) {
+    actual = actual.toLocaleLowerCase();
+    expected = expected.toLocaleLowerCase();
+  }
+  return substring ? actual.includes(expected) : actual === expected;
+}

package/src/processing-variables.ts

@@ -0,0 +1,83 @@
+import type {
+  QtiDocument,
+  QtiOutcomeDeclaration,
+  QtiProcessingExpression,
+  QtiResponseDeclaration,
+  QtiTemplateDeclaration,
+  QtiValue,
+} from "./types.js";
+
+export function getResponseDeclaration(
+  document: QtiDocument,
+  identifier: string,
+): QtiResponseDeclaration | undefined {
+  return document.item.responseDeclarations.find(
+    (declaration) => declaration.identifier === identifier,
+  );
+}
+
+export function resolveVariableValue(
+  document: QtiDocument,
+  identifier: string,
+  responses: Record<string, QtiValue>,
+  outcomes: Record<string, QtiValue>,
+  templateValues: Record<string, QtiValue>,
+): QtiValue {
+  return (
+    resolveOptionalVariableValue(document, identifier, responses, outcomes, templateValues) ?? null
+  );
+}
+
+export function resolveOptionalVariableValue(
+  document: QtiDocument,
+  identifier: string,
+  responses: Record<string, QtiValue>,
+  outcomes: Record<string, QtiValue>,
+  templateValues: Record<string, QtiValue>,
+): QtiValue | undefined {
+  const declaration = resolveVariableDeclaration(document, identifier);
+  if (!declaration) return undefined;
+  if (declaration.kind === "response") return responses[identifier] ?? null;
+  if (declaration.kind === "outcome") return outcomes[identifier] ?? null;
+  return templateValues[identifier] ?? null;
+}
+
+export function defaultValueForIdentifier(document: QtiDocument, identifier: string): QtiValue {
+  return resolveVariableDeclaration(document, identifier)?.defaultValue ?? null;
+}
+
+export function expressionIsOrdered(
+  expression: QtiProcessingExpression,
+  document: QtiDocument,
+): boolean {
+  if (expression.type === "ordered") return true;
+  if (
+    (expression.type === "variable" ||
+      expression.type === "correct" ||
+      expression.type === "default" ||
+      expression.type === "isNull") &&
+    variableCardinality(document, expression.identifier) === "ordered"
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function variableCardinality(document: QtiDocument, identifier: string): string | undefined {
+  return resolveVariableDeclaration(document, identifier)?.cardinality;
+}
+
+function resolveVariableDeclaration(
+  document: QtiDocument,
+  identifier: string,
+): QtiResponseDeclaration | QtiOutcomeDeclaration | QtiTemplateDeclaration | undefined {
+  return (
+    document.item.responseDeclarations.find(
+      (declaration) => declaration.identifier === identifier,
+    ) ??
+    document.item.outcomeDeclarations.find(
+      (declaration) => declaration.identifier === identifier,
+    ) ??
+    document.item.templateDeclarations.find((declaration) => declaration.identifier === identifier)
+  );
+}