@openstax/ts-utils 1.34.0 → 1.35.0

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

@@ -1,358 +0,0 @@
-/*
- * 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];
-};