@longsightgroup/qti3-core 0.9.2 → 0.9.3

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

package/src/serializer-processing-expressions.ts

@@ -11,6 +11,7 @@ import {
   type UnaryExpressionType,
 } from "./processing-expression-tags.js";
 import { escapeXmlText } from "./xml.js";
+import { assertNever } from "./assert-never.js";
 import {
   addSerializerDiagnostic,
   knownAttributesWithBagFallback,
@@ -274,7 +275,7 @@ export function serializeExpression(
         indent,
       );
     default:
-      return unsupportedExpression(expression, context);
+      return assertNever(expression);
   }
 }
 
@@ -443,14 +444,3 @@ function isSerializableBaseValue(value: QtiValue): value is string | number | bo
     (typeof value === "number" && Number.isFinite(value))
   );
 }
-
-function unsupportedExpression(
-  expression: QtiProcessingExpression,
-  context: SerializationContext,
-): string[] {
-  addSerializerDiagnostic(context, "responseProcessing.serialize.unsupportedExpression", {
-    message: `Unsupported response-processing expression type: ${expression.type}.`,
-    source: expression.source,
-  });
-  return [];
-}

package/src/serializer-processing-xml.ts

@@ -41,13 +41,13 @@ export function knownAttributesWithBagFallback(
   });
   const extras = Object.entries(bag ?? {})
     .filter(([name]) => !knownNames.has(name))
-    .sort(([left], [right]) => left.localeCompare(right));
+    .toSorted(([left], [right]) => left.localeCompare(right));
   return [...resolved, ...extras];
 }
 
 export function sortedBagAttributes(bag: Record<string, string> | undefined): XmlAttribute[] {
   return Object.entries(bag ?? {})
-    .sort(([left], [right]) => left.localeCompare(right))
+    .toSorted(([left], [right]) => left.localeCompare(right))
     .map(([name, value]) => [name, value] as const);
 }
 

package/src/serializer-processing.ts

@@ -13,6 +13,7 @@ import type {
   QtiResponseProcessing,
   QtiResponseRule,
 } from "./types.js";
+import { assertNever } from "./assert-never.js";
 
 export interface QtiSerializeResponseProcessingResult {
   ok: boolean;
@@ -114,6 +115,8 @@ function serializeResponseRule(
         rule.rules.flatMap((child) => serializeResponseRule(child, context, indent + 1)),
         indent,
       );
+    default:
+      return assertNever(rule);
   }
 }