@openstax/ts-utils 1.34.0 → 1.35.0

package/dist/cjs/services/lrsGateway/attempt-utils.js

@@ -0,0 +1,283 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.putCompletedStatement = exports.createCompletedStatement = exports.putAttemptActivityStatement = exports.createAttemptActivityStatement = exports.putAttemptStatement = exports.createAttemptStatement = exports.createStatement = exports.loadActivityAttemptInfo = exports.loadStatementsForActivityAndFirstChildren = exports.resolveAttemptInfo = exports.mostRecentStatement = exports.oldestStatement = exports.resolveCompletedForAttempt = exports.resolveAttempts = exports.matchAttemptCompleted = exports.matchAttempt = void 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.
+ */
+const formatISODuration_1 = __importDefault(require("date-fns/formatISODuration"));
+const intervalToDuration_1 = __importDefault(require("date-fns/intervalToDuration"));
+const isAfter_1 = __importDefault(require("date-fns/isAfter"));
+const isBefore_1 = __importDefault(require("date-fns/isBefore"));
+const parseISO_1 = __importDefault(require("date-fns/parseISO"));
+var Verb;
+(function (Verb) {
+    Verb["Attempted"] = "http://adlnet.gov/expapi/verbs/attempted";
+    Verb["Completed"] = "http://adlnet.gov/expapi/verbs/completed";
+})(Verb || (Verb = {}));
+const matchAttempt = (statement) => statement.verb.id === Verb.Attempted;
+exports.matchAttempt = matchAttempt;
+const matchAttemptCompleted = (attempt) => (statement) => {
+    var _a, _b;
+    return statement.verb.id === Verb.Completed
+        && statement.context !== undefined
+        && ((_a = statement.context.statement) === null || _a === void 0 ? void 0 : _a.id) === attempt.id
+        && statement.context.registration === ((_b = attempt.context) === null || _b === void 0 ? void 0 : _b.registration);
+};
+exports.matchAttemptCompleted = matchAttemptCompleted;
+const resolveAttempts = (statements, options) => statements.filter(statement => {
+    var _a;
+    return (0, exports.matchAttempt)(statement)
+        && (!(options === null || options === void 0 ? void 0 : options.activityIRI) || statement.object.id === options.activityIRI)
+        && (!(options === null || options === void 0 ? void 0 : options.parentActivityAttempt) || ((_a = statement.context) === null || _a === void 0 ? void 0 : _a.registration) === options.parentActivityAttempt);
+});
+exports.resolveAttempts = resolveAttempts;
+const resolveCompletedForAttempt = (statements, attempt, activityIRI) => statements.find(statement => (0, exports.matchAttemptCompleted)(attempt)(statement)
+    && (!activityIRI || statement.object.id === activityIRI));
+exports.resolveCompletedForAttempt = resolveCompletedForAttempt;
+const oldestStatement = (statements) => statements.reduce((result, statement) => result && (0, isBefore_1.default)((0, parseISO_1.default)('stored' in result && result.stored ? result.stored : result.timestamp), (0, parseISO_1.default)(statement.timestamp)) ? result : statement, statements[0]);
+exports.oldestStatement = oldestStatement;
+const mostRecentStatement = (statements) => statements.reduce((result, statement) => result && (0, isAfter_1.default)((0, parseISO_1.default)('stored' in result && result.stored ? result.stored : result.timestamp), (0, parseISO_1.default)(statement.timestamp)) ? result : statement, statements[0]);
+exports.mostRecentStatement = mostRecentStatement;
+const resolveAttemptInfo = (statements, options) => {
+    // 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 = (0, exports.resolveAttempts)(statements, options);
+    /* attempts that have a completed statement */
+    const resolveAttemptsWithCompleted = (statements, attempts, activityIRI) => attempts.reduce((acc, attempt) => {
+        const completed = (0, exports.resolveCompletedForAttempt)(statements, attempt, activityIRI);
+        if (completed)
+            acc.push({ attempt, completed });
+        return acc;
+    }, []);
+    const completedPairs = resolveAttemptsWithCompleted(statements, attempts, options === null || options === void 0 ? void 0 : options.activityIRI);
+    const completedAttempts = completedPairs.map(p => p.attempt);
+    /* the last attempt sorted by timestamp */
+    const currentAttempt = (options === null || options === void 0 ? void 0 : options.currentAttempt)
+        ? attempts.find(attempt => attempt.id === options.currentAttempt)
+        : (options === null || options === void 0 ? void 0 : options.currentPreference) === 'oldest'
+            ? (0, exports.oldestStatement)(attempts)
+            : (0, exports.mostRecentStatement)(attempts);
+    /* all statements for the current attempt (doesn't include the attempt or completed statements) */
+    const currentAttemptStatements = currentAttempt ? statements.filter(statement => {
+        var _a;
+        return (!(options === null || options === void 0 ? void 0 : options.activityIRI) || statement.object.id === options.activityIRI)
+            && ((_a = statement.context) === null || _a === void 0 ? void 0 : _a.registration) === currentAttempt.id;
+    }) : [];
+    const currentAttemptCompleted = currentAttempt && (0, exports.resolveCompletedForAttempt)(statements, currentAttempt, options === null || options === void 0 ? void 0 : options.activityIRI);
+    const mostRecentPair = completedPairs.reduce((cur, pair) => {
+        if (!cur)
+            return pair;
+        return (0, isAfter_1.default)((0, parseISO_1.default)(cur.attempt.timestamp), (0, parseISO_1.default)(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) => {
+        var _a;
+        return p.completed.result !== undefined &&
+            typeof ((_a = p.completed.result.score) === null || _a === void 0 ? void 0 : _a.scaled) === 'number';
+    };
+    // Filter to only scored pairs with scaled.
+    const scoredPairs = completedPairs.filter(hasScaledScore);
+    const bestPair = scoredPairs.reduce((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 === null || bestPair === void 0 ? void 0 : bestPair.attempt,
+        bestCompletedAttemptCompleted: bestPair === null || bestPair === void 0 ? void 0 : bestPair.completed,
+        completedAttempts: completedAttempts.length,
+        currentAttempt,
+        currentAttemptCompleted,
+        currentAttemptStatements,
+        mostRecentAttemptWithCompleted: mostRecentPair === null || mostRecentPair === void 0 ? void 0 : mostRecentPair.attempt,
+        mostRecentAttemptWithCompletedCompleted: mostRecentPair === null || mostRecentPair === void 0 ? void 0 : mostRecentPair.completed,
+    };
+};
+exports.resolveAttemptInfo = resolveAttemptInfo;
+/*
+ * 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.
+ */
+const loadStatementsForActivityAndFirstChildren = (gateway, activityIRI, options) => {
+    const { attempt, ...partialOptions } = options ? options : { attempt: undefined };
+    const getOptions = attempt ? { registration: attempt, ...partialOptions } : partialOptions;
+    return gateway.getAllXapiStatements({
+        activity: activityIRI,
+        related_activities: true,
+        ...getOptions,
+    });
+};
+exports.loadStatementsForActivityAndFirstChildren = loadStatementsForActivityAndFirstChildren;
+const loadActivityAttemptInfo = async (gateway, activityIRI, options) => {
+    const { parentActivityAttempt, ...partialOptions } = options ? options : { parentActivityAttempt: undefined };
+    const loadOptions = parentActivityAttempt ? { ...partialOptions, registration: parentActivityAttempt } : partialOptions;
+    return (0, exports.resolveAttemptInfo)(await gateway.getAllXapiStatements({ ...loadOptions, activity: activityIRI }), { ...options, activityIRI });
+};
+exports.loadActivityAttemptInfo = loadActivityAttemptInfo;
+const createStatement = (verb, activity, attempt, parentActivityIRI) => {
+    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,
+    };
+};
+exports.createStatement = createStatement;
+/*
+ * 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)
+ */
+const createAttemptStatement = (activity, parentActivity) => {
+    return {
+        ...((parentActivity === null || parentActivity === void 0 ? void 0 : parentActivity.iri) || (parentActivity === null || parentActivity === void 0 ? void 0 : 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,
+        },
+    };
+};
+exports.createAttemptStatement = createAttemptStatement;
+/* resolves with the statement id */
+const putAttemptStatement = async (gateway, activity, parentActivity) => {
+    return (await gateway.putXapiStatements([(0, exports.createAttemptStatement)(activity, parentActivity)]))[0];
+};
+exports.putAttemptStatement = putAttemptStatement;
+/*
+ * creates a statement under the given attempt.
+ *
+ * `result` optional context for the attempt result (score, selected answer, etc)
+ */
+const createAttemptActivityStatement = (attemptStatement, verb, result) => {
+    var _a;
+    return {
+        context: {
+            ...(((_a = attemptStatement.context) === null || _a === void 0 ? void 0 : _a.contextActivities) ? {
+                contextActivities: attemptStatement.context.contextActivities,
+            } : {}),
+            registration: attemptStatement.id,
+        },
+        object: attemptStatement.object,
+        verb: verb,
+        ...(result ? { result } : {}),
+    };
+};
+exports.createAttemptActivityStatement = createAttemptActivityStatement;
+const putAttemptActivityStatement = async (gateway, attemptStatement, verb, result) => {
+    return (await gateway.putXapiStatements([(0, exports.createAttemptActivityStatement)(attemptStatement, verb, result)]))[0];
+};
+exports.putAttemptActivityStatement = putAttemptActivityStatement;
+/*
+ * creates a statement that completes the given attempt.
+ *
+ * `result` optional context for the attempt result (score, selected answer, etc)
+ */
+const createCompletedStatement = (attemptStatement, result) => {
+    var _a, _b;
+    return {
+        context: {
+            ...(((_a = attemptStatement.context) === null || _a === void 0 ? void 0 : _a.contextActivities) ? {
+                contextActivities: attemptStatement.context.contextActivities,
+            } : {}),
+            ...(((_b = attemptStatement.context) === null || _b === void 0 ? void 0 : _b.registration) ? {
+                registration: attemptStatement.context.registration,
+            } : {}),
+            statement: {
+                objectType: 'StatementRef',
+                id: attemptStatement.id,
+            }
+        },
+        object: attemptStatement.object,
+        verb: {
+            display: { 'en-US': 'Completed' },
+            id: Verb.Completed,
+        },
+        result: {
+            duration: (0, formatISODuration_1.default)((0, intervalToDuration_1.default)({
+                start: (0, parseISO_1.default)(attemptStatement.timestamp), end: new Date()
+            })),
+            ...result,
+        }
+    };
+};
+exports.createCompletedStatement = createCompletedStatement;
+const putCompletedStatement = async (gateway, attemptStatement, result) => {
+    return (await gateway.putXapiStatements([(0, exports.createCompletedStatement)(attemptStatement, result)]))[0];
+};
+exports.putCompletedStatement = putCompletedStatement;

package/dist/cjs/services/lrsGateway/file-system.d.ts

@@ -0,0 +1,15 @@
+import { ConfigProviderForConfig } from '../../config';
+import { AuthProvider } from '../authProvider';
+import { LrsGateway } from '.';
+type Config = {
+    name: string;
+};
+interface Initializer<C> {
+    dataDir: string;
+    fs?: Pick<typeof import('fs'), 'readFile' | 'writeFile'>;
+    configSpace?: C;
+}
+export declare const fileSystemLrsGateway: <C extends string = "fileSystem">(initializer: Initializer<C>) => (configProvider: { [_key in C]: ConfigProviderForConfig<Config>; }) => ({ authProvider }: {
+    authProvider: AuthProvider;
+}) => LrsGateway;
+export {};

package/dist/cjs/services/lrsGateway/file-system.js

@@ -0,0 +1,150 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileSystemLrsGateway = void 0;
+const fsModule = __importStar(require("fs"));
+const path_1 = __importDefault(require("path"));
+const formatISO_1 = __importDefault(require("date-fns/formatISO"));
+const uuid_1 = require("uuid");
+const assertions_1 = require("../../assertions");
+const config_1 = require("../../config");
+const errors_1 = require("../../errors");
+const guards_1 = require("../../guards");
+const pageSize = 5;
+const fileSystemLrsGateway = (initializer) => (configProvider) => ({ authProvider }) => {
+    const name = (0, config_1.resolveConfigValue)(configProvider[initializer.configSpace || 'fileSystem'].name);
+    const filePath = name.then((fileName) => path_1.default.join(initializer.dataDir, fileName));
+    const { readFile, writeFile } = (0, guards_1.ifDefined)(initializer.fs, fsModule);
+    let data;
+    const load = filePath.then(path => new Promise(resolve => {
+        readFile(path, (err, readData) => {
+            if (err) {
+                console.error(err);
+            }
+            else {
+                try {
+                    data = JSON.parse(readData.toString());
+                    if (typeof data !== 'object' || !(data instanceof Array)) {
+                        data = undefined;
+                    }
+                }
+                catch (e) {
+                    console.error(e);
+                }
+            }
+            resolve();
+        });
+    }));
+    let previousSave;
+    const putXapiStatements = async (statements) => {
+        const user = (0, assertions_1.assertDefined)(await authProvider.getUser(), new errors_1.UnauthorizedError);
+        const statementsWithDefaults = statements.map(statement => ({
+            ...statement,
+            id: (0, uuid_1.v4)(),
+            actor: {
+                account: {
+                    homePage: 'https://openstax.org',
+                    name: user.uuid,
+                },
+                objectType: 'Agent',
+            },
+            timestamp: (0, formatISO_1.default)(new Date()),
+        }));
+        await load;
+        await previousSave;
+        const path = await filePath;
+        const save = previousSave = new Promise(resolve => {
+            data = data || [];
+            data.push(...statementsWithDefaults.map(statement => ({ ...statement, stored: statement.timestamp })));
+            writeFile(path, JSON.stringify(data, null, 2), () => resolve());
+        });
+        await save;
+        return statementsWithDefaults;
+    };
+    const getAllXapiStatements = async ({ user, anyUser, fetchUntil, ...options }) => {
+        const authUser = await authProvider.getUser();
+        await load;
+        let filteredData = (data || []).filter(statement => {
+            var _a, _b, _c, _d;
+            const statementDate = new Date(statement.timestamp);
+            const sinceDate = options.since ? new Date(options.since) : null;
+            const untilDate = options.until ? new Date(options.until) : null;
+            return (anyUser === true || statement.actor.account.name === (user || (0, assertions_1.assertDefined)(authUser, new errors_1.UnauthorizedError()).uuid))
+                && (!options.verb || statement.verb.id === options.verb)
+                && (!options.registration || ((_a = statement.context) === null || _a === void 0 ? void 0 : _a.registration) === options.registration)
+                && (!options.activity || (options.related_activities
+                    ? ((statement.object.id === options.activity && statement.object.objectType === 'Activity')
+                        || (!!((_d = (_c = (_b = statement.context) === null || _b === void 0 ? void 0 : _b.contextActivities) === null || _c === void 0 ? void 0 : _c.parent) === null || _d === void 0 ? void 0 : _d.find(parent => parent.id === options.activity && parent.objectType === 'Activity'))))
+                    : (statement.object.id === options.activity && statement.object.objectType === 'Activity')))
+                && (!sinceDate || statementDate >= sinceDate)
+                && (!untilDate || statementDate <= untilDate);
+        });
+        if (fetchUntil) {
+            for (let i = 0; i < filteredData.length; i += pageSize) {
+                if (fetchUntil(filteredData.slice(0, i + pageSize))) {
+                    filteredData = filteredData.slice(0, i + pageSize);
+                    break;
+                }
+            }
+        }
+        return filteredData;
+    };
+    const getMoreXapiStatements = async (more) => {
+        const { args, offset } = JSON.parse(more);
+        const allResults = await getAllXapiStatements(...args);
+        const end = offset + pageSize;
+        return {
+            more: allResults.length > end ? JSON.stringify({ args, offset: end }) : '',
+            statements: allResults.slice(offset, end)
+        };
+    };
+    const getXapiStatements = async (...args) => {
+        const allResults = await getAllXapiStatements(...args);
+        return {
+            more: allResults.length > pageSize ? JSON.stringify({ args, offset: pageSize }) : '',
+            statements: allResults.slice(0, pageSize)
+        };
+    };
+    return {
+        putXapiStatements,
+        getAllXapiStatements,
+        getXapiStatements,
+        getMoreXapiStatements,
+    };
+};
+exports.fileSystemLrsGateway = fileSystemLrsGateway;

package/dist/cjs/services/lrsGateway/index.d.ts

@@ -0,0 +1,122 @@
+import { ConfigProviderForConfig } from '../../config';
+import { GenericFetch } from '../../fetch';
+import { WithRequired } from '../../types';
+import { AuthProvider } from '../authProvider';
+import { Logger } from '../logger';
+type Config = {
+    lrsHost: string;
+    lrsAuthorization: string;
+};
+interface Initializer<C> {
+    configSpace?: C;
+    fetch: GenericFetch;
+}
+export interface XapiStatement {
+    actor: {
+        account: {
+            homePage: 'https://openstax.org';
+            name: string;
+        };
+        objectType: 'Agent';
+    };
+    id: string;
+    context?: {
+        contextActivities?: {
+            parent?: [
+                {
+                    id: string;
+                    objectType: 'Activity';
+                }
+            ];
+        };
+        statement?: {
+            objectType: 'StatementRef';
+            id: string;
+        };
+        registration?: string;
+        platform?: string;
+    };
+    object: {
+        definition?: {
+            extensions?: {
+                [key: string]: string;
+            };
+            name: {
+                [key: string]: string;
+            };
+            type: string;
+        };
+        id: string;
+        objectType: 'Activity';
+    };
+    result?: {
+        score?: {
+            scaled?: number;
+            raw?: number;
+            min?: number;
+            max?: number;
+        };
+        success?: boolean;
+        completion?: boolean;
+        response?: string;
+        duration?: string;
+        extensions?: {
+            [key: string]: string;
+        };
+    };
+    verb: {
+        display?: {
+            [key: string]: string;
+        };
+        id: string;
+    };
+    timestamp: string;
+    stored?: string;
+}
+export type SavedXapiStatement = WithRequired<XapiStatement, 'stored'>;
+export type EagerXapiStatement = Omit<XapiStatement, 'stored'>;
+export type UXapiStatement = XapiStatement | EagerXapiStatement | SavedXapiStatement;
+export type LrsGateway = ReturnType<ReturnType<ReturnType<typeof lrsGateway>>>;
+export type LrsProvider = ReturnType<ReturnType<typeof lrsGateway>>;
+export declare const lrsGateway: <C extends string = "lrs">(initializer: Initializer<C>) => (configProvider: { [_key in C]: ConfigProviderForConfig<Config>; }) => ({ authProvider, logger }: {
+    authProvider: AuthProvider;
+    logger: Logger;
+}) => {
+    putXapiStatements: (statements: Array<(Pick<XapiStatement, "object" | "verb" | "context" | "result"> & {
+        id?: string;
+    }) | UXapiStatement>) => Promise<EagerXapiStatement[]>;
+    getXapiStatements: (params: {
+        verb?: string;
+        activity?: string;
+        registration?: string;
+        related_activities?: boolean;
+        user?: string;
+        anyUser?: boolean;
+        since?: string;
+        until?: string;
+    } & {
+        ensureSync?: boolean;
+    }) => Promise<{
+        more: string;
+        statements: XapiStatement[];
+    }>;
+    getMoreXapiStatements: (more: string) => Promise<{
+        more: string;
+        statements: XapiStatement[];
+    }>;
+    getAllXapiStatements: ({ fetchUntil, ...params }: ({
+        verb?: string;
+        activity?: string;
+        registration?: string;
+        related_activities?: boolean;
+        user?: string;
+        anyUser?: boolean;
+        since?: string;
+        until?: string;
+    } & {
+        ensureSync?: boolean;
+    }) & {
+        fetchUntil?: (statements: XapiStatement[]) => boolean;
+    }) => Promise<XapiStatement[]>;
+};
+export {};