@openstax/ts-utils 1.34.0 → 1.35.0

package/dist/esm/services/lrsGateway/xapiUtils.d.ts

@@ -0,0 +1,71 @@
+import { AccountsGateway, MappedUserInfo } from '../accountsGateway';
+import { AuthProvider } from '../authProvider';
+import { ActivityState } from './attempt-utils';
+import { LrsGateway } from '.';
+export interface Grade {
+    activityProgress: 'Initialized' | 'Started' | 'inProgress' | 'Submitted' | 'Completed';
+    comment?: string;
+    gradingProgress: 'FullyGraded' | 'Pending' | 'PendingManual' | 'Failed' | 'NotReady';
+    scoreGiven: number;
+    scoreMaximum: number;
+    submission?: {
+        startedAt?: string;
+        submittedAt?: string;
+    };
+    userId?: string;
+}
+export declare const getRegistrationAttemptInfo: (lrs: LrsGateway, registration: string, options?: {
+    activity?: string;
+    anyUser?: boolean;
+    currentPreference?: "latest" | "oldest";
+    ensureSync?: boolean;
+    user?: string;
+}) => Promise<{
+    [key: string]: ActivityState;
+}>;
+export declare const getScoreGrade: (score: {
+    scaled?: number;
+    raw?: number;
+    min?: number;
+    max?: number;
+}, options: {
+    maxScore?: number;
+    startedAt?: string;
+    submittedAt?: string;
+    userId?: string;
+}) => Grade;
+export type Progress = {
+    scaled: number;
+    max?: number;
+    raw?: number;
+};
+export type GradeAndProgress = {
+    grade: Grade;
+    progress: Progress;
+    name?: string;
+};
+export type UserActivityInfo = MappedUserInfo<ActivityState>;
+export declare const getCompletedUserInfosGradeAndProgress: (infos: UserActivityInfo[], scoreMaximum?: number, gradePreference?: "current" | "best") => GradeAndProgress[];
+export declare const getCurrentGrade: (services: {
+    lrs: LrsGateway;
+    ltiAuthProvider: AuthProvider;
+}, registration: string, options?: {
+    currentPreference?: "latest" | "oldest";
+    incompleteAttemptCallback?: (info: ActivityState) => Promise<GradeAndProgress>;
+    name?: string;
+    scoreMaximum?: number;
+    userId?: string;
+    gradePreference?: "current" | "best";
+}) => Promise<GradeAndProgress | null>;
+export declare const getAssignmentGrades: (services: {
+    accountsGateway: AccountsGateway;
+    lrs: LrsGateway;
+}, assignmentIRI: string, registration: string, options?: {
+    anyUser?: boolean;
+    currentPreference?: "latest" | "oldest";
+    incompleteAttemptsCallback?: (mappedInfo: UserActivityInfo[]) => Promise<GradeAndProgress[]>;
+    platformId?: string;
+    scoreMaximum?: number;
+    user?: string;
+    gradePreference?: "current" | "best";
+}) => Promise<GradeAndProgress[]>;

package/dist/esm/services/lrsGateway/xapiUtils.js

@@ -0,0 +1,134 @@
+import partition from 'lodash/fp/partition';
+import { roundToPrecision } from '../..';
+import { resolveAttemptInfo } from './attempt-utils';
+export const getRegistrationAttemptInfo = async (lrs, registration, options) => {
+    const { currentPreference, ...xapiOptions } = options !== null && options !== void 0 ? options : {};
+    const allStatements = await lrs.getAllXapiStatements({ ...xapiOptions, registration });
+    // Partition statements for each user
+    const statementsPerUser = {};
+    allStatements.forEach((statement) => {
+        var _a;
+        // If we ever support accounts from different statement.actor.account.homePage, this method may need changes
+        // (unless we can guarantee the statement.actor.account.name are unique)
+        statementsPerUser[_a = statement.actor.account.name] || (statementsPerUser[_a] = []);
+        statementsPerUser[statement.actor.account.name].push(statement);
+    });
+    const result = {};
+    for (const [userUuid, userStatements] of Object.entries(statementsPerUser)) {
+        result[userUuid] = resolveAttemptInfo(userStatements, { currentPreference });
+    }
+    return result;
+};
+// generates a payload that can be sent to the LMS, documentation here:
+// lti: http://www.imsglobal.org/spec/lti-ags/v2p0#score-publish-service
+// ltijs: https://cvmcosta.me/ltijs/#/grading
+// Note: "min" is currently completely ignored
+export const getScoreGrade = (score, options) => {
+    const { raw, scaled, max } = score;
+    const { maxScore, startedAt, submittedAt, userId } = options;
+    const scoreMaximum = maxScore !== null && maxScore !== void 0 ? maxScore : 100;
+    const scoreGiven = raw && max
+        ? scoreMaximum / max * raw
+        : scaled
+            ? scaled * scoreMaximum
+            : 0;
+    const submission = {};
+    if (startedAt) {
+        submission.startedAt = startedAt;
+    }
+    if (submittedAt) {
+        submission.submittedAt = submittedAt;
+    }
+    return {
+        userId,
+        activityProgress: submittedAt ? 'Completed' : 'Started',
+        // canvas assumes that anything that isn't 'FullyGraded' requires manual grading and displays a "needs grading" icon.
+        // if you warp your mind you can consider the portion of the assignment which is completed to be fully graded.
+        gradingProgress: 'FullyGraded',
+        scoreMaximum,
+        scoreGiven: roundToPrecision(scoreGiven, -2),
+        submission,
+    };
+};
+// These methods assign 0's to incomplete activities
+const pickAttemptAndCompleted = (state, gradePreference) => {
+    if (gradePreference === 'best' && state.bestCompletedAttempt) {
+        return {
+            attempt: state.bestCompletedAttempt,
+            completed: state.bestCompletedAttemptCompleted,
+        };
+    }
+    // return current attempt if gradePreference is current
+    return {
+        attempt: state.currentAttempt,
+        completed: state.currentAttemptCompleted,
+    };
+};
+const getCompletedActivityStateGradeAndProgress = ({ name, scoreMaximum, state, userId, gradePreference = 'current' }) => {
+    var _a;
+    const { attempt, completed } = pickAttemptAndCompleted(state, gradePreference);
+    return {
+        grade: getScoreGrade(((_a = completed === null || completed === void 0 ? void 0 : completed.result) === null || _a === void 0 ? void 0 : _a.score) || {}, {
+            maxScore: scoreMaximum,
+            startedAt: attempt === null || attempt === void 0 ? void 0 : attempt.timestamp,
+            submittedAt: completed === null || completed === void 0 ? void 0 : completed.timestamp,
+            userId,
+        }),
+        progress: {
+            scaled: completed ? 1 : 0,
+        },
+        name,
+    };
+};
+export const getCompletedUserInfosGradeAndProgress = (infos, scoreMaximum, gradePreference) => infos.map(({ data, fullName, platformUserId }) => getCompletedActivityStateGradeAndProgress({
+    name: fullName,
+    scoreMaximum,
+    userId: platformUserId,
+    state: data,
+    gradePreference,
+}));
+export const getCurrentGrade = async (services, registration, options) => {
+    var _a;
+    const user = await services.ltiAuthProvider.getUser();
+    if (!user) {
+        return null;
+    }
+    const userId = (_a = options === null || options === void 0 ? void 0 : options.userId) !== null && _a !== void 0 ? _a : user.uuid;
+    const { currentPreference, incompleteAttemptCallback, name, scoreMaximum, gradePreference, } = options !== null && options !== void 0 ? options : {};
+    const infoPerUser = await getRegistrationAttemptInfo(services.lrs, registration, { currentPreference });
+    const userInfo = infoPerUser[user.uuid];
+    if (!userInfo) {
+        return getCompletedActivityStateGradeAndProgress({
+            name,
+            scoreMaximum,
+            state: resolveAttemptInfo([]),
+            userId,
+            gradePreference,
+        });
+    }
+    if (userInfo.currentAttemptCompleted || !incompleteAttemptCallback) {
+        return getCompletedActivityStateGradeAndProgress({
+            name,
+            scoreMaximum,
+            state: userInfo,
+            userId,
+            gradePreference,
+        });
+    }
+    return incompleteAttemptCallback(userInfo);
+};
+export const getAssignmentGrades = async (services, assignmentIRI, registration, options) => {
+    const { anyUser, currentPreference, incompleteAttemptsCallback, platformId, scoreMaximum, user, gradePreference = 'current', } = options !== null && options !== void 0 ? options : {};
+    const infoPerUserUuid = await getRegistrationAttemptInfo(services.lrs, registration, { activity: assignmentIRI, anyUser, currentPreference, user });
+    const mappedInfo = await services.accountsGateway.mapUserUuids(infoPerUserUuid, platformId);
+    // If no custom callback, just return graded results based on preference
+    if (!incompleteAttemptsCallback) {
+        return getCompletedUserInfosGradeAndProgress(mappedInfo, scoreMaximum, gradePreference);
+    }
+    // Partition based on whether the chosen preference has a completed attempt
+    const [incompleteInfo, completedInfo] = partition((info) => {
+        const { completed } = pickAttemptAndCompleted(info.data, gradePreference);
+        return completed === undefined;
+    })(mappedInfo);
+    return getCompletedUserInfosGradeAndProgress(completedInfo, scoreMaximum, gradePreference).concat(await incompleteAttemptsCallback(incompleteInfo));
+};

package/dist/esm/services/postgresConnection/index.d.ts

@@ -0,0 +1,28 @@
+import postgres, { Sql } from 'postgres';
+import { ConfigProviderForConfig } from '../../config';
+import type { Logger } from '../logger';
+type Config = {
+    host: string;
+    readHost: string;
+    port: string;
+    database: string;
+    username: string;
+    password: string;
+};
+interface Initializer<C> {
+    configSpace?: C;
+}
+export declare const postgresConnection: <C extends string = "local">(initializer: Initializer<C>) => (configProvider: { [_key in C]: ConfigProviderForConfig<Config>; }) => (services: {
+    logger: Logger;
+}) => {
+    db: () => Promise<postgres.Sql<{}>>;
+    dbRead: () => Promise<postgres.Sql<{}>>;
+    migrate: (migrations: Migration[]) => Promise<void>;
+    down: () => Promise<void[]>;
+};
+export type PostgresConnection = ReturnType<ReturnType<ReturnType<typeof postgresConnection>>>;
+export interface Migration {
+    name: string;
+    up: (db: Sql) => Promise<void>;
+}
+export {};

package/dist/esm/services/postgresConnection/index.js

@@ -0,0 +1,58 @@
+import postgres from 'postgres';
+import { assertNotNaN } from '../../assertions';
+import { resolveConfigValue } from '../../config';
+import { ifDefined } from '../../guards';
+import { once } from '../../misc/helpers';
+export const postgresConnection = (initializer) => (configProvider) => {
+    const config = configProvider[ifDefined(initializer.configSpace, 'local')];
+    const host = once(() => resolveConfigValue(config.host));
+    const readHost = once(() => resolveConfigValue(config.readHost));
+    const connectionOptions = once(async () => ({
+        port: assertNotNaN(parseInt(await resolveConfigValue(config.port), 10), new Error('port must be a number')),
+        database: await resolveConfigValue(config.database),
+        username: await resolveConfigValue(config.username),
+        password: await resolveConfigValue(config.password),
+        transform: {
+            column: { to: postgres.fromCamel, from: postgres.toCamel },
+        },
+    }));
+    const connections = [];
+    const sql = once(async () => {
+        const options = await connectionOptions();
+        const connection = postgres({ ...options, host: await host() });
+        connections.push(connection);
+        return connection;
+    });
+    const sqlRead = once(async () => {
+        const options = await connectionOptions();
+        const connection = postgres({ ...options, host: await readHost() });
+        connections.push(connection);
+        return connection;
+    });
+    return (services) => ({
+        db: sql,
+        dbRead: sqlRead,
+        migrate: async (migrations) => {
+            await migrate(services, await sql(), migrations);
+        },
+        down: () => Promise.all(connections.map(c => c.end()))
+    });
+};
+async function migrate(services, db, migrations) {
+    await db `
+    CREATE TABLE IF NOT EXISTS migrations (
+      id SERIAL PRIMARY KEY,
+      name TEXT NOT NULL,
+      ran_at TIMESTAMP NOT NULL DEFAULT NOW()
+    )
+  `;
+    const ranMigrations = await db `SELECT name FROM migrations`;
+    for (const migration of migrations) {
+        if (ranMigrations.some(({ name }) => name === migration.name)) {
+            continue;
+        }
+        services.logger.log(`Running migration ${migration.name}`);
+        await migration.up(db);
+        await db `INSERT INTO migrations (name) VALUES (${migration.name})`;
+    }
+}

package/dist/esm/services/searchProvider/index.d.ts

@@ -0,0 +1,69 @@
+export type FieldType = string | string[] | number | boolean;
+export type ESFilter = {
+    terms: Record<string, FieldType>;
+} | {
+    term: Record<string, FieldType>;
+} | {
+    exists: {
+        field: string;
+    };
+} | {
+    nested: {
+        path: string;
+        query: Filter;
+    };
+} | {
+    bool: BoolFilter;
+};
+export type Filter = {
+    key: string;
+    value: FieldType;
+} | ESFilter;
+export type BoolFilter = {
+    must?: Filter[];
+    must_not?: Filter[];
+    should?: Filter[];
+    filter?: Filter[];
+    minimum_should_match?: number;
+};
+type Field = {
+    key: string;
+    type?: 'text';
+    weight: number;
+} | {
+    key: string;
+    type: 'keyword';
+} | {
+    key: string;
+    type: 'boolean';
+};
+export interface IndexOptions<T> {
+    body: T;
+    id: string;
+    version?: number;
+    version_type?: 'external' | 'external_gte';
+}
+export type FieldMapping = {
+    type: 'keyword' | 'text' | 'boolean';
+} | {
+    type: 'date';
+    format?: string;
+} | {
+    type?: 'nested' | 'object';
+    properties: Record<string, FieldMapping>;
+};
+export type FieldMappings = Record<string, FieldMapping>;
+export interface SearchOptions {
+    page?: number;
+    query: string | undefined;
+    fields: Field[];
+    filter?: Filter[];
+    must?: Filter[];
+    must_not?: Filter[];
+    should?: Filter[];
+    sort?: {
+        key: string;
+        order: 'asc' | 'desc';
+    }[];
+}
+export {};

package/dist/esm/services/searchProvider/index.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/services/searchProvider/memorySearchTheBadWay.d.ts

@@ -0,0 +1,20 @@
+import { FieldMappings, IndexOptions, SearchOptions } from '.';
+export type Config<T> = {
+    mappings: FieldMappings;
+    store: {
+        loadAllDocumentsTheBadWay: () => Promise<T[]>;
+    };
+};
+export declare const memorySearchTheBadWay: () => <T>({ store, mappings }: Config<T>) => {
+    deleteIndexIfExists: () => Promise<undefined>;
+    ensureIndexCreated: () => Promise<undefined>;
+    index: (_options: IndexOptions<T>) => Promise<undefined>;
+    bulkIndex: (_items: IndexOptions<T>[]) => Promise<undefined>;
+    search: (options: SearchOptions) => Promise<{
+        items: T[];
+        pageSize: number;
+        currentPage: number;
+        totalItems: number;
+        totalPages: number;
+    }>;
+};

package/dist/esm/services/searchProvider/memorySearchTheBadWay.js

@@ -0,0 +1,187 @@
+import { coerceArray } from '../..';
+import { InvalidRequestError } from '../../errors';
+import { isDefined } from '../../guards';
+const MIN_MATCH = 0.5;
+const MAX_RESULTS = 10;
+var MatchType;
+(function (MatchType) {
+    MatchType[MatchType["Must"] = 0] = "Must";
+    MatchType[MatchType["MustNot"] = 1] = "MustNot";
+    MatchType[MatchType["Should"] = 2] = "Should";
+})(MatchType || (MatchType = {}));
+const resolveField = (context, field) => {
+    const path = field.startsWith(context.scope + '.')
+        ? field.slice(context.scope.length + 1)
+        : field;
+    return path.split('.').reduce((result, key) => {
+        if (result === undefined) {
+            throw new Error(`Key "${key}" not found in document resolving ${field}`);
+        }
+        return result[key];
+    }, context.document);
+};
+const getFieldDefinition = (context, field) => {
+    let current = context.fields;
+    const parts = field.split('.');
+    const head = parts.slice(0, -1);
+    const tail = parts[parts.length - 1];
+    for (const part of head) {
+        const currentDefinition = current[part];
+        if (!currentDefinition || !('properties' in currentDefinition)) {
+            throw new Error(`Field "${field}" not found in mappings`);
+        }
+        current = currentDefinition.properties;
+    }
+    if (!current[tail]) {
+        throw new Error(`Field "${field}" not found in mappings`);
+    }
+    return current[tail];
+};
+const getFieldType = (context, field) => {
+    const definition = getFieldDefinition(context, field);
+    return definition.type;
+};
+const matchNested = (context, nested) => {
+    const nestedPath = nested.path;
+    const nestedDocuments = resolveField(context, nestedPath);
+    if (!Array.isArray(nestedDocuments)) {
+        throw new InvalidRequestError(`Nested path "${nestedPath}" is not an array`);
+    }
+    return nestedDocuments.some(nestedDocument => matchClause({
+        ...context,
+        scope: nestedPath,
+        document: nestedDocument
+    }, nested.query));
+};
+const matchExists = (context, exists) => {
+    const value = resolveField(context, exists.field);
+    return value !== undefined && value !== null;
+};
+const matchTerms = (context, terms) => {
+    for (const key in terms) {
+        const docValues = coerceArray(resolveField(context, key));
+        const coerceValue = getFieldType(context, key) === 'boolean'
+            ? (input) => {
+                if ([true, 'true', '1', 1].includes(input)) {
+                    return true;
+                }
+                if ([false, 'false', '0', 0, ''].includes(input)) {
+                    return false;
+                }
+                throw new InvalidRequestError('input is not a valid boolean filter');
+            }
+            : (x) => x;
+        const hasMatch = coerceArray(terms[key]).map(coerceValue).some(v => docValues.includes(v));
+        if (!hasMatch) {
+            return false;
+        }
+    }
+    return true;
+};
+const matchClause = (context, clause) => {
+    const filter = ('key' in clause && 'value' in clause)
+        ? { terms: { [clause.key]: clause.value } }
+        : clause;
+    if ('terms' in filter)
+        return matchTerms(context, filter.terms);
+    else if ('term' in filter)
+        return matchTerms(context, filter.term);
+    else if ('exists' in filter)
+        return matchExists(context, filter.exists);
+    else if ('bool' in filter)
+        return matchBool(context, filter.bool);
+    else if ('nested' in filter)
+        return matchNested(context, filter.nested);
+    else
+        throw new InvalidRequestError('invalid filter type');
+};
+const matchFilters = (context, filters, matchType) => {
+    for (const field of filters) {
+        const hasMatch = matchClause(context, field);
+        if ((matchType === MatchType.Must && !hasMatch) || (matchType === MatchType.MustNot && hasMatch)) {
+            return false;
+        }
+        else if (matchType === MatchType.Should && hasMatch) {
+            return true;
+        }
+    }
+    return matchType !== MatchType.Should;
+};
+const matchBool = (context, filters) => {
+    const { must_not, should, must, filter } = filters;
+    if ((must === null || must === void 0 ? void 0 : must.length) && !matchFilters(context, must, MatchType.Must)) {
+        return false;
+    }
+    if ((filter === null || filter === void 0 ? void 0 : filter.length) && !matchFilters(context, filter, MatchType.Must)) {
+        return false;
+    }
+    if ((must_not === null || must_not === void 0 ? void 0 : must_not.length) && !matchFilters(context, must_not, MatchType.MustNot)) {
+        return false;
+    }
+    if ((should === null || should === void 0 ? void 0 : should.length) && !matchFilters(context, should, MatchType.Should)) {
+        return false;
+    }
+    return true;
+};
+export const memorySearchTheBadWay = () => ({ store, mappings }) => {
+    return {
+        // This method is intentionally stubbed because index deletion is not applicable for in-memory storage.
+        deleteIndexIfExists: async () => undefined,
+        ensureIndexCreated: async () => undefined,
+        index: async (_options) => undefined,
+        bulkIndex: async (_items) => undefined,
+        search: async (options) => {
+            const results = (await store.loadAllDocumentsTheBadWay())
+                .map(document => {
+                let weight = 0;
+                if (options.query !== undefined) {
+                    for (const field of options.fields) {
+                        if (field.type !== undefined && field.type !== 'text') {
+                            continue;
+                        }
+                        const value = resolveField({ document, fields: mappings, scope: '' }, field.key);
+                        if (value === undefined || value === null) {
+                            continue;
+                        }
+                        if (typeof value === 'string') {
+                            if (value.toUpperCase().indexOf(options.query.toUpperCase()) !== -1) {
+                                weight += (1 * field.weight);
+                            }
+                        }
+                        else {
+                            throw new Error(`invalid value type when searching in field ${field.key.toString()}`);
+                        }
+                    }
+                }
+                if (!matchBool({ document, fields: mappings, scope: '' }, options)) {
+                    return undefined;
+                }
+                return { document, weight };
+            })
+                .filter(isDefined)
+                .filter(r => !options.query || r.weight >= MIN_MATCH);
+            results.sort((a, b) => {
+                for (const sort of (options.sort || [])) {
+                    const aValue = resolveField({ document: a.document, fields: mappings, scope: '' }, sort.key);
+                    const bValue = resolveField({ document: b.document, fields: mappings, scope: '' }, sort.key);
+                    if (aValue < bValue) {
+                        return sort.order === 'asc' ? -1 : 1;
+                    }
+                    if (aValue > bValue) {
+                        return sort.order === 'asc' ? 1 : -1;
+                    }
+                }
+                return b.weight - a.weight;
+            });
+            const page = options.page || 1;
+            const offset = (page - 1) * MAX_RESULTS;
+            return {
+                items: results.slice(offset, offset + MAX_RESULTS).map(r => r.document),
+                pageSize: MAX_RESULTS,
+                currentPage: page,
+                totalItems: results.length,
+                totalPages: Math.ceil(results.length / MAX_RESULTS)
+            };
+        },
+    };
+};

package/dist/esm/services/searchProvider/openSearch.d.ts

@@ -0,0 +1,28 @@
+import { ConfigProviderForConfig } from '../../config';
+import { FieldMappings, IndexOptions, SearchOptions } from '.';
+export type Config = {
+    node: string;
+    region: string;
+};
+export interface Initializer<C> {
+    configSpace?: C;
+}
+export type IndexConfig = {
+    name: string;
+    mappings: FieldMappings;
+    pageSize?: number;
+};
+export declare const openSearchService: <C extends string = "deployed">(initializer?: Initializer<C>) => (configProvider: { [_key in C]: ConfigProviderForConfig<Config>; }) => <T>(indexConfig: IndexConfig) => {
+    ensureIndexCreated: () => Promise<void>;
+    deleteIndexIfExists: () => Promise<void>;
+    index: (params: IndexOptions<T>) => Promise<void>;
+    bulkIndex: (items: IndexOptions<T>[]) => Promise<void>;
+    search: (options: SearchOptions) => Promise<{
+        items: Exclude<T, undefined>[];
+        pageSize: number;
+        currentPage: number;
+        totalItems: number;
+        totalPages: number;
+    }>;
+    updateMappings: () => Promise<void>;
+};