Vmeda.Online/src/core/features/courses/services/courses-helper.ts

// (C) Copyright 2015 Moodle Pty Ltd.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

import { Injectable } from '@angular/core';
import { CoreUtils } from '@services/utils/utils';
import { CoreSites, CoreSitesCommonWSOptions } from '@services/sites';
import {
    CoreCourseAnyCourseDataWithOptions,
    CoreCourses,
    CoreCourseSearchedData,
    CoreCourseUserAdminOrNavOptionIndexed,
    CoreEnrolledCourseData,
} from './courses';
import { makeSingleton, Translate } from '@singletons';
import { CoreWSExternalFile } from '@services/ws';
import { AddonCourseCompletion } from '@addons/coursecompletion/services/coursecompletion';
import moment from 'moment-timezone';
import { of } from 'rxjs';
import { firstValueFrom, zipIncludingComplete } from '@/core/utils/rxjs';
import { catchError, map } from 'rxjs/operators';
import { chainRequests, WSObservable } from '@classes/sites/authenticated-site';

// Id for a course item representing all courses (for example, for course filters).
export const ALL_COURSES_ID = -1;

/**
 * Helper to gather some common courses functions.
 */
@Injectable({ providedIn: 'root' })
export class CoreCoursesHelperProvider {

    protected courseSiteColors: Record<string, (string | undefined)[]> = {};

    /**
     * Get the courses to display the course picker popover. If a courseId is specified, it will also return its categoryId.
     *
     * @param courseId Course ID to get the category.
     * @returns Promise resolved with the list of courses and the category.
     */
    async getCoursesForPopover(courseId?: number): Promise<{courses: CoreEnrolledCourseData[]; categoryId?: number}> {
        const courses: CoreEnrolledCourseData[] = await CoreCourses.getUserCourses(false);

        // Add "All courses".
        courses.unshift({
            id: ALL_COURSES_ID,
            fullname: Translate.instant('core.fulllistofcourses'),
            shortname: Translate.instant('core.fulllistofcourses'),
            categoryid: -1,
            summary: '',
            summaryformat: 1,
        });

        let categoryId: number | undefined;
        if (courseId) {
            // Search the course to get the category.
            const course = courses.find((course) => course.id == courseId);

            if (course) {
                categoryId = course.categoryid;
            }
        }

        return {
            courses: courses,
            categoryId: categoryId,
        };
    }

    /**
     * Given a course object returned by core_enrol_get_users_courses and another one returned by core_course_get_courses_by_field,
     * load some extra data to the first one.
     *
     * @param course Course returned by core_enrol_get_users_courses.
     * @param courseByField Course returned by core_course_get_courses_by_field.
     * @param addCategoryName Whether add category name or not.
     */
    protected loadCourseExtraInfo(
        course: CoreEnrolledCourseDataWithExtraInfo,
        courseByField: CoreCourseSearchedData,
        addCategoryName: boolean = false,
    ): void {
        if (courseByField) {
            course.displayname = courseByField.displayname;
            course.categoryname = addCategoryName ? courseByField.categoryname : undefined;
            course.overviewfiles = course.overviewfiles || courseByField.overviewfiles;
        } else {
            delete course.displayname;
        }
    }

    /**
     * Loads the color of courses or the thumb image.
     *
     * @param courses List of courses.
     * @returns Promise resolved when done.
     */
    async loadCoursesColorAndImage(courses: CoreCourseSearchedData[]): Promise<void> {
        if (!courses.length) {
            return;
        }

        await Promise.all(courses.map((course) => this.loadCourseColorAndImage(course)));
    }

    /**
     * Given a list of courses returned by core_enrol_get_users_courses, load some extra data using the WebService
     * core_course_get_courses_by_field if available.
     *
     * @param courses List of courses.
     * @param loadCategoryNames Whether load category names or not.
     * @returns Promise resolved when done.
     */
    loadCoursesExtraInfo(
        courses: CoreEnrolledCourseDataWithExtraInfo[],
        loadCategoryNames: boolean = false,
    ): Promise<CoreEnrolledCourseDataWithExtraInfo[]> {
        return firstValueFrom(this.loadCoursesExtraInfoObservable(courses, loadCategoryNames));
    }

    /**
     * Given a list of courses returned by core_enrol_get_users_courses, load some extra data using the WebService
     * core_course_get_courses_by_field if available.
     *
     * @param courses List of courses.
     * @param loadCategoryNames Whether load category names or not.
     * @returns Promise resolved when done.
     */
    loadCoursesExtraInfoObservable(
        courses: CoreEnrolledCourseDataWithExtraInfo[],
        loadCategoryNames: boolean = false,
        options: CoreSitesCommonWSOptions = {},
    ): WSObservable<CoreEnrolledCourseDataWithExtraInfo[]> {
        if (!courses.length) {
            return of([]);
        }

        if (!loadCategoryNames && (courses[0].overviewfiles !== undefined || courses[0].displayname !== undefined)) {
            // No need to load more data.
            return of(courses);
        }

        const courseIds = courses.map((course) => course.id).join(',');

        // Get the extra data for the courses.
        return CoreCourses.getCoursesByFieldObservable('ids', courseIds, options).pipe(map(coursesInfosArray => {
            const coursesInfo = CoreUtils.arrayToObject(coursesInfosArray, 'id');

            courses.forEach((course) => {
                this.loadCourseExtraInfo(course, coursesInfo[course.id], loadCategoryNames);
            });

            return courses;
        }));
    }

    /**
     * Load course colors from site config.
     *
     * @returns course colors RGB.
     */
    protected async loadCourseSiteColors(): Promise<(string | undefined)[]> {
        const site = CoreSites.getRequiredCurrentSite();
        const siteId = site.getId();

        if (this.courseSiteColors[siteId] !== undefined) {
            return this.courseSiteColors[siteId];
        }

        if (!site.isVersionGreaterEqualThan('3.8')) {
            this.courseSiteColors[siteId] = [];

            return [];
        }

        const colors: (string | undefined)[] = [];

        try {
            const configs = await site.getConfig();
            for (let x = 0; x < 10; x++) {
                colors[x] = configs['core_admin_coursecolor' + (x + 1)] || undefined;
            }

            this.courseSiteColors[siteId] = colors;
        } catch {
            // Ignore errors.
        }

        return colors;
    }

    /**
     * Loads the color of the course or the thumb image.
     *
     * @param course Course data.
     */
    async loadCourseColorAndImage(course: CoreCourseWithImageAndColor): Promise<void> {
        // Moodle 4.1 downwards geopatterns are embedded in b64 in only some WS, remote them to keep it coherent.
        if (course.courseimage?.startsWith('data')) {
            course.courseimage = undefined;
        }

        if (course.courseimage !== undefined) {
            course.courseImage = course.courseimage; // @deprecated since 4.3 use courseimage instead.

            return;
        }

        if (course.overviewfiles && course.overviewfiles[0]) {
            course.courseimage = course.overviewfiles[0].fileurl;
            course.courseImage = course.courseimage; // @deprecated since 4.3 use courseimage instead.

            return;
        }

        const colors = await this.loadCourseSiteColors();

        course.colorNumber = course.id % 10;
        course.color = colors.length ? colors[course.colorNumber] : undefined;
    }

    /**
     * Get user courses with admin and nav options.
     *
     * @param sort Sort courses after get them. If sort is not defined it won't be sorted.
     * @param slice Slice results to get the X first one. If slice > 0 it will be done after sorting.
     * @param filter Filter using some field.
     * @param loadCategoryNames Whether load category names or not.
     * @param options Options.
     * @returns Courses filled with options.
     */
    getUserCoursesWithOptions(
        sort: string = 'fullname',
        slice: number = 0,
        filter?: string,
        loadCategoryNames: boolean = false,
        options: CoreSitesCommonWSOptions = {},
    ): Promise<CoreEnrolledCourseDataWithExtraInfoAndOptions[]> {
        return firstValueFrom(this.getUserCoursesWithOptionsObservable({
            sort,
            slice,
            filter,
            loadCategoryNames,
            ...options,
        }));
    }

    /**
     * Get user courses with admin and nav options.
     *
     * @param options Options.
     * @returns Courses filled with options.
     */
    getUserCoursesWithOptionsObservable(
        options: CoreCoursesGetWithOptionsOptions = {},
    ): WSObservable<CoreEnrolledCourseDataWithExtraInfoAndOptions[]> {

        return CoreCourses.getUserCoursesObservable(options).pipe(
            chainRequests(options.readingStrategy, (courses, newReadingStrategy) => {
                if (courses.length <= 0) {
                    return of([]);
                }

                const courseIds = courses.map((course) => course.id); // Use all courses to get options, to use cache.
                const newOptions = {
                    ...options,
                    readingStrategy: newReadingStrategy,
                };
                courses = this.filterAndSortCoursesWithOptions(courses, options);

                return zipIncludingComplete(
                    this.loadCoursesExtraInfoObservable(courses, options.loadCategoryNames, newOptions),
                    CoreCourses.getCoursesAdminAndNavOptionsObservable(courseIds, newOptions).pipe(map(courseOptions => {
                        courses.forEach((course: CoreEnrolledCourseDataWithOptions) => {
                            course.navOptions = courseOptions.navOptions[course.id];
                            course.admOptions = courseOptions.admOptions[course.id];
                        });
                    })),
                    ...courses.map(course => this.loadCourseCompletedStatus(course, newOptions)),
                ).pipe(map(() => courses));
            }),
        );
    }

    /**
     * Filter and sort some courses.
     *
     * @param courses Courses.
     * @param options Options
     * @returns Courses filtered and sorted.
     */
    protected filterAndSortCoursesWithOptions(
        courses: CoreEnrolledCourseData[],
        options: CoreCoursesGetWithOptionsOptions = {},
    ): CoreEnrolledCourseData[] {
        const sort = options.sort ?? 'fullname';
        const slice = options.slice ?? -1;

        switch (options.filter) {
            case 'isfavourite':
                courses = courses.filter((course) => !!course.isfavourite);
                break;
            default:
                // Filter not implemented.
        }

        switch (sort) {
            case 'fullname':
                courses.sort((a, b) => {
                    const compareA = a.fullname.toLowerCase();
                    const compareB = b.fullname.toLowerCase();

                    return compareA.localeCompare(compareB);
                });
                break;
            case 'lastaccess':
                courses.sort((a, b) => (b.lastaccess || 0) - (a.lastaccess || 0));
                break;
            // Time modified property is defined on Moodle 4.0.
            case 'timemodified':
                courses.sort((a, b) => (b.timemodified || 0) - (a.timemodified || 0));
                break;
            case 'shortname':
                courses.sort((a, b) => {
                    const compareA = a.shortname.toLowerCase();
                    const compareB = b.shortname.toLowerCase();

                    return compareA.localeCompare(compareB);
                });
                break;
            default:
            // Sort not implemented. Do not sort.
        }

        courses = slice > 0 ? courses.slice(0, slice) : courses;

        return courses;
    }

    /**
     * Given a course object, fetch and set its completed status if not present already.
     *
     * @param course Course.
     * @returns Observable.
     */
    protected loadCourseCompletedStatus(
        course: CoreEnrolledCourseDataWithExtraInfo,
        options: CoreSitesCommonWSOptions = {},
    ): WSObservable<CoreEnrolledCourseDataWithExtraInfo> {
        if (course.completed !== undefined) {
            // The WebService already returns the completed status, no need to fetch it.
            return of(course);
        }

        if (course.enablecompletion !== undefined && !course.enablecompletion) {
            // Completion is disabled for this course, there is no need to fetch the completion status.
            return of(course);
        }

        return AddonCourseCompletion.getCompletionObservable(course.id, options).pipe(
            map(completion => {
                course.completed = completion.completed;

                return course;
            }),
            catchError(() => {
                // Ignore error, maybe course completion is disabled or user has no permission.
                course.completed = false;

                return of(course);
            }),
        );
    }

    /**
     * Calculates if course date is past.
     *
     * @param course Course Object.
     * @param gradePeriodAfter Classify past courses as in progress for these many days after the course end date.
     * @returns Wether the course is past.
     */
    isPastCourse(course: CoreEnrolledCourseDataWithOptions, gradePeriodAfter = 0): boolean {
        if (course.completed) {
            return true;
        }

        if (!course.enddate) {
            return false;
        }

        // Calculate the end date to use for display classification purposes, incorporating the grace period, if any.
        const endDate = moment(course.enddate * 1000).add(gradePeriodAfter, 'days').valueOf();

        return endDate < Date.now();
    }

    /**
     * Calculates if course date is future.
     *
     * @param course Course Object.
     * @param gradePeriodAfter Classify past courses as in progress for these many days after the course end date.
     * @param gradePeriodBefore Classify future courses as in progress for these many days prior to the course start date.
     * @returns Wether the course is future.
     */
    isFutureCourse(
        course: CoreEnrolledCourseDataWithOptions,
        gradePeriodAfter = 0,
        gradePeriodBefore = 0,
    ): boolean {
        if (this.isPastCourse(course, gradePeriodAfter) || !course.startdate) {
            return false;
        }

        // Calculate the start date to use for display classification purposes, incorporating the grace period, if any.
        const startDate = moment(course.startdate * 1000).subtract(gradePeriodBefore, 'days').valueOf();

        return startDate > Date.now();
    }

    /**
     * Retrieves my courses page module.
     *
     * @returns My courses page module.
     */
    async getMyRouteModule(): Promise<unknown> {
        return import('../courses-my-lazy.module').then(m => m.CoreCoursesMyLazyModule);
    }

}

export const CoreCoursesHelper = makeSingleton(CoreCoursesHelperProvider);

/**
 * Course with colors info and course image.
 */
export type CoreCourseWithImageAndColor = {
    id: number; // Course id.
    overviewfiles?: CoreWSExternalFile[];
    colorNumber?: number; // Color index number.
    color?: string; // Color RGB.
    courseImage?: string; // Course thumbnail. @deprecated since 4.3, use courseimage instead.
    courseimage?: string; // Course thumbnail.
};

/**
 * Enrolled course data with extra rendering info.
 */
export type CoreEnrolledCourseDataWithExtraInfo = CoreCourseWithImageAndColor & CoreEnrolledCourseData & {
    categoryname?: string; // Category name,
};

/**
 * Enrolled course data with admin and navigation option availability.
 */
export type CoreEnrolledCourseDataWithOptions = CoreEnrolledCourseData & {
    navOptions?: CoreCourseUserAdminOrNavOptionIndexed;
    admOptions?: CoreCourseUserAdminOrNavOptionIndexed;
};

/**
 * Course summary data with admin and navigation option availability.
 */
export type CoreCourseSearchedDataWithOptions = CoreCourseSearchedData & {
    navOptions?: CoreCourseUserAdminOrNavOptionIndexed;
    admOptions?: CoreCourseUserAdminOrNavOptionIndexed;
};

/**
 * Enrolled course data with admin and navigation option availability and extra rendering info.
 */
export type CoreEnrolledCourseDataWithExtraInfoAndOptions = CoreEnrolledCourseDataWithExtraInfo & CoreEnrolledCourseDataWithOptions;

/**
 * Searched course data with admin and navigation option availability and extra rendering info.
 */
export type CoreCourseSearchedDataWithExtraInfoAndOptions = CoreCourseWithImageAndColor & CoreCourseSearchedDataWithOptions;

/**
 * Any course data with admin and navigation option availability and extra rendering info.
 */
export type CoreCourseAnyCourseDataWithExtraInfoAndOptions = CoreCourseWithImageAndColor & CoreCourseAnyCourseDataWithOptions & {
    categoryname?: string; // Category name,
};

/**
 * Options for getUserCoursesWithOptionsObservable.
 */
export type CoreCoursesGetWithOptionsOptions = CoreSitesCommonWSOptions & {
    sort?: string; // Sort courses after get them. Defaults to 'fullname'.
    slice?: number; // Slice results to get the X first one. If slice > 0 it will be done after sorting.
    filter?: string; // Filter using some field.
    loadCategoryNames?: boolean; // Whether load category names or not.
};