Re-add grouping & combining schedules

.github/workflows/test.yml

@@ -17,6 +17,11 @@ jobs:
       - name: Type-check code
         run: deno check mod.ts
 
+      - name: Type-check examples
+        run: | 
+          shopt -s globstar
+          for f in examples/**/*.ts; do deno check $f; done
+
       - name: Run tests
         run: deno test --allow-none --doc
 

README.md

@@ -34,7 +34,7 @@ if (status !== LoginStatus.Ok) {
 }
 
 let timetable = await client.getOwnTimetable("2022-01-01", "2022-12-31");
-client.logout();
+await client.logout();
 
 console.log(timetable.lessons);
 ```

deno.jsonc

@@ -26,5 +26,10 @@
 
   "tasks": {
     "build_npm": "deno run -A scripts/build_npm.ts"
+  },
+
+  "compilerOptions": {
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true
   }
 }

examples/combine_schedules.ts

@@ -0,0 +1,21 @@
+/**
+ * This example shows how lesson schedules can be retrieved and combined.
+ */
+
+import { LoginStatus, UntisClient } from "../mod.ts";
+
+let client = new UntisClient("nessa.webuntis.com", "School name");
+
+let status = await client.login("username", "password");
+if (status !== LoginStatus.Ok) {
+  throw new Error(`Login failed: ${LoginStatus[status]}`);
+}
+
+let timetable = await client.getOwnTimetable("2022-01-01", "2022-12-31");
+await client.logout();
+
+let collection = timetable.getScheduleCollection();
+
+collection = collection.combineSequentialSchedules();
+
+console.log(collection.schedules);

examples/1.ts → examples/get_timetable.ts

@@ -1,3 +1,10 @@
+/**
+ * This example shows a basic usecase of
+ * - searching your school by its name,
+ * - logging in with your credentials and
+ * - fetching your timetable.
+ */
+
 import { LoginStatus, searchSchoolsByName } from "../mod.ts";
 
 let [school] = await searchSchoolsByName("School name");
@@ -9,12 +16,11 @@ if (!school) {
 let client = school.getClient();
 
 let status = await client.login("username", "password");
-
 if (status !== LoginStatus.Ok) {
   throw new Error(`Login failed: ${LoginStatus[status]}`);
 }
 
 let timetable = await client.getOwnTimetable("2022-01-01", "2022-12-31");
-client.logout();
+await client.logout();
 
 console.log(timetable.lessons);

lib/datetime/Time.ts

@@ -1,3 +1,5 @@
+import { TimeUnits } from "./TimeUnits.ts";
+
 /** Helper for comparing the start and end times of lessons. By no means a replacement for {@link Date}. */
 export class Time {
   constructor(
@@ -18,14 +20,29 @@ export class Time {
   }
 
   selectEarlier(other: Time): Time {
-    return this.hours <= other.hours && this.minutes <= other.minutes
-      ? this
-      : other;
+    if (this.hours === other.hours) {
+      return this.minutes <= other.minutes ? this : other;
+    }
+    return this.hours < other.hours ? this : other;
   }
 
   selectLater(other: Time): Time {
-    return this.hours >= other.hours && this.minutes >= other.minutes
-      ? this
-      : other;
+    if (this.hours === other.hours) {
+      return this.minutes >= other.minutes ? this : other;
+    }
+    return this.hours > other.hours ? this : other;
+  }
+
+  diffTo(other: Time): number {
+    let diff = (other.hours - this.hours) * TimeUnits.Hour +
+      (other.minutes - this.minutes) * TimeUnits.Minute;
+
+    return diff;
+  }
+
+  withDate(date: Date): Date {
+    date = new Date(date);
+    date.setHours(this.hours, this.minutes);
+    return date;
   }
 }

lib/datetime/TimeUnits.ts

@@ -0,0 +1,9 @@
+/** The number of milliseconds in each unit of time. */
+export enum TimeUnits {
+  Millisecond = 1,
+  Second = 1000 * TimeUnits.Millisecond,
+  Minute = 60 * TimeUnits.Second,
+  Hour = 60 * TimeUnits.Minute,
+  Day = 24 * TimeUnits.Hour,
+  Week = 7 * TimeUnits.Day,
+}

lib/datetime/Time_test.ts

@@ -0,0 +1,37 @@
+import { assert } from "std/testing/asserts.ts";
+import { Time, TimeUnits } from "./mod.ts";
+
+Deno.test("Time.selectEarlier() - should work with different hours", () => {
+  let a = new Time(9, 25);
+  let b = new Time(10, 0);
+
+  assert(a.selectEarlier(b).equals(a));
+});
+
+Deno.test("Time.selectEarlier() - should work with the same hour", () => {
+  let a = new Time(9, 25);
+  let b = new Time(9, 30);
+
+  assert(a.selectEarlier(b).equals(a));
+});
+
+Deno.test("Time.selectLater() - should work with different hours", () => {
+  let a = new Time(9, 25);
+  let b = new Time(10, 0);
+
+  assert(a.selectLater(b).equals(b));
+});
+
+Deno.test("Time.selectLater() - should work with the same hour", () => {
+  let a = new Time(9, 25);
+  let b = new Time(9, 30);
+
+  assert(a.selectLater(b).equals(b));
+});
+
+Deno.test("Time.diffTo() - should be +1 hour", () => {
+  let a = new Time(10, 30);
+  let b = new Time(11, 30);
+
+  assert(a.diffTo(b) === TimeUnits.Hour * 1);
+});

lib/datetime/mod.ts

@@ -1,2 +1,3 @@
 export * from "./Time.ts";
 export * from "./untis.ts";
+export * from "./TimeUnits.ts";

lib/datetime/untis.ts

@@ -1,5 +1,4 @@
-import { format } from "std/datetime/format.ts";
-import { parse } from "std/datetime/parse.ts";
+import { format, parse } from "std/datetime/mod.ts";
 import { Time } from "./Time.ts";
 
 /** Parse a date from the WebUntis API into a JS Date object using local time. */
@@ -10,7 +9,7 @@ export function parseUntisDate(date: string | number): Date {
 /** Parse a time from the WebUntis API into a {@link Time} object. */
 export function parseUntisTime(time: string | number): Time {
   time = String(time).padStart(4, "0");
-  return Time.fromDate(parse(time, "hhmm"));
+  return Time.fromDate(parse(time, "HHmm"));
 }
 
 /** Format a JS Date object into a format understood by the WebUntis API.  */

lib/jsonrpc/RpcClient.ts

@@ -70,7 +70,6 @@ export class RpcClient {
     }
 
     for (let { name, value } of getSetCookies(response.headers)) {
-      console.log({ name, value });
       this.cookies[name] = value;
     }
 

src/UntisClient.ts

@@ -54,7 +54,7 @@ export class UntisClient {
 
   /**
    * Logs in as a user. Needs to be called before accessing all other methods.
-   * You should log out ({@link UntisClient.logout()}) as soon as possible to free resources on WebUntis' servers.
+   * You should log out ({@link logout()}) as soon as possible to free resources on WebUntis' servers.
    * @param username username to log in with.
    * @param password user password.
    * @returns a {@link LoginStatus} describing whether the login was successful.
@@ -209,10 +209,10 @@ export class UntisClient {
         showLsText: true,
         showLsNumber: true,
         showStudentgroup: true,
-        klasseFields: ["id", "name", "longname"],
-        roomFields: ["id", "name", "longname"],
-        subjectFields: ["id", "name", "longname"],
-        teacherFields: ["id", "name", "longname"],
+        klasseFields: ["id", "name"],
+        roomFields: ["id", "name"],
+        subjectFields: ["id", "name"],
+        teacherFields: ["id", "name"],
       },
     };
 

src/webuntis/resources/lesson.ts

@@ -19,7 +19,6 @@ export type lesson = {
 export type lessonElement = {
   id: number;
   name: string;
-  longname: string;
 
   /**
    * If this is not `undefined`, this is the id of the original element and

src/wrappers/Lesson.ts

@@ -1,7 +1,7 @@
 import { parseUntisDate, Time } from "lib/datetime/mod.ts";
 import { lesson } from "webuntis/resources";
 import { parseUntisTime } from "../../lib/datetime/untis.ts";
-import { LessonElements } from "./LessonElements.ts";
+import { LessonElementCollection } from "./LessonElementCollection.ts";
 import { Schedule } from "./Schedule.ts";
 
 type lessonType =
@@ -38,32 +38,34 @@ function getLessonCode(lesson: lesson): lessonCode {
   return lesson.code || "regular";
 }
 
-/**
- * Wrapper around the lesson object.
- */
-export class Lesson extends Schedule {
+/** Wrapper around the lesson object. */
+export class Lesson {
   constructor(
+    /** The lesson's id. Is unique and not the same for repeated occurrences. */
     readonly id: number,
+    /** The date the lesson occurs on. */
     readonly date: Date,
-    startTime: Time,
-    endTime: Time,
+    /** Time the lesson starts at. */
+    readonly startTime: Time,
+    /** Time the lesson ends at. */
+    readonly endTime: Time,
+    /** The type of lesson. */
     readonly lessonType: lessonType,
+    /** Code that represents whether the lesson is regular, cancelled or irregular. */
     readonly lessonCode: lessonCode,
-    lessonNumber: number,
-    lessonText: string,
+    /** Lesson number that is shared by all lessons in this student group (combination of class and subject). */
+    readonly lessonNumber: number,
+    /** Lesson text. */
+    readonly lessonText: string,
+    /** Text containing info about a substitution if present. */
     readonly substitutionText: string | null,
+    /** Activitiy type. */
     readonly activityType: string,
-    studentGroup: string | null,
-    readonly elements: LessonElements,
+    /** Name of the lesson's student group. */
+    readonly studentGroup: string | null,
+    /** Collection of elements included in the lesson. */
+    readonly elements: LessonElementCollection,
   ) {
-    super(
-      lessonNumber,
-      date.getDay(),
-      startTime,
-      endTime,
-      studentGroup,
-      lessonText,
-    );
   }
 
   /** Creates a new instance of this class from a lesson object returned by WebUntis.  */
@@ -80,24 +82,30 @@ export class Lesson extends Schedule {
       lesson.substText || null,
       lesson.activityType,
       lesson.sg || null,
-      LessonElements.fromLesson(lesson),
+      LessonElementCollection.fromLesson(lesson),
     );
   }
 
+  /** Creates a new schedule object that represents the schedule the lesson belongs to. */
   getSchedule(): Schedule {
     return new Schedule(
       this.lessonNumber,
-      this.weekDay,
+      this.date.getDay(),
       this.startTime,
       this.endTime,
       this.studentGroup,
       this.lessonText,
     );
   }
 
+  /** Checks whether the lesson belongs to a schedule. */
+  belongsToSchedule(schedule: Schedule): boolean {
+    return this.getSchedule().equals(schedule);
+  }
+
   /**
    * Checks whether this lesson deviates from its weekly schedule.
-   * A deviation could be that the lesson is cancelled or that it has substituted or missing elements compared to its schedule.
+   * A deviation could be that the lesson is cancelled or that it has substituted or removed elements compared to its schedule.
    */
   deviatesFromSchedule(): boolean {
     return this.substitutionText !== null ||
@@ -106,4 +114,37 @@ export class Lesson extends Schedule {
         .flat()
         .some((element) => element.isSubstituted());
   }
+
+  /** Checks whether two lessons are sequential and can be combined. */
+  isSequential(other: Lesson): boolean {
+    return this.date.valueOf() === other.date.valueOf() &&
+      (this.endTime.equals(other.startTime) ||
+        other.endTime.equals(this.startTime)) &&
+      this.lessonType === other.lessonType &&
+      this.lessonCode === other.lessonCode &&
+      this.lessonNumber === other.lessonNumber &&
+      this.lessonText === other.lessonText &&
+      this.substitutionText === other.substitutionText &&
+      this.activityType === other.activityType &&
+      this.studentGroup === other.studentGroup &&
+      this.elements.equals(other.elements);
+  }
+
+  /** Creates a new lesson by combining this lesson with another lesson. */
+  combineWith(other: Lesson): Lesson {
+    return new Lesson(
+      this.id,
+      this.date,
+      this.startTime.selectEarlier(other.startTime),
+      this.endTime.selectLater(other.endTime),
+      this.lessonType,
+      this.lessonCode,
+      this.lessonNumber,
+      this.lessonText,
+      this.substitutionText,
+      this.activityType,
+      this.studentGroup,
+      this.elements,
+    );
+  }
 }