@olea-bps/base 1.0.0

package/context/context-timetable/TimetableService.js

@@ -0,0 +1,357 @@
+import { useSyncExternalStore } from 'react';
+
+import * as SecureStore from 'expo-secure-store';
+
+import { groupBy } from 'lodash';
+import { DateTime, Duration } from 'luxon';
+
+import CollectorVersion2ApiProvider from './CollectorVersion2ApiProvider';
+
+/**
+ * @typedef TimetableProvider
+ * @property {(timetableCode: string, startDate: string, startDate: string) => Course[]} getByCode Ruft zu einem Stundenplancode die entsprechenden Vorlesungen in einem bestimmten Zeitraum ab
+ */
+
+/**
+ * @typedef CourseDataField
+ * @property {string} data
+ * @property {string} displayname
+ */
+
+/**
+ * @typedef CourseDataField
+ * @property {string} data
+ * @property {string} displayname
+ */
+
+/**
+ * @typedef CourseTime
+ * @property {number} dayOfWeek
+ * @property {string} date ISO Datum
+ * @property {string} start ISO Uhrzeit
+ * @property {string} end ISO Uhrzeit
+ * @property {string} displayname
+ * @property {string} weekmode
+ * @property {string} mode
+ */
+
+/**
+ * @typedef Course
+ * @property {CourseDataField} title
+ * @property {CourseDataField} room
+ * @property {CourseDataField} type
+ * @property {CourseDataField[]} lecturer
+ * @property {CourseTime[]} times
+ */
+
+const TimetableCodeStoreKey = 'timetable.code';
+const TimetableCoursesStoreKey = 'timetable.courses';
+
+export class ApiProviderNotInitializedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+
+export class TimetableCodeNotInitializedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+
+/**
+ * Eine Serviceklasse, die Zugriff auf die Daten des Stundenplan-Moduls ermöglicht.
+ *
+ * Der Stundenplan-Service ist Klasse für die Datenverwaltung der für das Stundenplan-Modul benötigten Daten.
+ * Dieser ist außerhalb des React-Kontextes angesiedelt, damit auf die Daten zugegriffen werden kann, wenn kein React-Kontext verfügbar ist.
+ * Alle Daten werden in lokalen Speichern zwischengespeichert, um beim ersten Zugriff veraltet Daten anzeigen zu können.
+ *
+ * Der Service sollte über {@linkcode TimetableService.fromProviderSettingsObject} initialisert werden.
+ */
+export default class TimetableService {
+
+    /**
+     * @type {TimetableProvider}
+     */
+    #provider;
+
+    /**
+     * Konstruktor des Stundenplan-Services.
+     * Es muss ein Provider Übergeben werden, damit der Stundenplan-Service Daten über den Provider abrufen kann.
+     * Es wird empfohlen {@linkcode TimetableService.fromProviderSettingsObject} zu verwenden.
+     *
+     * @param {TimetableProvider} provider Provider, welcher für den Datenabruf zuständig ist
+     * @example
+     * const language = 'de';
+     * const providerSettings {
+     *     name: 'normal-provider',
+     *     url: 'https://provider.com/api/v1/'
+     * };
+     *
+     * const timetableService = TimetableService.fromProviderSettingsObject(providerSettings, language);
+     */
+    constructor(provider) {
+        this.#provider = provider;
+
+        this.#code = SecureStore.getItem(TimetableCodeStoreKey);
+        this.#courses = JSON.parse(SecureStore.getItem(TimetableCoursesStoreKey));
+    }
+
+
+
+    #code = undefined;
+    #codeSubscribers = new Set();
+
+    code() {
+        return this.#code;
+    }
+    codeCallback = () => this.code();
+
+    #setCode(code) {
+        this.#code = code;
+        this.#codeSubscribers.forEach(subscriber => subscriber(code));
+    }
+    async setCode(code) {
+        await SecureStore.setItemAsync(TimetableCodeStoreKey, code);
+        this.#setCode(code);
+    }
+    setCodeCallback = async (code) => this.setCode(code);
+
+    async deleteCode() {
+
+        await Promise.all([
+            SecureStore.deleteItemAsync(TimetableCodeStoreKey),
+            SecureStore.deleteItemAsync(TimetableCoursesStoreKey),
+        ]);
+
+        this.#setCode(null);
+        this.#setCourses(null);
+    }
+    deleteCodeCallback = () => this.deleteCode();
+
+    codeSubscribe(subscriber) {
+        this.#codeSubscribers.add(subscriber);
+
+        return () => this.codeUnsubscribe(subscriber);
+    }
+    codeSubscribeCallback = (subscriber) => this.codeSubscribe(subscriber);
+
+    codeUnsubscribe(subscriber) {
+        return this.#codeSubscribers.delete(subscriber);
+    }
+
+
+
+    /**
+     * @type {Object.<string, Course[]>}
+     */
+    #courses = undefined;
+    #coursesSubscribers = new Set();
+
+    /**
+     * Liefert die Vorlesungen, die von dem Service respeichert werden zurück.
+     * Dabei werden die Vorlesungen nach Vorlesungstagen gruppiert.
+     * Somit wird ein Object zurückgegeben, bei dem die Schlüssel ISO-Datums der Vorlesungstage sind und die Werte sind Listen mit Vorlesungen
+     *
+     * @returns {Object.<string, Course[]>} Vorlesungen gruppiert nach Vorlesungstagen
+     */
+    courses() {
+        return this.#courses;
+    }
+
+    #setCourses(courses) {
+        // Neue Vorlesungsdaten im Service hinterlegen
+        this.#courses = courses;
+
+        // Jedem Subscriber werden die neuen Vorlesungstage bekannt gemacht
+        this.#coursesSubscribers.forEach(subscriber => subscriber(this.#courses));
+    }
+
+    coursesCallback = () => this.courses();
+
+    async refreshCourses(startDate, endDate) {
+
+        if (this.#provider === null) {
+            throw new ApiProviderNotInitializedError('Api Provider is not initilized');
+        }
+
+        if (this.#code === null) {
+            throw new TimetableCodeNotInitializedError('Timetable code is not initilized');
+        }
+
+        const courses = await this.#provider.getByCode(this.#code, startDate, endDate);
+        const transformedCourses = courses.map(
+            course => {
+                // Erstes Time-Element aus dem times-Array nehmen, da im neuen Format nur noch eine Zeit enthalten ist
+                const courseTime = course?.times?.[0];
+                if (courseTime) {
+                    const courseDate = DateTime.fromISO(courseTime?.date);
+                    // Startzeit und Endzeit der Vorlesung in ein DateTime umwandeln
+                    const courseStartTime = Duration.fromISOTime(courseTime.start);
+                    const courseStartDateTime = courseDate.plus(courseStartTime);
+                    const courseEndTime = Duration.fromISOTime(courseTime.end);
+                    const courseEndDateTime = courseDate.plus(courseEndTime);
+
+                    return {
+                        ...course,
+                        startDateTime: courseStartDateTime.toISO(),
+                        endDateTime: courseEndDateTime.toISO(),
+                    }
+                } else {
+                    return course;
+                }
+            }
+        )
+
+        // Gruppieren der vom Provider abgeholten Vorlesungen
+        // Es wird nach dem Datum der Vorlesungen gruppiert
+        // Vorlesungen, die keinem Tag zugeordnet werden können, werden untder dem Schlüssel `undefined` zusammengefasst
+        const addingCourses = groupBy(
+            transformedCourses,
+            course => {
+                // Datum der Vorlesung aus der Vorlesung holen
+                const courseDate = course?.times?.[0]?.date;
+
+                // Prüfen ob die Vorlesung einen Wert als Datum vorweist
+                return courseDate
+                    // Ist ein Wert vorhanden, wird dieser für die Gruppierung verwendet
+                    ? courseDate
+                    // Ansonsten wird undefined zurückgeben (lerrer String, null, undefined, ...)
+                    : undefined;
+            }
+        );
+
+        //Entfernen der Vorlesungstage zwischen Startdatum und Enddatum
+        const rangeRemovedCourses = Object.fromEntries(
+            Object.entries(this.#courses ?? {})
+                .filter(([coursesDate,]) => startDate >= coursesDate && coursesDate <= endDate)
+        );
+
+        // Zusammenführen der neuen Vorlesungstagen der Vorlesungen des Providers und der schon vorhandenen Vorlesungstagen
+        const newCourses = {
+            ...rangeRemovedCourses,
+            ...addingCourses,
+        };
+
+        // Neue Vorlesungsdaten in den Cache ablegen
+        SecureStore.setItem(TimetableCoursesStoreKey, JSON.stringify(newCourses));
+
+        // Neue Vorlesungen hin Service hinterlegen und Äanderun bekannt geben
+        this.#setCourses(newCourses);
+    }
+    refreshCoursesCallback = (startDate, endDate) => this.refreshCourses(startDate, endDate);
+
+    coursesSubscribe(subscriber) {
+        this.#coursesSubscribers.add(subscriber);
+
+        return () => this.coursesUnsubscribe(subscriber);
+    }
+    coursesSubscribeCallback = (subscriber) => this.coursesSubscribe(subscriber);
+
+    coursesUnsubscribe(subscriber) {
+        return this.#coursesSubscribers.delete(subscriber);
+    }
+
+
+
+    /**
+     * Erstellen eines Stundenplanservices mit Hilfe der Provider-Einstellungen und Sprache
+     *
+     * @param {ProviderSetting} providerSettingsObject
+     * @param {string} language
+     * @returns
+     */
+    static fromProviderSettingsObject(providerSettingsObject, language) {
+        const provider = TimetableService.#createProvider(providerSettingsObject, language);
+
+        return new TimetableService(provider);
+    }
+
+    /**
+     * Erstellen des Providers mit Hilfe eines Provider-Einstellungen-Objektes und einer Sprache
+     *
+     * @param {ProviderSetting} providerSettingsObject Einstellungen welche zum auswählen und Initialisieren des Provider verwendet werden
+     * @param {string} language Sprachcode welcher für den Datenabruf verwendet werden soll
+     */
+    static #createProvider(providerSettingsObject, language) {
+        const { provider } = providerSettingsObject;
+
+        switch (provider) {
+            case CollectorVersion2ApiProvider.name:
+                return CollectorVersion2ApiProvider.fromSettingsObject(providerSettingsObject, language);
+            default:
+                return null;
+        }
+    }
+}
+
+/**
+ * Ein React-Hook, um den Stundenplancode des Stundenplan-Services in den React-Kontext einzubinden.
+ *
+ * @param {TimetableService} timetableService Der Stundenplan-Service welche den Stundenplancode bereitstellen soll
+ * @returns {[string|null, (code: string) => Promise<void>, () => void]}
+ * @example
+ * const timetableService = TimetableService.fromProviderSettingsObject(
+ *     {
+ *         provider: 'hs-collector-v2',
+ *         url: 'https://hsc-production.hrz.tu-chemnitz.de/hs_collector/api/v1/',
+ *     },
+ *     'de',
+ * );
+ *
+ * const [timetableCode, saveTimetableCode, deleteTimetableCode] = useSyncTimetableCode(timetableService);
+ *
+ * saveTimetableCode('testcode');
+ *
+ * return (
+ *     <Text>
+ *         {timetableCode}
+ *     </Text>
+ * );
+ */
+export function useSyncTimetableCode(timetableService) {
+    const timetableCode = useSyncExternalStore(
+        timetableService.codeSubscribeCallback,
+        timetableService.codeCallback,
+    );
+
+    return [timetableCode, timetableService.setCodeCallback, timetableService.deleteCodeCallback];
+}
+
+/**
+ * React-Hook, welcher die Vorlesungen nach Vorlesungtagen gruppoert für React zur verfügung stellt.
+ * Zusätzlich wird eine Funktion zurückgegeben, welche für die Aktualisierung der Daten in einem bestimmten Zeitraum verwendet werden kann.
+ *
+ * @param {TimetableService} timetableService
+ * @returns {[Object.<string, Course[]>, (startDate: string, endDate: string)=> Promise<void>]}
+ * @example
+ * const timetableService = TimetableService.fromProviderSettingsObject(
+ *     {
+ *         provider: 'hs-collector-v2',
+ *         url: 'https://hsc-production.hrz.tu-chemnitz.de/hs_collector/api/v1/',
+ *     },
+ *     'de',
+ * );
+ *
+ * const [courses, refreshCourses] = useSyncCourses(timetableService);
+ *
+ * useEffect(
+ *     () => {
+ *         refreshCourses('2025-01-01', '2026-01-01');
+ *     },
+ *     []
+ * );
+ *
+ * return (
+ * );
+ */
+export function useSyncCourses(timetableService) {
+    const courses = useSyncExternalStore(
+        timetableService.coursesSubscribeCallback,
+        timetableService.coursesCallback,
+    );
+
+    return [courses, timetableService.refreshCoursesCallback];
+}

package/context/context-timetable/index.js

@@ -0,0 +1,215 @@
+/**
+ * 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 { createContext, useEffect, useContext, useMemo } from 'react'
+
+import { useSelector } from 'react-redux';
+import { useTheme } from 'react-native-paper';
+
+import { DateTime, Duration } from 'luxon';
+
+import { TimetableNotFoundError } from './ProviderErrors';
+import TimetableService, {
+    ApiProviderNotInitializedError,
+    TimetableCodeNotInitializedError,
+    useSyncCourses,
+    useSyncTimetableCode
+} from './TimetableService';
+
+const CourseWeekModeWeekly = 'weekly';
+const CourseWeekModeOdd = 'odd';
+const CourseWeekModeEven = 'even';
+
+const CourseWeekModes = {
+    weekly: CourseWeekModeWeekly,
+    odd: CourseWeekModeOdd,
+    even: CourseWeekModeEven,
+}
+
+const TimetableContext = createContext({
+    code: null,
+    courses: {},
+});
+
+/**
+ * Ein Monat ist die standart Zeispanne für das Vorladen der Stundenplandaten
+ *
+ * @constant
+ * @type {string} Zeitspanne im ISO Format(https://de.wikipedia.org/wiki/ISO_8601#Zeitspannen)
+ */
+const defaultPrefetchDistance = 'P1M';
+
+/**
+ * Selector für Wert, der anzeigt ob die Staging-Server genutzt werden sollen.
+ * @param {Object} reduxState
+ * @returns {boolean} true, wenn die Staging-Server verwendet werden sollen, ansonsten false
+ */
+function selectUseStagingServer(reduxState) {
+    return reduxState?.settingReducer?.settingsDevelop?.useStaging ?? false;
+}
+
+/**
+ * Provider for timetable context
+ */
+function TimetableContextProvider({ children }) {
+    const componentName = TimetableContextProvider.name;
+    const theme = useTheme();
+    const useStagingServers = useSelector(selectUseStagingServer);
+    const language = 'de';
+
+    // Einstellungen für das Stundenplan-Modul
+    const timetableSettings = theme?.appSettings?.modules?.timetable
+
+    // Einstellungen für Vorladen der Stundenplandaten
+    const timetablePrefetchSettings = timetableSettings?.prefetch;
+    const beginPrefetchDistance = timetablePrefetchSettings?.beginDistance ?? defaultPrefetchDistance;
+    const endPrefetchDistance = timetablePrefetchSettings?.beginDistance ?? defaultPrefetchDistance;
+
+    // Einstellungen für API-Provider
+    const timetableApiSettings = theme?.appSettings?.modules?.timetable?.api
+    // Soll der Staging-Provider verwendet werden?
+    const timetableApiProviderSettings = useStagingServers
+        // Wenn ja, werden die Staging Provider-Einstellungen geladen
+        ? timetableApiSettings?.staging
+        // Wenn nein, werden die productiven Provider-Einstellungen geladen
+        : timetableApiSettings?.production;
+
+    // Erstellen des Stundenplan-Services
+    const timetableService = useMemo(
+        () => TimetableService.fromProviderSettingsObject(
+            timetableApiProviderSettings,
+            language,
+        ),
+        [timetableApiProviderSettings, language]
+    );
+
+    // Stundenplan-Code aus dem Stundenplan-Service holen
+    // Es werden noch 2 Funktionen aus dem Stundenplan-Service geladen, um den Code zu speichern und zu löschen
+    const [timetableCode, saveTimetableCode, deleteTimetableCode] = useSyncTimetableCode(timetableService);
+
+    // Vorlesungen gruppiert nach Vorlesungstagen werden aus dem Stundenplan-Service geholt
+    // Es wird zusätzlich eine Funktion zum aktuallisieren der Vorlesungen mit geladen
+    const [courses, refreshCourses] = useSyncCourses(timetableService);
+
+    // Aktualiseren des course-States, wenn Provider oder Stundenplan-Code sich ändern.
+    useEffect(
+        () => {
+            // Stundenplan wird nur einmal geholt, wenn der Stundenplancode geladen ist
+            if ((timetableCode ?? false)) {
+                // Berechnen des Vorladezeitraumes
+                // ISO Zeitspannen(string) werden in Luxon Zeitspannen umgewandelt
+                const beginPrefetchDuration = Duration.fromISO(beginPrefetchDistance);
+                const endPrefetchDuration = Duration.fromISO(endPrefetchDistance);
+                // Jetztige Zeit ermitteln
+                const today = DateTime.now();
+                // Für den Anfang des Vorladezeitraumes das Datum berechnen
+                const prefetchStartDate = today.minus(beginPrefetchDuration).toISODate();
+                // Für das Ende des Vorlesungszeitraumes das Datum berechnen
+                const prefetchEndDate = today.plus(endPrefetchDuration).toISODate();
+
+                console.debug(componentName, 'prefetch timetable courses from', prefetchStartDate, 'to', prefetchEndDate);
+
+                refreshCourses(prefetchStartDate, prefetchEndDate)
+                    .then(() => setSynchronizationCompleted(true))
+                    .catch(
+                        reason => {
+                            if (!reason instanceof ApiProviderNotInitializedError || !reason instanceof TimetableCodeNotInitializedError) {
+                                console.error(componentName, ': Error while update courses by timetable code: ', reason, 'base url: ', timetableApiBaseUrl);
+                            }
+                        }
+                    );
+            }
+        }, [timetableService, beginPrefetchDistance, endPrefetchDistance, timetableCode]
+    );
+
+    return (
+        <TimetableContext.Provider
+            value={{
+                timetableCode: timetableCode,
+                saveTimetableCode: saveTimetableCode,
+                deleteTimetableCode: deleteTimetableCode,
+                courses: courses,
+                refreshCourses: refreshCourses,
+            }}
+        >
+            {children}
+        </TimetableContext.Provider>
+    );
+}
+
+/**
+ * Liefert den derzeitigen Stundenplan-Code und eine Funktion zum Speichern eines neues Stundenplan-Codes.
+ * @function
+ * @returns {[string, (timetableCode: string) => Promise<void>, () => Promise<void>]} Array mit 3 Elementen. Das erste Element ist der derzeitige gespeicherte Stundenplan-Code.
+ * Das zweite Element ist eine Funktion, welche das Speichern eines neuen Stundenplan-Codes ermlöglicht.
+ * Das dritte Element ist eine Funktion, die das Löschen des derzeitigen Stundenplan-Codes und der Courses ermöglicht.
+ * @example
+ * [timetableCode, saveTimetableCode, deleteTimetableCode] = useTimetableCode();
+ * saveTimetableCode(newTimetableCode);
+ * deleteTimetableCode();
+ */
+function useTimetableCode() {
+    const { timetableCode, saveTimetableCode, deleteTimetableCode } = useContext(TimetableContext);
+
+    return [timetableCode, saveTimetableCode, deleteTimetableCode];
+}
+
+/**
+ * Dieser Hook stellt die Vorlesungen aus dem Stundenplan-Kontext zur Verfügung.
+ * Es werden 2 Rückgabewerte in einem Array zurückgegeben.
+ * Der erste Parameter ist eine Map der Vorlesungen für den derzeitigen Stundenplan-Code im Stundenplan-Kontext.
+ * Die Schlüsel sind die Vorlesungstage und die Werte sind Listen der entsprechenden Vorlesungen zu dem im Schlüssel enthaltenen Datum.
+ * Der zweite Parameter ist eine parameterlose Funktion, welche die Vorlesungen im Stundenplan-Kontext aktuallisiert.
+ * @returns {[Object.<string, Course[]>, (startDate: string, endDate: string) => Promise<void>]} Array, welches aus 2 Elementen besteht.
+ * @example
+ * const [courses, refreshCourses] = useCourses();
+ *
+ * refreshCourses('2025-01-01', '2025-02-01');
+ *
+ * const coursesOfDay = courses['2025-01-01'];
+ */
+function useCourses() {
+    const { courses, refreshCourses } = useContext(TimetableContext);
+
+    return [courses, refreshCourses];
+}
+
+/**
+ *
+ *
+ * @param {string} date ISO Datum der Vorlesungen
+ * @returns {[Course[], (date : string) => Promise<void>]}
+ * @example
+ * const [dateCourses, refreshDateCourses] = useDateCourses('2025-01-01');
+ *
+ * refreshDateCourses();
+ */
+function useDateCourses(date) {
+    const [courses, refreshCourses] = useCourses();
+
+    const dateCourses = courses?.[date] ?? [];
+
+
+    return [dateCourses, refreshCourses]
+}
+
+export {
+    TimetableContext as default,
+    TimetableContextProvider,
+    CourseWeekModes as weekModes,
+    useTimetableCode,
+    useCourses,
+    useDateCourses,
+    TimetableNotFoundError,
+}