@examplary/qti 1.1.0 → 1.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 This module provides utilities for creating and managing QTI 3.0 assessment packages, including generating IMS manifests and QTI test/item XML structures.
 
+## Building QTI assessments
+
 Example usage:
 
 ```ts
@@ -20,8 +22,10 @@ const item = new QtiItem({
   title: "Sample Question",
 });
 
-item.addResponseDeclaration({ identifier: "RESPONSE" });
-item.addCorrectResponse("RESPONSE", ["4"]);
+item.addResponseDeclaration({
+  identifier: "RESPONSE",
+  correctResponse: ["4"],
+});
 
 item.addItemBodyFromHtml("<p>What is 2 + 2?</p>");
 item.addInteraction(
@@ -47,3 +51,28 @@ test.addToPackage(pkg);
 
 const zip = await pkg.generateZip();
 ```
+
+## Parsing QTI assessments
+
+The library also supports parsing existing QTI packages:
+
+```ts
+import { QtiItem, ImsPackage, ImsManifestResourceType } from "@examplary/qti";
+import { readFile } from "fs/promises";
+
+const contents = await readFile("./example-qti-package.zip");
+const pkg = await ImsPackage.fromZip(contents);
+
+const itemResources = pkg.manifest.getResourcesOfType(
+  ImsManifestResourceType.imsqti_item_xmlv3p0,
+);
+
+for (const resource of itemResources) {
+  const item = await QtiItem.fromImsPackageResource(pkg, resource);
+  const xml = await pkg.getResourceContentsString(item.identifier);
+  const item = QtiItem.fromXmlString(xml!);
+
+  console.log("Question title:", item.title);
+  console.log("Interactions:", item.getInteractions());
+}
+```

package/dist/ims/ims-manifest.d.ts

@@ -51,5 +51,8 @@ export declare class ImsManifest {
     constructor(options?: ImsManifestOptions);
     addResource(resource: ImsManifestResource): void;
     getResources(): ImsManifestResource[];
+    getResourcesOfType(type: ImsManifestResourceType): ImsManifestResource[];
+    getResourceByIdentifier(identifier: string): ImsManifestResource | undefined;
+    static fromXmlString(xml: string): ImsManifest;
     buildXml(): string;
 }

package/dist/ims/ims-manifest.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ImsManifest = exports.ImsManifestResourceType = void 0;
+const cheerio_1 = require("cheerio");
 const xmlbuilder2_1 = require("xmlbuilder2");
 var ImsManifestResourceType;
 (function (ImsManifestResourceType) {
@@ -73,6 +74,60 @@ class ImsManifest {
     getResources() {
         return Array.from(this.resources.values());
     }
+    getResourcesOfType(type) {
+        return Array.from(this.resources.values()).filter((res) => res.type === type);
+    }
+    getResourceByIdentifier(identifier) {
+        return this.resources.get(identifier);
+    }
+    static fromXmlString(xml) {
+        const $ = (0, cheerio_1.load)(xml, { xmlMode: true });
+        const root = $("manifest");
+        if (!root.length)
+            throw new Error("Missing manifest element");
+        const resources = root.find("resources");
+        if (!resources?.length) {
+            throw new Error("Invalid IMS Manifest XML: Missing resources element");
+        }
+        const manifest = new ImsManifest({
+            identifier: root.attr("identifier"),
+            // TODO: parse other metadata if needed
+        });
+        resources.find("resource").each((_, res) => {
+            const $res = $(res);
+            const identifier = $res.attr("identifier");
+            const type = $res.attr("type");
+            if (!identifier || !type) {
+                throw new Error("Invalid IMS Manifest XML: Resource missing identifier or type");
+            }
+            const href = $res.attr("href");
+            const files = [];
+            $res.find("file").each((_, file) => {
+                const $file = $(file);
+                const fileHref = $file.attr("href");
+                if (fileHref) {
+                    files.push({ href: fileHref });
+                }
+            });
+            const dependencies = [];
+            $res.find("dependency").each((_, dep) => {
+                const $dep = $(dep);
+                const identifierref = $dep.attr("identifierref");
+                if (identifierref) {
+                    dependencies.push({ identifierref });
+                }
+            });
+            manifest.addResource({
+                identifier,
+                type: type,
+                href: href || undefined,
+                metadata: $res.find("metadata").first(), // TODO: inconsistent type casting here
+                files,
+                dependencies: dependencies.length > 0 ? dependencies : undefined,
+            });
+        });
+        return manifest;
+    }
     buildXml() {
         const manifest = (0, xmlbuilder2_1.create)({ version: "1.0", encoding: "UTF-8" }).ele("manifest", {
             xmlns: "http://www.imsglobal.org/xsd/qti/qtiv3p0/imscp_v1p1",

package/dist/ims/ims-package.d.ts

@@ -18,10 +18,12 @@ export declare class ImsPackage {
      * Create a new IMS Package.
      */
     constructor(manifestOptions?: ImsManifestOptions);
+    static fromZip(zipContents: ArrayBuffer | Buffer): Promise<ImsPackage>;
     /**
      * Add a resource to the IMS Package, along with its associated files.
      */
     addResource(resource: ImsManifestResourceWithoutFiles, files: ImsPackageFile[]): Promise<void>;
+    getResourceContentsString(resourceIdentifier: string): Promise<string | undefined>;
     /**
      * Add a file directly to the final ZIP, without adding it to the manifest.
      * Can fetch from URL or add from data.

package/dist/ims/ims-package.js

@@ -16,6 +16,19 @@ class ImsPackage {
         this.manifest = new ims_manifest_1.ImsManifest(manifestOptions);
         this.zip = new jszip_1.default();
     }
+    static async fromZip(zipContents) {
+        const zip = await jszip_1.default.loadAsync(zipContents);
+        const manifestFile = zip.file("imsmanifest.xml");
+        if (!manifestFile) {
+            throw new Error("Invalid IMS Package: Missing imsmanifest.xml");
+        }
+        const manifestXml = await manifestFile.async("string");
+        const manifest = ims_manifest_1.ImsManifest.fromXmlString(manifestXml);
+        const imsPackage = new ImsPackage(manifest);
+        imsPackage.manifest = manifest;
+        imsPackage.zip = zip;
+        return imsPackage;
+    }
     /**
      * Add a resource to the IMS Package, along with its associated files.
      */
@@ -28,6 +41,18 @@ class ImsPackage {
             files: files.map((file) => ({ href: file.filename })),
         });
     }
+    async getResourceContentsString(resourceIdentifier) {
+        const resource = this.manifest.getResourceByIdentifier(resourceIdentifier);
+        if (!resource || !resource.href) {
+            throw new Error(`Resource with identifier ${resourceIdentifier} not found or has no href`);
+        }
+        const href = resource.href || resource.files[0]?.href;
+        const file = this.zip.file(href);
+        if (!file) {
+            throw new Error(`File for resource with identifier ${resourceIdentifier} not found in ZIP in path ${href}`);
+        }
+        return file.async("string");
+    }
     /**
      * Add a file directly to the final ZIP, without adding it to the manifest.
      * Can fetch from URL or add from data.

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export * from "./ims/ims-manifest";
 export * from "./ims/ims-package";
 export * from "./qti/qti-element";
 export * from "./qti/qti-test";
+export * from "./qti/qti-test-part";
+export * from "./qti/qti-assessment-section";
 export * from "./qti/qti-item";
 export * from "./qti/interactions";
 export * from "./qti/types";

package/dist/index.js

@@ -18,6 +18,8 @@ __exportStar(require("./ims/ims-manifest"), exports);
 __exportStar(require("./ims/ims-package"), exports);
 __exportStar(require("./qti/qti-element"), exports);
 __exportStar(require("./qti/qti-test"), exports);
+__exportStar(require("./qti/qti-test-part"), exports);
+__exportStar(require("./qti/qti-assessment-section"), exports);
 __exportStar(require("./qti/qti-item"), exports);
 __exportStar(require("./qti/interactions"), exports);
 __exportStar(require("./qti/types"), exports);

package/dist/qti/interactions/associate-interaction.d.ts

@@ -1,3 +1,4 @@
+import { XMLBuilder } from "xmlbuilder2/lib/interfaces";
 import { QtiPromptInteraction, QtiPromptInteractionOptions } from "./interaction";
 export type SimpleAssociableChoiceOptions = {
     identifier: string;
@@ -32,5 +33,12 @@ export type AssociateInteractionOptions = QtiPromptInteractionOptions & {
  * });
  */
 export declare class AssociateInteraction extends QtiPromptInteraction {
+    static tagName: string;
+    shuffle?: boolean;
+    minAssociations?: number;
+    maxAssociations?: number;
+    choices?: SimpleAssociableChoiceOptions[];
     constructor(options: AssociateInteractionOptions);
+    static fromXmlString(xml: string): AssociateInteraction;
+    protected buildXmlPayload(): XMLBuilder;
 }

package/dist/qti/interactions/associate-interaction.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AssociateInteraction = void 0;
+const cheerio_1 = require("cheerio");
 const xmlbuilder2_1 = require("xmlbuilder2");
 const interaction_1 = require("./interaction");
 const html_1 = require("../../utils/html");
@@ -22,17 +23,61 @@ const html_1 = require("../../utils/html");
  * });
  */
 class AssociateInteraction extends interaction_1.QtiPromptInteraction {
+    static tagName = "qti-associate-interaction";
+    shuffle;
+    minAssociations;
+    maxAssociations;
+    choices;
     constructor(options) {
         super(options);
-        this.item = (0, xmlbuilder2_1.fragment)().ele("qti-associate-interaction", {
-            "response-identifier": options.responseIdentifier,
-            label: options.label,
-            shuffle: options.shuffle ? "true" : "false",
-            "min-associations": options.minAssociations?.toString(),
-            "max-associations": options.maxAssociations?.toString(),
+        this.shuffle = options.shuffle;
+        this.minAssociations = options.minAssociations;
+        this.maxAssociations = options.maxAssociations;
+        this.choices = options.choices;
+    }
+    static fromXmlString(xml) {
+        const choices = [];
+        const $ = (0, cheerio_1.load)(xml, { xmlMode: true });
+        const $root = $("qti-associate-interaction");
+        $("qti-simple-associable-choice").each((_, node) => {
+            const choice = $(node);
+            choices.push({
+                identifier: choice.attr("identifier"),
+                matchMax: choice.attr("match-max")
+                    ? Number(choice.attr("match-max"))
+                    : undefined,
+                matchMin: choice.attr("match-min")
+                    ? Number(choice.attr("match-min"))
+                    : undefined,
+                matchGroup: choice.attr("match-group"),
+                fixed: choice.attr("fixed") === "true",
+                templateIdentifier: choice.attr("template-identifier"),
+                content: (choice.html() || "").trim(),
+            });
+        });
+        return new AssociateInteraction({
+            responseIdentifier: $root.attr("response-identifier"),
+            label: $root.attr("label"),
+            shuffle: $root.attr("shuffle") === "true",
+            minAssociations: $root.attr("min-associations")
+                ? Number($root.attr("min-associations"))
+                : undefined,
+            maxAssociations: $root.attr("max-associations")
+                ? Number($root.attr("max-associations"))
+                : undefined,
+            choices,
+        });
+    }
+    buildXmlPayload() {
+        const item = (0, xmlbuilder2_1.fragment)().ele("qti-associate-interaction", {
+            "response-identifier": this.responseIdentifier,
+            label: this.label,
+            shuffle: this.shuffle ? "true" : "false",
+            "min-associations": this.minAssociations?.toString(),
+            "max-associations": this.maxAssociations?.toString(),
         });
-        for (const choice of options.choices || []) {
-            const choiceEl = this.item.ele("qti-simple-associable-choice", {
+        for (const choice of this.choices || []) {
+            const choiceEl = item.ele("qti-simple-associable-choice", {
                 identifier: choice.identifier,
                 "match-max": choice.matchMax?.toString(),
                 "match-min": choice.matchMin?.toString(),
@@ -44,6 +89,7 @@ class AssociateInteraction extends interaction_1.QtiPromptInteraction {
                 (0, html_1.appendHtmlFragment)(choice.content, choiceEl);
             }
         }
+        return item;
     }
 }
 exports.AssociateInteraction = AssociateInteraction;

package/dist/qti/interactions/choice-interaction.d.ts

@@ -1,3 +1,4 @@
+import { XMLBuilder } from "xmlbuilder2/lib/interfaces";
 import { QtiPromptInteraction, QtiPromptInteractionOptions } from "./interaction";
 export type SimpleChoiceOptions = {
     identifier: string;
@@ -32,5 +33,15 @@ export type ChoiceInteractionOptions = QtiPromptInteractionOptions & {
  * });
  */
 export declare class ChoiceInteraction extends QtiPromptInteraction {
+    static tagName: string;
+    choices?: SimpleChoiceOptions[];
+    shuffle?: boolean;
+    maxChoices?: number;
+    minChoices?: number;
+    orientation?: "horizontal" | "vertical";
+    minSelectionsMessage?: string;
+    maxSelectionsMessage?: string;
     constructor(options: ChoiceInteractionOptions);
+    static fromXmlString(xml: string): ChoiceInteraction;
+    protected buildXmlPayload(): XMLBuilder;
 }

package/dist/qti/interactions/choice-interaction.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChoiceInteraction = void 0;
+const cheerio_1 = require("cheerio");
 const xmlbuilder2_1 = require("xmlbuilder2");
 const interaction_1 = require("./interaction");
 const html_1 = require("../../utils/html");
@@ -21,26 +22,74 @@ const html_1 = require("../../utils/html");
  * });
  */
 class ChoiceInteraction extends interaction_1.QtiPromptInteraction {
+    static tagName = "qti-choice-interaction";
+    choices;
+    shuffle;
+    maxChoices;
+    minChoices;
+    orientation;
+    minSelectionsMessage;
+    maxSelectionsMessage;
     constructor(options) {
         super(options);
-        this.item = (0, xmlbuilder2_1.fragment)().ele("qti-choice-interaction", {
-            "response-identifier": options.responseIdentifier,
-            label: options.label,
-            shuffle: options.shuffle ? "true" : "false",
-            "max-choices": options.maxChoices?.toString(),
-            "min-choices": options.minChoices?.toString(),
-            orientation: options.orientation,
-            "data-min-selections-message": options.minSelectionsMessage,
-            "data-max-selections-message": options.maxSelectionsMessage,
+        this.shuffle = options.shuffle;
+        this.maxChoices = options.maxChoices;
+        this.minChoices = options.minChoices;
+        this.orientation = options.orientation;
+        this.minSelectionsMessage = options.minSelectionsMessage;
+        this.maxSelectionsMessage = options.maxSelectionsMessage;
+        this.choices = options.choices;
+    }
+    static fromXmlString(xml) {
+        const choices = [];
+        const $ = (0, cheerio_1.load)(xml, { xmlMode: true });
+        const $root = $("qti-choice-interaction");
+        $("qti-simple-choice").each((_, node) => {
+            const choice = $(node);
+            choices.push({
+                identifier: choice.attr("identifier"),
+                fixed: choice.attr("fixed") === "true",
+                templateIdentifier: choice.attr("template-identifier"),
+                label: choice.attr("label"),
+                content: (choice.html() || "").trim(),
+            });
+        });
+        return new ChoiceInteraction({
+            responseIdentifier: $root.attr("response-identifier"),
+            label: $root.attr("label"),
+            shuffle: $root.attr("shuffle") === "true",
+            minChoices: $root.attr("min-choices")
+                ? Number($root.attr("min-choices"))
+                : undefined,
+            maxChoices: $root.attr("max-choices")
+                ? Number($root.attr("max-choices"))
+                : undefined,
+            orientation: $root.attr("orientation"),
+            minSelectionsMessage: $root.attr("data-min-selections-message"),
+            maxSelectionsMessage: $root.attr("data-max-selections-message"),
+            choices,
+        });
+    }
+    buildXmlPayload() {
+        const item = (0, xmlbuilder2_1.fragment)().ele("qti-choice-interaction", {
+            "response-identifier": this.responseIdentifier,
+            label: this.label,
+            shuffle: this.shuffle ? "true" : "false",
+            "max-choices": this.maxChoices?.toString(),
+            "min-choices": this.minChoices?.toString(),
+            orientation: this.orientation,
+            "data-min-selections-message": this.minSelectionsMessage,
+            "data-max-selections-message": this.maxSelectionsMessage,
         });
-        for (const choice of options.choices || []) {
-            (0, html_1.appendHtmlFragment)(choice.content || "", this.item.ele("qti-simple-choice", {
+        for (const choice of this.choices || []) {
+            (0, html_1.appendHtmlFragment)(choice.content || "", item.ele("qti-simple-choice", {
                 identifier: choice.identifier,
                 fixed: choice.fixed ? "true" : "false",
                 "template-identifier": choice.templateIdentifier,
                 label: choice.label,
             }));
         }
+        return item;
     }
 }
 exports.ChoiceInteraction = ChoiceInteraction;

package/dist/qti/interactions/drawing-interaction.d.ts

@@ -1,3 +1,4 @@
+import { XMLBuilder } from "xmlbuilder2/lib/interfaces";
 import { QtiPromptInteraction, QtiPromptInteractionOptions } from "./interaction";
 export type DrawingObjectOptions = {
     data: string;
@@ -21,5 +22,9 @@ export type DrawingInteractionOptions = QtiPromptInteractionOptions & {
  * });
  */
 export declare class DrawingInteraction extends QtiPromptInteraction {
+    static tagName: string;
+    object: DrawingObjectOptions;
     constructor(options: DrawingInteractionOptions);
+    static fromXmlString(xml: string): DrawingInteraction;
+    protected buildXmlPayload(): XMLBuilder;
 }

package/dist/qti/interactions/drawing-interaction.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DrawingInteraction = void 0;
+const cheerio_1 = require("cheerio");
 const xmlbuilder2_1 = require("xmlbuilder2");
 const interaction_1 = require("./interaction");
 /**
@@ -16,18 +17,43 @@ const interaction_1 = require("./interaction");
  * });
  */
 class DrawingInteraction extends interaction_1.QtiPromptInteraction {
+    static tagName = "qti-drawing-interaction";
+    object;
     constructor(options) {
         super(options);
-        this.item = (0, xmlbuilder2_1.fragment)().ele("qti-drawing-interaction", {
-            "response-identifier": options.responseIdentifier,
-            label: options.label,
+        this.object = options.object;
+    }
+    static fromXmlString(xml) {
+        const $ = (0, cheerio_1.load)(xml, { xmlMode: true });
+        const $root = $("qti-drawing-interaction");
+        const $object = $root.find("object");
+        return new DrawingInteraction({
+            responseIdentifier: $root.attr("response-identifier"),
+            label: $root.attr("label"),
+            object: {
+                data: $object.attr("data"),
+                type: $object.attr("type"),
+                width: $object.attr("width")
+                    ? Number($object.attr("width"))
+                    : undefined,
+                height: $object.attr("height")
+                    ? Number($object.attr("height"))
+                    : undefined,
+            },
+        });
+    }
+    buildXmlPayload() {
+        const item = (0, xmlbuilder2_1.fragment)().ele("qti-drawing-interaction", {
+            "response-identifier": this.responseIdentifier,
+            label: this.label,
         });
-        this.item.ele("object", {
-            data: options.object.data,
-            type: options.object.type,
-            width: options.object.width?.toString(),
-            height: options.object.height?.toString(),
+        item.ele("object", {
+            data: this.object.data,
+            type: this.object.type,
+            width: this.object.width?.toString(),
+            height: this.object.height?.toString(),
         });
+        return item;
     }
 }
 exports.DrawingInteraction = DrawingInteraction;

package/dist/qti/interactions/end-attempt-interaction.d.ts

@@ -1,3 +1,4 @@
+import { XMLBuilder } from "xmlbuilder2/lib/interfaces";
 import { QtiInteraction, QtiInteractionOptions } from "./interaction";
 export type EndAttemptInteractionOptions = QtiInteractionOptions & {
     title: string;
@@ -17,5 +18,10 @@ export type EndAttemptInteractionOptions = QtiInteractionOptions & {
  * });
  */
 export declare class EndAttemptInteraction extends QtiInteraction {
+    static tagName: string;
+    title: string;
+    countAttempt?: boolean;
     constructor(options: EndAttemptInteractionOptions);
+    static fromXmlString(xml: string): EndAttemptInteraction;
+    protected buildXmlPayload(): XMLBuilder;
 }

package/dist/qti/interactions/end-attempt-interaction.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EndAttemptInteraction = void 0;
+const cheerio_1 = require("cheerio");
 const xmlbuilder2_1 = require("xmlbuilder2");
 const interaction_1 = require("./interaction");
 /**
@@ -17,14 +18,32 @@ const interaction_1 = require("./interaction");
  * });
  */
 class EndAttemptInteraction extends interaction_1.QtiInteraction {
+    static tagName = "qti-end-attempt-interaction";
+    title;
+    countAttempt;
     constructor(options) {
         super(options);
-        this.item = (0, xmlbuilder2_1.fragment)().ele("qti-end-attempt-interaction", {
-            "response-identifier": options.responseIdentifier,
-            label: options.label,
-            title: options.title,
-            "count-attempt": options.countAttempt ? "true" : undefined,
+        this.title = options.title;
+        this.countAttempt = options.countAttempt;
+    }
+    static fromXmlString(xml) {
+        const $ = (0, cheerio_1.load)(xml, { xmlMode: true });
+        const $root = $("qti-end-attempt-interaction");
+        return new EndAttemptInteraction({
+            responseIdentifier: $root.attr("response-identifier"),
+            label: $root.attr("label"),
+            title: $root.attr("title"),
+            countAttempt: $root.attr("count-attempt") === "true",
+        });
+    }
+    buildXmlPayload() {
+        const item = (0, xmlbuilder2_1.fragment)().ele("qti-end-attempt-interaction", {
+            "response-identifier": this.responseIdentifier,
+            label: this.label,
+            title: this.title,
+            "count-attempt": this.countAttempt ? "true" : undefined,
         });
+        return item;
     }
 }
 exports.EndAttemptInteraction = EndAttemptInteraction;

package/dist/qti/interactions/extended-text-interaction.d.ts

@@ -1,3 +1,4 @@
+import { XMLBuilder } from "xmlbuilder2/lib/interfaces";
 import { QtiPromptInteraction, QtiPromptInteractionOptions } from "./interaction";
 export type ExtendedTextInteractionOptions = QtiPromptInteractionOptions & {
     base?: number;
@@ -24,5 +25,17 @@ export type ExtendedTextInteractionOptions = QtiPromptInteractionOptions & {
  * });
  */
 export declare class ExtendedTextInteraction extends QtiPromptInteraction {
+    static tagName: string;
+    base?: number;
+    stringIdentifier?: string;
+    expectedLength?: number;
+    patternMask?: string;
+    placeholderText?: string;
+    maxStrings?: number;
+    minStrings?: number;
+    expectedLines?: number;
+    format?: "plain" | "pre-formatted" | "xhtml";
     constructor(options: ExtendedTextInteractionOptions);
+    static fromXmlString(xml: string): ExtendedTextInteraction;
+    protected buildXmlPayload(): XMLBuilder;
 }