@longsightgroup/qti3-core 0.9.1 → 0.9.3

package/src/processing-evaluator-comparison.ts

@@ -0,0 +1,106 @@
+import type { QtiProcessingExpression, QtiValue } from "./types.js";
+import { assertNever } from "./assert-never.js";
+import type { EvaluationContext } from "./processing-evaluator.js";
+import {
+  containsValues,
+  durationSeconds,
+  numericValueOrNull,
+  qtiMatchValues,
+  valuesEqual,
+  valueContainer,
+} from "./processing-values.js";
+import { expressionIsOrdered } from "./processing-variables.js";
+import { roundWithMode } from "./processing-operators.js";
+
+type ComparisonExpression = Extract<
+  QtiProcessingExpression,
+  {
+    type:
+      | "match"
+      | "equal"
+      | "equalRounded"
+      | "numericCompare"
+      | "durationCompare"
+      | "member"
+      | "delete"
+      | "contains";
+  }
+>;
+
+export function evaluateComparisonExpression(
+  expression: ComparisonExpression,
+  context: EvaluationContext,
+): QtiValue {
+  switch (expression.type) {
+    case "match": {
+      const left = context.evaluate(expression.left);
+      const right = context.evaluate(expression.right);
+      return qtiMatchValues(
+        left,
+        right,
+        expressionIsOrdered(expression.left, context.document) ||
+          expressionIsOrdered(expression.right, context.document),
+      );
+    }
+    case "equal": {
+      const left = context.evaluate(expression.left);
+      const right = context.evaluate(expression.right);
+      return left === null || right === null ? null : valuesEqual(left, right);
+    }
+    case "equalRounded": {
+      const left = context.evaluate(expression.left);
+      const right = context.evaluate(expression.right);
+      if (left === null || right === null) return null;
+      const leftNumber = numericValueOrNull(left);
+      const rightNumber = numericValueOrNull(right);
+      if (leftNumber === null || rightNumber === null) return null;
+      const roundedLeft = roundWithMode(leftNumber, expression.roundingMode, expression.figures);
+      const roundedRight = roundWithMode(rightNumber, expression.roundingMode, expression.figures);
+      return roundedLeft === null || roundedRight === null ? null : roundedLeft === roundedRight;
+    }
+    case "numericCompare": {
+      const leftValue = context.evaluate(expression.left);
+      const rightValue = context.evaluate(expression.right);
+      if (leftValue === null || rightValue === null) return null;
+      const left = numericValueOrNull(leftValue);
+      const right = numericValueOrNull(rightValue);
+      if (left === null || right === null) return null;
+      if (expression.operator === "lt") return left < right;
+      if (expression.operator === "lte") return left <= right;
+      if (expression.operator === "gt") return left > right;
+      return left >= right;
+    }
+    case "durationCompare": {
+      const left = durationSeconds(context.evaluate(expression.left));
+      const right = durationSeconds(context.evaluate(expression.right));
+      if (left === null || right === null) return null;
+      return expression.operator === "lt" ? left < right : left >= right;
+    }
+    case "member": {
+      const value = context.evaluate(expression.value);
+      const collection = context.evaluate(expression.collection);
+      if (value === null || collection === null) return null;
+      return valueContainer(collection).some((item) => valuesEqual(item, value));
+    }
+    case "delete": {
+      const value = context.evaluate(expression.value);
+      const collectionValue = context.evaluate(expression.collection);
+      if (value === null || collectionValue === null) return null;
+      const collection = valueContainer(collectionValue);
+      if (collection.length === 0) return null;
+      const filtered = collection.filter((item) => !valuesEqual(item, value));
+      return filtered.length > 0 ? filtered : null;
+    }
+    case "contains": {
+      const collectionValue = context.evaluate(expression.collection);
+      const valuesValue = context.evaluate(expression.values);
+      if (collectionValue === null || valuesValue === null) return null;
+      const collection = valueContainer(collectionValue);
+      const values = valueContainer(valuesValue);
+      if (collection.length === 0 || values.length === 0) return null;
+      return containsValues(collection, values);
+    }
+    default:
+      return assertNever(expression);
+  }
+}

package/src/processing-evaluator-custom.ts

@@ -0,0 +1,20 @@
+import type { QtiProcessingExpression, QtiValue } from "./types.js";
+import type { EvaluationContext } from "./processing-evaluator.js";
+
+type CustomOperatorExpression = Extract<QtiProcessingExpression, { type: "customOperator" }>;
+
+export function evaluateCustomOperatorExpression(
+  expression: CustomOperatorExpression,
+  context: EvaluationContext,
+): QtiValue {
+  const operatorKey = expression.definition ?? expression.className ?? "";
+  const handler = context.customOperators[operatorKey];
+  if (!handler) return null;
+  return handler({
+    definition: expression.definition,
+    className: expression.className,
+    attributes: expression.attributes,
+    values: expression.expressions.map((item) => context.evaluate(item)),
+    expression,
+  });
+}

package/src/processing-evaluator-geometry.ts

@@ -0,0 +1,26 @@
+import type { QtiProcessingExpression, QtiValue } from "./types.js";
+import type { EvaluationContext } from "./processing-evaluator.js";
+import { parsePoint, pointInsideArea } from "./processing-mapping.js";
+import { valueContainer } from "./processing-values.js";
+
+type GeometryExpression = Extract<QtiProcessingExpression, { type: "inside" }>;
+
+export function evaluateGeometryExpression(
+  expression: GeometryExpression,
+  context: EvaluationContext,
+): QtiValue {
+  const value = context.evaluate(expression.expression);
+  if (value === null) return null;
+  if (expression.shape === "default") return true;
+  return valueContainer(value).some((pointValue) => {
+    const point = parsePoint(String(pointValue));
+    return point
+      ? pointInsideArea(point, {
+          shape: expression.shape,
+          coords: expression.coords,
+          mappedValue: 0,
+          attributes: {},
+        })
+      : false;
+  });
+}

package/src/processing-evaluator-numeric.ts

@@ -0,0 +1,155 @@
+import type { QtiProcessingExpression, QtiValue } from "./types.js";
+import { assertNever } from "./assert-never.js";
+import type { EvaluationContext } from "./processing-evaluator.js";
+import {
+  generalizedGcd,
+  generalizedLcm,
+  mathOperatorValue,
+  roundToDecimalPlaces,
+  roundToSignificantFigures,
+  statsOperatorValue,
+} from "./processing-operators.js";
+import {
+  isRecordValue,
+  numericValue,
+  numericValueOrNull,
+  valueContainer,
+} from "./processing-values.js";
+
+type NumericExpression = Extract<
+  QtiProcessingExpression,
+  {
+    type:
+      | "sum"
+      | "product"
+      | "min"
+      | "max"
+      | "subtract"
+      | "divide"
+      | "power"
+      | "integerDivide"
+      | "integerModulus"
+      | "round"
+      | "roundTo"
+      | "truncate"
+      | "integerToFloat"
+      | "gcd"
+      | "lcm"
+      | "mathConstant"
+      | "mathOperator"
+      | "statsOperator";
+  }
+>;
+
+export function evaluateNumericExpression(
+  expression: NumericExpression,
+  context: EvaluationContext,
+): QtiValue {
+  switch (expression.type) {
+    case "sum": {
+      const values = context.numericOperands(expression.expressions);
+      return values ? values.reduce((sum, value) => sum + value, 0) : null;
+    }
+    case "product": {
+      const values = context.numericOperands(expression.expressions);
+      return values ? values.reduce((product, value) => product * value, 1) : null;
+    }
+    case "min":
+    case "max": {
+      const values = context.numericOperands(expression.expressions);
+      if (!values || values.length === 0) return null;
+      return expression.type === "min" ? Math.min(...values) : Math.max(...values);
+    }
+    case "subtract": {
+      const values = context.numericOperands([expression.left, expression.right]);
+      return values && values.length === 2 ? values[0]! - values[1]! : null;
+    }
+    case "divide":
+      return divide(context.evaluate(expression.left), context.evaluate(expression.right));
+    case "power": {
+      const values = context.numericOperands([expression.left, expression.right]);
+      if (!values || values.length !== 2) return null;
+      const value = Math.pow(values[0]!, values[1]!);
+      return Number.isFinite(value) ? value : null;
+    }
+    case "integerDivide": {
+      const values = integerOperands(
+        context.evaluate(expression.left),
+        context.evaluate(expression.right),
+      );
+      return values ? Math.floor(values.dividend / values.divisor) : null;
+    }
+    case "integerModulus": {
+      const values = integerOperands(
+        context.evaluate(expression.left),
+        context.evaluate(expression.right),
+      );
+      return values
+        ? values.dividend - Math.floor(values.dividend / values.divisor) * values.divisor
+        : null;
+    }
+    case "round": {
+      const value = numericValueOrNull(context.evaluate(expression.expression));
+      return value === null ? null : Math.round(value);
+    }
+    case "roundTo": {
+      const value = numericValueOrNull(context.evaluate(expression.expression));
+      if (value === null) return null;
+      return expression.roundingMode === "decimalPlaces"
+        ? roundToDecimalPlaces(value, expression.figures)
+        : roundToSignificantFigures(value, expression.figures);
+    }
+    case "truncate": {
+      const value = numericValueOrNull(context.evaluate(expression.expression));
+      return value === null ? null : Math.trunc(value);
+    }
+    case "integerToFloat":
+      return numericValueOrNull(context.evaluate(expression.expression));
+    case "gcd":
+    case "lcm": {
+      const values = expression.expressions.flatMap((item) => {
+        const value = context.evaluate(item);
+        return value === null ? [null] : valueContainer(value);
+      });
+      if (values.length === 0 || values.some((value) => value === null || isRecordValue(value))) {
+        return null;
+      }
+      const integers = values.map((value) => Math.trunc(numericValue(value)));
+      return expression.type === "gcd" ? generalizedGcd(integers) : generalizedLcm(integers);
+    }
+    case "mathConstant":
+      if (expression.name === "pi") return Math.PI;
+      if (expression.name === "e") return Math.E;
+      return null;
+    case "mathOperator": {
+      const values = expression.expressions.map((item) => context.evaluate(item));
+      if (values.length === 0 || values.some((value) => value === null)) return null;
+      return mathOperatorValue(expression.name, values.map(numericValue));
+    }
+    case "statsOperator": {
+      const value = context.evaluate(expression.expression);
+      if (value === null) return null;
+      return statsOperatorValue(expression.name, valueContainer(value).map(numericValue));
+    }
+    default:
+      return assertNever(expression);
+  }
+}
+
+function divide(dividendValue: QtiValue, divisorValue: QtiValue): QtiValue {
+  const values = integerOperands(dividendValue, divisorValue);
+  if (!values) return null;
+  const quotient = values.dividend / values.divisor;
+  return Number.isFinite(quotient) ? quotient : null;
+}
+
+function integerOperands(
+  dividendValue: QtiValue,
+  divisorValue: QtiValue,
+): { dividend: number; divisor: number } | undefined {
+  if (dividendValue === null || divisorValue === null) return undefined;
+  const dividend = numericValueOrNull(dividendValue);
+  const divisor = numericValueOrNull(divisorValue);
+  if (dividend === null || divisor === null || divisor === 0) return undefined;
+  return { dividend, divisor };
+}

package/src/processing-evaluator-string.ts

@@ -0,0 +1,60 @@
+import type { QtiProcessingExpression, QtiValue } from "./types.js";
+import { assertNever } from "./assert-never.js";
+import type { EvaluationContext } from "./processing-evaluator.js";
+import { qtiValueToString } from "./value-format.js";
+import { isRecordValue, stringMatch } from "./processing-values.js";
+import { resolveOptionalVariableValue } from "./processing-variables.js";
+
+type StringExpression = Extract<
+  QtiProcessingExpression,
+  { type: "stringMatch" | "substring" | "patternMatch" | "fieldValue" }
+>;
+
+export function evaluateStringExpression(
+  expression: StringExpression,
+  context: EvaluationContext,
+): QtiValue {
+  switch (expression.type) {
+    case "stringMatch":
+      return stringMatch(
+        context.evaluate(expression.left),
+        context.evaluate(expression.right),
+        expression.caseSensitive,
+        expression.substring,
+      );
+    case "substring":
+      return stringMatch(
+        context.evaluate(expression.right),
+        context.evaluate(expression.left),
+        expression.caseSensitive,
+        true,
+      );
+    case "patternMatch": {
+      const value = context.evaluate(expression.expression);
+      if (value === null) return null;
+      const patternValue =
+        resolveOptionalVariableValue(
+          context.document,
+          expression.pattern,
+          context.responses,
+          context.outcomes,
+          context.templateValues,
+        ) ??
+        context.undeclaredResponseValue(expression.pattern) ??
+        expression.pattern;
+      try {
+        return new RegExp(
+          typeof patternValue === "string" ? patternValue : qtiValueToString(patternValue),
+        ).test(qtiValueToString(value));
+      } catch {
+        return null;
+      }
+    }
+    case "fieldValue": {
+      const value = context.evaluate(expression.expression);
+      return isRecordValue(value) ? (value[expression.fieldIdentifier] ?? null) : null;
+    }
+    default:
+      return assertNever(expression);
+  }
+}

package/src/processing-evaluator-variable.ts

@@ -0,0 +1,81 @@
+import type { QtiProcessingExpression, QtiValue } from "./types.js";
+import { assertNever } from "./assert-never.js";
+import type { EvaluationContext } from "./processing-evaluator.js";
+import { mapOrMatchResponse, scoreAreaMapping } from "./processing-mapping.js";
+import { isNullResponse, qtiMatchValues } from "./processing-values.js";
+import {
+  defaultValueForIdentifier,
+  getResponseDeclaration,
+  resolveVariableValue,
+} from "./processing-variables.js";
+
+type VariableExpression = Extract<
+  QtiProcessingExpression,
+  {
+    type:
+      | "isNull"
+      | "matchCorrect"
+      | "mapResponse"
+      | "mapResponsePoint"
+      | "correct"
+      | "default"
+      | "variable";
+  }
+>;
+
+export function evaluateVariableExpression(
+  expression: VariableExpression,
+  context: EvaluationContext,
+): QtiValue {
+  switch (expression.type) {
+    case "isNull":
+      return isNullResponse(context.responses[expression.identifier] ?? null);
+    case "matchCorrect": {
+      const declaration = getResponseDeclaration(context.document, expression.correctIdentifier);
+      return declaration
+        ? qtiMatchValues(
+            context.responses[expression.identifier] ?? null,
+            context.correctResponses[expression.correctIdentifier] ?? null,
+            declaration.cardinality === "ordered",
+          )
+        : false;
+    }
+    case "mapResponse": {
+      const declaration = getResponseDeclaration(context.document, expression.identifier);
+      return declaration
+        ? mapOrMatchResponse(
+            declaration,
+            context.responses[expression.identifier] ?? null,
+            context.correctResponses[expression.identifier] ?? null,
+          )
+        : 0;
+    }
+    case "mapResponsePoint": {
+      const declaration = getResponseDeclaration(context.document, expression.identifier);
+      return declaration?.areaMapping
+        ? scoreAreaMapping(
+            context.responses[expression.identifier] ?? null,
+            declaration.areaMapping,
+          )
+        : 0;
+    }
+    case "correct":
+      return context.correctResponses[expression.identifier] ?? null;
+    case "default":
+      return defaultValueForIdentifier(context.document, expression.identifier);
+    case "variable":
+      return (
+        resolveVariableValue(
+          context.document,
+          expression.identifier,
+          context.responses,
+          context.outcomes,
+          context.templateValues,
+        ) ??
+        context.undeclaredResponseValue(expression.identifier) ??
+        null
+      );
+    default:
+      return assertNever(expression);
+  }
+}

package/src/processing-evaluator.ts

@@ -0,0 +1,173 @@
+import type { QtiDocument, QtiProcessingExpression, QtiValue } from "./types.js";
+import { assertNever } from "./assert-never.js";
+import type { QtiCustomOperatorRegistry } from "./custom-operators.js";
+import { evaluateBooleanExpression } from "./processing-evaluator-boolean.js";
+import {
+  evaluateCollectionExpression,
+  evaluateRepeatExpression,
+} from "./processing-evaluator-collection.js";
+import { evaluateComparisonExpression } from "./processing-evaluator-comparison.js";
+import { evaluateCustomOperatorExpression } from "./processing-evaluator-custom.js";
+import { evaluateGeometryExpression } from "./processing-evaluator-geometry.js";
+import { evaluateNumericExpression } from "./processing-evaluator-numeric.js";
+import { evaluateStringExpression } from "./processing-evaluator-string.js";
+import { evaluateVariableExpression } from "./processing-evaluator-variable.js";
+import { isRecordValue, numericValueOrNull } from "./processing-values.js";
+
+export interface EvaluationContext {
+  document: QtiDocument;
+  responses: Record<string, QtiValue>;
+  outcomes: Record<string, QtiValue>;
+  templateValues: Record<string, QtiValue>;
+  correctResponses: Record<string, QtiValue>;
+  allowedUndeclaredResponseIdentifiers: ReadonlySet<string>;
+  random: () => number;
+  customOperators: QtiCustomOperatorRegistry;
+  evaluate(expression: QtiProcessingExpression): QtiValue;
+  indexValue(identifierOrInteger: string): number | undefined;
+  numericOperands(expressions: QtiProcessingExpression[]): number[] | null;
+  undeclaredResponseValue(identifier: string): QtiValue | undefined;
+}
+
+export interface EvaluationOptions {
+  allowedUndeclaredResponseIdentifiers?: ReadonlySet<string> | readonly string[] | undefined;
+}
+
+export function createEvaluationContext(
+  document: QtiDocument,
+  responses: Record<string, QtiValue>,
+  outcomes: Record<string, QtiValue>,
+  templateValues: Record<string, QtiValue>,
+  correctResponses: Record<string, QtiValue>,
+  random: () => number,
+  customOperators: QtiCustomOperatorRegistry,
+  options: EvaluationOptions = {},
+): EvaluationContext {
+  const allowedUndeclaredResponseIdentifiers =
+    options.allowedUndeclaredResponseIdentifiers instanceof Set
+      ? options.allowedUndeclaredResponseIdentifiers
+      : new Set(options.allowedUndeclaredResponseIdentifiers ?? []);
+  const context: EvaluationContext = {
+    document,
+    responses,
+    outcomes,
+    templateValues,
+    correctResponses,
+    allowedUndeclaredResponseIdentifiers,
+    random,
+    customOperators,
+    evaluate(expression) {
+      return evaluateProcessingExpression(expression, context);
+    },
+    indexValue(identifierOrInteger) {
+      const parsed = Number(identifierOrInteger);
+      if (Number.isInteger(parsed)) return parsed;
+      const value = outcomes[identifierOrInteger] ?? templateValues[identifierOrInteger] ?? null;
+      const numeric = numericValueOrNull(value);
+      return numeric !== null && Number.isInteger(numeric) ? numeric : undefined;
+    },
+    numericOperands(expressions) {
+      const numericValues: number[] = [];
+      for (const expression of expressions) {
+        const value = context.evaluate(expression);
+        if (value === null || isRecordValue(value)) return null;
+        const values = Array.isArray(value) ? value : [value];
+        for (const item of values) {
+          const numeric = numericValueOrNull(item);
+          if (numeric === null) return null;
+          numericValues.push(numeric);
+        }
+      }
+      return numericValues;
+    },
+    undeclaredResponseValue(identifier) {
+      return allowedUndeclaredResponseIdentifiers.has(identifier) && identifier in responses
+        ? (responses[identifier] ?? null)
+        : undefined;
+    },
+  };
+  return context;
+}
+
+export function evaluateProcessingExpression(
+  expression: QtiProcessingExpression,
+  context: EvaluationContext,
+): QtiValue {
+  switch (expression.type) {
+    case "baseValue":
+      return expression.value;
+    case "null":
+      return null;
+    case "randomInteger": {
+      const step = expression.step > 0 ? expression.step : 1;
+      const count = Math.floor((expression.max - expression.min) / step) + 1;
+      return expression.min + Math.floor(context.random() * count) * step;
+    }
+    case "randomFloat":
+      return expression.min + context.random() * (expression.max - expression.min);
+    case "random":
+      if (expression.values.length === 0) return null;
+      return context.evaluate(
+        expression.values[Math.floor(context.random() * expression.values.length)]!,
+      );
+    case "isNull":
+    case "matchCorrect":
+    case "mapResponse":
+    case "mapResponsePoint":
+    case "correct":
+    case "default":
+    case "variable":
+      return evaluateVariableExpression(expression, context);
+    case "multiple":
+    case "ordered":
+    case "index":
+    case "containerSize":
+      return evaluateCollectionExpression(expression, context);
+    case "sum":
+    case "product":
+    case "min":
+    case "max":
+    case "subtract":
+    case "divide":
+    case "power":
+    case "integerDivide":
+    case "integerModulus":
+    case "round":
+    case "roundTo":
+    case "truncate":
+    case "integerToFloat":
+    case "gcd":
+    case "lcm":
+    case "mathConstant":
+    case "mathOperator":
+    case "statsOperator":
+      return evaluateNumericExpression(expression, context);
+    case "and":
+    case "anyN":
+    case "or":
+    case "not":
+      return evaluateBooleanExpression(expression, context);
+    case "match":
+    case "equal":
+    case "equalRounded":
+    case "numericCompare":
+    case "durationCompare":
+    case "member":
+    case "delete":
+    case "contains":
+      return evaluateComparisonExpression(expression, context);
+    case "stringMatch":
+    case "substring":
+    case "patternMatch":
+    case "fieldValue":
+      return evaluateStringExpression(expression, context);
+    case "inside":
+      return evaluateGeometryExpression(expression, context);
+    case "repeat":
+      return evaluateRepeatExpression(expression, context);
+    case "customOperator":
+      return evaluateCustomOperatorExpression(expression, context);
+    default:
+      return assertNever(expression);
+  }
+}

package/src/processing-expression-children.ts

@@ -0,0 +1,69 @@
+import type { QtiProcessingExpression } from "./types.js";
+import { assertNever } from "./assert-never.js";
+
+export function expressionChildren(expression: QtiProcessingExpression): QtiProcessingExpression[] {
+  switch (expression.type) {
+    case "random":
+      return expression.values;
+    case "multiple":
+    case "ordered":
+    case "sum":
+    case "product":
+    case "min":
+    case "max":
+    case "and":
+    case "anyN":
+    case "or":
+    case "gcd":
+    case "lcm":
+    case "mathOperator":
+    case "repeat":
+    case "customOperator":
+      return expression.expressions;
+    case "subtract":
+    case "divide":
+    case "power":
+    case "integerDivide":
+    case "integerModulus":
+    case "match":
+    case "equal":
+    case "equalRounded":
+    case "numericCompare":
+    case "durationCompare":
+    case "stringMatch":
+    case "substring":
+      return [expression.left, expression.right];
+    case "not":
+    case "round":
+    case "roundTo":
+    case "truncate":
+    case "integerToFloat":
+    case "index":
+    case "containerSize":
+    case "patternMatch":
+    case "fieldValue":
+    case "inside":
+    case "statsOperator":
+      return [expression.expression];
+    case "member":
+    case "delete":
+      return [expression.value, expression.collection];
+    case "contains":
+      return [expression.collection, expression.values];
+    case "baseValue":
+    case "correct":
+    case "default":
+    case "isNull":
+    case "mapResponse":
+    case "mapResponsePoint":
+    case "matchCorrect":
+    case "mathConstant":
+    case "null":
+    case "randomFloat":
+    case "randomInteger":
+    case "variable":
+      return [];
+    default:
+      return assertNever(expression);
+  }
+}