@openstax/ts-utils 1.33.1 → 1.34.0

package/packages/utils/src/services/lrsGateway/attempt-utils.ts

@@ -0,0 +1,358 @@
+/*
+ * the structure of xapi statements for handling multiple attempts of an activity
+ * including the option of a parent activity/attempt such that a new attempt
+ * of a parent activity inherently creates a new attempt scope for sub-activities
+ * is done by convention using certain context and verb pieces of a statement.
+ * this module provides helpers for creating and retrieving statements according
+ * to this convention.
+ */
+import formatISODuration from 'date-fns/formatISODuration';
+import intervalToDuration from 'date-fns/intervalToDuration';
+import isAfter from 'date-fns/isAfter';
+import isBefore from 'date-fns/isBefore';
+import parseISO from 'date-fns/parseISO';
+import { LrsGateway, UXapiStatement } from '.';
+
+enum Verb {
+  Attempted='http://adlnet.gov/expapi/verbs/attempted',
+  Completed='http://adlnet.gov/expapi/verbs/completed',
+}
+
+export type ActivityState = {
+  attempts: number;
+  bestCompletedAttempt?: UXapiStatement;
+  bestCompletedAttemptCompleted?: UXapiStatement;
+  completedAttempts: number;
+  currentAttempt?: UXapiStatement;
+  currentAttemptCompleted?: UXapiStatement;
+  currentAttemptStatements: UXapiStatement[];
+  mostRecentAttemptWithCompleted?: UXapiStatement;
+  mostRecentAttemptWithCompletedCompleted?: UXapiStatement;
+};
+
+type AttemptWithCompleted = { attempt: UXapiStatement; completed: UXapiStatement };
+type ScoredAttemptWithCompleted = AttemptWithCompleted & {
+  completed: UXapiStatement & { result: { score: { scaled: number } } };
+};
+
+export const matchAttempt = (statement: UXapiStatement) =>
+  statement.verb.id === Verb.Attempted;
+export const matchAttemptCompleted = (attempt: UXapiStatement) => (statement: UXapiStatement) =>
+  statement.verb.id === Verb.Completed
+  && statement.context !== undefined
+  && statement.context.statement?.id === attempt.id
+  && statement.context.registration === attempt.context?.registration;
+
+export const resolveAttempts = (
+  statements: UXapiStatement[], options?: { activityIRI?: string; parentActivityAttempt?: string }
+) =>
+  statements.filter(statement =>
+    matchAttempt(statement)
+    && (!options?.activityIRI || statement.object.id === options.activityIRI)
+    && (!options?.parentActivityAttempt || statement.context?.registration === options.parentActivityAttempt)
+  )
+;
+
+export const resolveCompletedForAttempt = (statements: UXapiStatement[], attempt: UXapiStatement, activityIRI?: string) =>
+  statements.find(statement =>
+    matchAttemptCompleted(attempt)(statement)
+    && (!activityIRI || statement.object.id === activityIRI)
+  )
+;
+
+export const oldestStatement = (statements: UXapiStatement[]) => statements.reduce((result, statement) =>
+  result && isBefore(parseISO('stored' in result && result.stored ? result.stored : result.timestamp), parseISO(statement.timestamp)) ? result : statement
+, statements[0] as UXapiStatement | undefined);
+
+export const mostRecentStatement = (statements: UXapiStatement[]) => statements.reduce((result, statement) =>
+  result && isAfter(parseISO('stored' in result && result.stored ? result.stored : result.timestamp), parseISO(statement.timestamp)) ? result : statement
+, statements[0] as UXapiStatement | undefined);
+
+export const resolveAttemptInfo = (
+  statements: UXapiStatement[],
+  options?: {
+    activityIRI?: string;
+    currentAttempt?: string;
+    parentActivityAttempt?: string;
+    currentPreference?: 'latest' | 'oldest';
+  }
+): ActivityState => {
+  // TODO optimize. i'm 100% that this could all be done in one iteration but i'm not messing around with that for now.
+
+  const attempts = resolveAttempts(statements, options);
+
+  /* attempts that have a completed statement */
+  const resolveAttemptsWithCompleted = (
+    statements: UXapiStatement[],
+    attempts: UXapiStatement[],
+    activityIRI?: string
+  ): AttemptWithCompleted[] =>
+    attempts.reduce<AttemptWithCompleted[]>((acc, attempt) => {
+      const completed = resolveCompletedForAttempt(statements, attempt, activityIRI);
+      if (completed) acc.push({ attempt, completed });
+      return acc;
+    }, []);
+  const completedPairs = resolveAttemptsWithCompleted(statements, attempts, options?.activityIRI);
+  const completedAttempts = completedPairs.map(p => p.attempt);
+
+  /* the last attempt sorted by timestamp */
+  const currentAttempt = options?.currentAttempt
+    ? attempts.find(attempt => attempt.id === options.currentAttempt)
+    : options?.currentPreference === 'oldest'
+      ? oldestStatement(attempts)
+      : mostRecentStatement(attempts)
+  ;
+
+  /* all statements for the current attempt (doesn't include the attempt or completed statements) */
+  const currentAttemptStatements = currentAttempt ? statements.filter(statement =>
+    (!options?.activityIRI || statement.object.id === options.activityIRI)
+    && statement.context?.registration === currentAttempt.id
+  ) : [];
+
+  const currentAttemptCompleted = currentAttempt && resolveCompletedForAttempt(statements, currentAttempt, options?.activityIRI);
+
+  const mostRecentPair = completedPairs.reduce<AttemptWithCompleted | undefined>((cur, pair) => {
+    if (!cur) return pair;
+    return isAfter(parseISO(cur.attempt.timestamp), parseISO(pair.attempt.timestamp)) ? cur : pair;
+  }, undefined);
+
+  /*
+   * the structure allows for the possibility of multiple incomplete attempts.
+   * the implementation can choose at its discretion to ignore the currentAttempt
+   * and instead make a new one, for instance if the implementation desires
+   * an attempt timeout feature
+   */
+
+
+  const hasScaledScore = (p: AttemptWithCompleted): p is ScoredAttemptWithCompleted =>
+    p.completed.result !== undefined &&
+    typeof p.completed.result.score?.scaled === 'number';
+
+  // Filter to only scored pairs with scaled.
+  const scoredPairs = completedPairs.filter(hasScaledScore);
+
+  const bestPair = scoredPairs.reduce<ScoredAttemptWithCompleted | undefined>(
+    (best, pair) => {
+      if (!best) return pair;
+      return pair.completed.result.score.scaled > best.completed.result.score.scaled
+        ? pair
+        : best;
+    },
+    undefined
+  );
+
+
+  return {
+    attempts: attempts.length,
+    bestCompletedAttempt: bestPair?.attempt,
+    bestCompletedAttemptCompleted: bestPair?.completed,
+    completedAttempts: completedAttempts.length,
+    currentAttempt,
+    currentAttemptCompleted,
+    currentAttemptStatements,
+    mostRecentAttemptWithCompleted: mostRecentPair?.attempt,
+    mostRecentAttemptWithCompletedCompleted: mostRecentPair?.completed,
+  };
+};
+
+/*
+ * loads all statements (for this actor) that have the given activityIRI as the object.id or the context.contextActivities.parent.id
+ *
+ * note: if you filter on attempt you're only gonna get the `Attempted` statements from the child activities, subsequent child activity
+ * statements would then have to be fetched using
+ * `gateway.getAllXapiStatements({ activity: childActivityIRI, registration: childAttemptStatementID })`.
+ * this is because child activities could have multiple attempts under one attempt on the parent activity.
+ */
+export const loadStatementsForActivityAndFirstChildren = (gateway: LrsGateway, activityIRI: string, options?: {
+  anyUser?: boolean; attempt?: string; ensureSync?: boolean; user?: string;
+}) => {
+  const { attempt, ...partialOptions } = options ? options : { attempt: undefined };
+  const getOptions = attempt ? { registration: attempt, ...partialOptions } : partialOptions;
+
+  return gateway.getAllXapiStatements({
+    activity: activityIRI,
+    related_activities: true,
+    ...getOptions,
+  });
+};
+
+export const loadActivityAttemptInfo = async(gateway: LrsGateway, activityIRI: string, options?: {currentAttempt?: string; parentActivityAttempt?: string; ensureSync?: boolean}) => {
+  const { parentActivityAttempt, ...partialOptions } = options ? options : { parentActivityAttempt: undefined };
+  const loadOptions = parentActivityAttempt ? { ...partialOptions, registration: parentActivityAttempt } : partialOptions;
+
+  return resolveAttemptInfo(await gateway.getAllXapiStatements({ ...loadOptions, activity: activityIRI }), { ...options, activityIRI });
+};
+
+export const createStatement = (
+  verb: UXapiStatement['verb'],
+  activity: {iri: string; type: string; name: string; extensions?: {[key: string]: string}},
+  attempt: string,
+  parentActivityIRI?: string,
+): Pick<UXapiStatement, 'object' | 'verb' | 'context'> => {
+  return {
+    context: {
+      ...(parentActivityIRI ? {
+        contextActivities: {
+          parent: [
+            {
+              id: parentActivityIRI,
+              objectType: 'Activity',
+            },
+          ],
+        },
+      } : {}),
+      registration: attempt,
+    },
+    object: {
+      definition: {
+        extensions: {
+          ...activity.extensions
+        },
+        name: {
+          'en-US': activity.name,
+        },
+        type: activity.type,
+      },
+      id: activity.iri,
+      objectType: 'Activity'
+    },
+    verb,
+  };
+};
+
+/*
+ * activity:
+ *  - iri: the IRI formatted id for this activity
+ *  - type: the IRI formatted activity type (eg: http://id.tincanapi.com/activitytype/school-assignment)
+ *  - name: the plaintext name of the activity, for reporting
+ *
+ * parentActivity:
+ *  - iri: the IRI formatted id for the parent activity
+ *  - attempt: the statement id for the parent attempt (the object of which should be the parentActivity.iri)
+ */
+export const createAttemptStatement = (
+  activity: {iri: string; type: string; name: string; extensions?: {[key: string]: string}},
+  parentActivity?: {iri?: string; attempt?: string}
+): Pick<UXapiStatement, 'object' | 'verb' | 'context'> => {
+  return {
+    ...(parentActivity?.iri || parentActivity?.attempt ? {
+      context: {
+        ...(parentActivity.iri ? {
+          contextActivities: {
+            parent: [
+              {
+                id: parentActivity.iri,
+                objectType: 'Activity',
+              },
+            ],
+          },
+        } : {}),
+        ...(parentActivity.attempt ? {
+          registration: parentActivity.attempt,
+        } : {})
+      },
+    } : {}),
+    object: {
+      definition: {
+        extensions: {
+          ...activity.extensions
+        },
+        name: {
+          'en-US': activity.name,
+        },
+        type: activity.type,
+      },
+      id: activity.iri,
+      objectType: 'Activity'
+    },
+    verb: {
+      display: { 'en-US': 'Attempted' },
+      id: Verb.Attempted,
+    },
+  };
+};
+
+/* resolves with the statement id */
+export const putAttemptStatement = async(
+  gateway: LrsGateway,
+  activity: {iri: string; type: string; name: string; extensions?: {[key: string]: string}},
+  parentActivity?: {iri?: string; attempt?: string}
+) => {
+  return (await gateway.putXapiStatements([createAttemptStatement(activity, parentActivity)]))[0];
+};
+
+/*
+ * creates a statement under the given attempt.
+ *
+ * `result` optional context for the attempt result (score, selected answer, etc)
+ */
+export const createAttemptActivityStatement = (
+  attemptStatement: UXapiStatement,
+  verb: UXapiStatement['verb'],
+  result?: UXapiStatement['result']
+): Pick<UXapiStatement, 'object' | 'verb' | 'context' | 'result'> => {
+  return {
+    context: {
+      ...(attemptStatement.context?.contextActivities ? {
+        contextActivities: attemptStatement.context.contextActivities,
+      } : {}),
+      registration: attemptStatement.id,
+    },
+    object: attemptStatement.object,
+    verb: verb,
+    ...(result ? {result} : {}),
+  };
+};
+
+export const putAttemptActivityStatement = async(
+  gateway: LrsGateway,
+  attemptStatement: UXapiStatement,
+  verb: UXapiStatement['verb'],
+  result?: UXapiStatement['result']
+) => {
+  return (await gateway.putXapiStatements([createAttemptActivityStatement(attemptStatement, verb, result)]))[0];
+};
+
+/*
+ * creates a statement that completes the given attempt.
+ *
+ * `result` optional context for the attempt result (score, selected answer, etc)
+ */
+export const createCompletedStatement = (
+  attemptStatement: UXapiStatement,
+  result?: UXapiStatement['result']
+): Pick<UXapiStatement, 'object' | 'verb' | 'context' | 'result'> => {
+  return {
+    context: {
+      ...(attemptStatement.context?.contextActivities ? {
+        contextActivities: attemptStatement.context.contextActivities,
+      } : {}),
+      ...(attemptStatement.context?.registration ? {
+        registration: attemptStatement.context.registration,
+      } : {}),
+      statement: {
+        objectType: 'StatementRef',
+        id: attemptStatement.id,
+      }
+    },
+    object: attemptStatement.object,
+    verb: {
+      display: { 'en-US': 'Completed' },
+      id: Verb.Completed,
+    },
+    result: {
+      duration: formatISODuration(intervalToDuration({
+        start: parseISO(attemptStatement.timestamp), end: new Date()
+      })),
+      ...result,
+    }
+  };
+};
+
+export const putCompletedStatement = async(
+  gateway: LrsGateway,
+  attemptStatement: UXapiStatement,
+  result: UXapiStatement['result']
+) => {
+  return (await gateway.putXapiStatements([createCompletedStatement(attemptStatement, result)]))[0];
+};