chuvsu-js 5.0.0 → 5.1.0

package/dist/tt/domain/index.d.ts

@@ -3,5 +3,7 @@ export { TimetableDirectory } from "./directory.js";
 export { entityKey, mergeEntityRefs, mergeGroups, mergeRooms, mergeTeachers, normalizeScheduleText, } from "./normalize.js";
 export { MemoryTimetableRepositoryAdapter, TimetableRepository, } from "./repository.js";
 export { Schedule } from "./schedule.js";
+export { MaterializedSchedule, materializeSchedule, materializeScheduleSnapshot, } from "./materialized-schedule.js";
 export type { ScheduleQueryOptions, ScheduleOptions, ScheduleWeekdayOptions, } from "./schedule.js";
+export type { MaterializeScheduleOptions, MaterializedScheduleSnapshot, SerializedLessonOccurrence, SerializedLessonSourceRef, } from "./materialized-schedule.js";
 export type { GroupAttendance, GroupRef, IngestResult, LessonId, LessonIdGenerator, LessonOccurrence, LessonRecurrence, LessonSeries, LessonSeriesId, RelationCompleteness, RelationSet, LessonSourceRef, LessonStatus, LessonSubstitution, LessonTransfer, NamedEntityRef, OccurrenceObservation, RoomRef, ScheduleObservation, ScheduleOwner, ScheduleSourceSnapshot, SeriesObservation, TeacherRef, TimetableDirectorySnapshot, TimetableRepositoryAdapter, TimetableRepositorySnapshot, } from "./types.js";

package/dist/tt/domain/index.js

@@ -3,3 +3,4 @@ export { TimetableDirectory } from "./directory.js";
 export { entityKey, mergeEntityRefs, mergeGroups, mergeRooms, mergeTeachers, normalizeScheduleText, } from "./normalize.js";
 export { MemoryTimetableRepositoryAdapter, TimetableRepository, } from "./repository.js";
 export { Schedule } from "./schedule.js";
+export { MaterializedSchedule, materializeSchedule, materializeScheduleSnapshot, } from "./materialized-schedule.js";

package/dist/tt/domain/materialized-schedule.d.ts

@@ -0,0 +1,40 @@
+import type { AcademicPeriod, LocalDate } from "../../common/types.js";
+import type { Schedule } from "./schedule.js";
+import type { LessonOccurrence, LessonSourceRef, ScheduleOwner } from "./types.js";
+export interface SerializedLessonSourceRef extends Omit<LessonSourceRef, "observedAt"> {
+    observedAt: string;
+}
+export interface SerializedLessonOccurrence extends Omit<LessonOccurrence, "sources"> {
+    sources: SerializedLessonSourceRef[];
+}
+export interface MaterializedScheduleSnapshot {
+    schemaVersion: 1;
+    repositoryRevision: number;
+    owner: ScheduleOwner;
+    academicYearStartYear: number;
+    period: AcademicPeriod;
+    lessonsByDate: Record<LocalDate, SerializedLessonOccurrence[]>;
+}
+export interface MaterializeScheduleOptions {
+    start?: Date;
+    end?: Date;
+    includeSources?: boolean;
+}
+export declare class MaterializedSchedule {
+    readonly owner: ScheduleOwner;
+    readonly academicYearStartYear: number;
+    readonly period: AcademicPeriod;
+    readonly repositoryRevision: number;
+    private readonly lessonsByDate;
+    private readonly dateSetCache;
+    constructor(snapshot: MaterializedScheduleSnapshot);
+    export(): MaterializedScheduleSnapshot;
+    on(date: Date, options?: {
+        subgroup?: number;
+    }): LessonOccurrence[];
+    dateKeys(options?: {
+        subgroup?: number;
+    }): ReadonlySet<LocalDate>;
+}
+export declare function materializeSchedule(schedule: Schedule, options?: MaterializeScheduleOptions): MaterializedSchedule;
+export declare function materializeScheduleSnapshot(schedule: Schedule, options?: MaterializeScheduleOptions): MaterializedScheduleSnapshot;

package/dist/tt/domain/materialized-schedule.js

@@ -0,0 +1,132 @@
+import { formatLocalDate } from "../utils/index.js";
+import { entityKey } from "./normalize.js";
+function attendanceMatchesSubgroup(groups, owner, subgroup) {
+    if (subgroup == null)
+        return true;
+    if (owner.type === "group") {
+        const ownerKey = entityKey(owner.group);
+        return groups
+            .filter((value) => entityKey(value.group) === ownerKey)
+            .some((value) => value.subgroup == null || value.subgroup === subgroup);
+    }
+    return groups.some((value) => value.subgroup == null || value.subgroup === subgroup);
+}
+function serializeOccurrence(value, includeSources) {
+    return {
+        ...structuredClone(value),
+        sources: includeSources
+            ? value.sources.map((source) => ({
+                ...structuredClone(source),
+                observedAt: source.observedAt.toISOString(),
+            }))
+            : [],
+    };
+}
+function deserializeOccurrence(value) {
+    return {
+        ...structuredClone(value),
+        sources: value.sources.map((source) => ({
+            ...structuredClone(source),
+            observedAt: new Date(source.observedAt),
+        })),
+    };
+}
+function sortOccurrences(left, right) {
+    return (left.scheduledDate.localeCompare(right.scheduledDate) ||
+        ((left.time?.start.hours ?? 24) * 60 +
+            (left.time?.start.minutes ?? 0)) -
+            ((right.time?.start.hours ?? 24) * 60 +
+                (right.time?.start.minutes ?? 0)) ||
+        (left.slotNumber ?? Number.MAX_SAFE_INTEGER) -
+            (right.slotNumber ?? Number.MAX_SAFE_INTEGER) ||
+        left.subject.localeCompare(right.subject) ||
+        left.id.localeCompare(right.id));
+}
+export class MaterializedSchedule {
+    owner;
+    academicYearStartYear;
+    period;
+    repositoryRevision;
+    lessonsByDate = new Map();
+    dateSetCache = new Map();
+    constructor(snapshot) {
+        if (snapshot.schemaVersion !== 1) {
+            throw new Error(`Unsupported materialized schedule schema: ${snapshot.schemaVersion}`);
+        }
+        this.owner = structuredClone(snapshot.owner);
+        this.academicYearStartYear = snapshot.academicYearStartYear;
+        this.period = snapshot.period;
+        this.repositoryRevision = snapshot.repositoryRevision;
+        for (const [date, lessons] of Object.entries(snapshot.lessonsByDate)) {
+            this.lessonsByDate.set(date, lessons.map(deserializeOccurrence).sort(sortOccurrences));
+        }
+    }
+    export() {
+        return {
+            schemaVersion: 1,
+            repositoryRevision: this.repositoryRevision,
+            owner: structuredClone(this.owner),
+            academicYearStartYear: this.academicYearStartYear,
+            period: this.period,
+            lessonsByDate: Object.fromEntries([...this.lessonsByDate].map(([date, lessons]) => [
+                date,
+                lessons.map((lesson) => serializeOccurrence(lesson, true)),
+            ])),
+        };
+    }
+    on(date, options) {
+        const lessons = this.lessonsByDate.get(formatLocalDate(date)) ?? [];
+        return structuredClone(options?.subgroup == null
+            ? lessons
+            : lessons.filter((lesson) => attendanceMatchesSubgroup(lesson.groups.values, this.owner, options.subgroup)));
+    }
+    dateKeys(options) {
+        const subgroup = options?.subgroup;
+        const cached = this.dateSetCache.get(subgroup);
+        if (cached)
+            return new Set(cached);
+        const dates = new Set();
+        for (const [date, lessons] of this.lessonsByDate) {
+            if (subgroup == null ||
+                lessons.some((lesson) => attendanceMatchesSubgroup(lesson.groups.values, this.owner, subgroup))) {
+                dates.add(date);
+            }
+        }
+        this.dateSetCache.set(subgroup, dates);
+        return new Set(dates);
+    }
+}
+export function materializeSchedule(schedule, options) {
+    return new MaterializedSchedule(materializeScheduleSnapshot(schedule, options));
+}
+export function materializeScheduleSnapshot(schedule, options) {
+    const start = options?.start == null
+        ? new Date(schedule.academicYearStartYear, 8, 1)
+        : new Date(options.start);
+    const end = options?.end == null
+        ? new Date(schedule.academicYearStartYear + 1, 7, 31)
+        : new Date(options.end);
+    if (!Number.isFinite(start.getTime()) || !Number.isFinite(end.getTime())) {
+        throw new RangeError("Materialized schedule range contains an invalid date");
+    }
+    if (start > end) {
+        throw new RangeError("Materialized schedule start must not exceed end");
+    }
+    const lessonsByDate = {};
+    const date = new Date(start);
+    date.setHours(0, 0, 0, 0);
+    for (; date <= end; date.setDate(date.getDate() + 1)) {
+        const lessons = schedule.on(date);
+        if (lessons.length === 0)
+            continue;
+        lessonsByDate[formatLocalDate(date)] = lessons.map((lesson) => serializeOccurrence(lesson, options?.includeSources !== false));
+    }
+    return {
+        schemaVersion: 1,
+        repositoryRevision: schedule.revision,
+        owner: schedule.owner,
+        academicYearStartYear: schedule.academicYearStartYear,
+        period: schedule.period,
+        lessonsByDate,
+    };
+}

package/dist/tt/domain/schedule.d.ts

@@ -1,6 +1,7 @@
 import { AcademicPeriod } from "../../common/types.js";
 import { type Holiday, type HolidayTransfer } from "../utils/index.js";
 import { TimetableRepository } from "./repository.js";
+import { type MaterializeScheduleOptions, type MaterializedSchedule, type MaterializedScheduleSnapshot } from "./materialized-schedule.js";
 import type { LessonOccurrence, LessonSeries, ScheduleOwner } from "./types.js";
 export interface ScheduleQueryOptions {
     subgroup?: number;
@@ -20,10 +21,16 @@ export declare class Schedule {
     readonly period: AcademicPeriod;
     readonly holidays: Holiday[];
     readonly holidayTransfers: HolidayTransfer[];
+    private cachedRevision;
+    private cachedSeries;
+    private cachedDirectOccurrences;
     constructor(repository: TimetableRepository, owner: ScheduleOwner, academicYearStartYear: number, options?: ScheduleOptions);
     get revision(): number;
+    private queryData;
     series(): LessonSeries[];
     on(date: Date, options?: ScheduleQueryOptions): LessonOccurrence[];
+    materialize(options?: MaterializeScheduleOptions): MaterializedSchedule;
+    materializeSnapshot(options?: MaterializeScheduleOptions): MaterializedScheduleSnapshot;
     week(week?: number, options?: ScheduleQueryOptions): LessonOccurrence[];
     weekday(weekday: number, options?: ScheduleWeekdayOptions): LessonOccurrence[];
     today(options?: ScheduleQueryOptions): LessonOccurrence[];

package/dist/tt/domain/schedule.js

@@ -2,6 +2,7 @@ import { AcademicPeriod } from "../../common/types.js";
 import { getAdjacentSemester, getCurrentPeriod, getMonday, getSemesterStart, getSemesterWeeks, getWeekNumber, formatLocalDate, isHoliday, parseLocalDate, RUSSIAN_HOLIDAYS, } from "../utils/index.js";
 import { occurrenceIdForSeries } from "./ids.js";
 import { entityKey, normalizeScheduleText } from "./normalize.js";
+import { materializeSchedule, materializeScheduleSnapshot, } from "./materialized-schedule.js";
 function dateAt(date, time) {
     const value = new Date(date);
     value.setHours(time.hours, time.minutes, 0, 0);
@@ -76,6 +77,9 @@ export class Schedule {
     period;
     holidays;
     holidayTransfers;
+    cachedRevision = -1;
+    cachedSeries = [];
+    cachedDirectOccurrences = [];
     constructor(repository, owner, academicYearStartYear, options) {
         this.repository = repository;
         this.owner = structuredClone(owner);
@@ -90,21 +94,32 @@ export class Schedule {
     get revision() {
         return this.repository.revision;
     }
+    queryData() {
+        if (this.cachedRevision !== this.repository.revision) {
+            this.cachedSeries = this.repository.getSeries({
+                owner: this.owner,
+                academicYearStartYear: this.academicYearStartYear,
+            });
+            this.cachedDirectOccurrences = this.repository.getDirectOccurrences({
+                owner: this.owner,
+                academicYearStartYear: this.academicYearStartYear,
+            });
+            this.cachedRevision = this.repository.revision;
+        }
+        return {
+            series: this.cachedSeries,
+            direct: this.cachedDirectOccurrences,
+        };
+    }
     series() {
-        return this.repository.getSeries({
-            owner: this.owner,
-            academicYearStartYear: this.academicYearStartYear,
-        });
+        return structuredClone(this.queryData().series);
     }
     on(date, options) {
         if (!this.isInAcademicYear(date))
             return [];
         const holiday = isHoliday(date, this.holidays, this.holidayTransfers);
         const localDate = formatLocalDate(date);
-        const direct = this.repository.getDirectOccurrences({
-            owner: this.owner,
-            academicYearStartYear: this.academicYearStartYear,
-        });
+        const { series: recurringSeries, direct } = this.queryData();
         const movedSources = direct
             .filter((value) => value.movedFrom)
             .map((value) => ({
@@ -114,7 +129,7 @@ export class Schedule {
             groups: value.groups.values,
         }));
         const occurrences = [];
-        for (const series of this.series()) {
+        for (const series of recurringSeries) {
             if (holiday)
                 continue;
             const week = recurrenceIncludes(series, date);
@@ -168,7 +183,7 @@ export class Schedule {
             };
             if (occurrenceMatchesOwner(occurrence, this.owner) &&
                 attendanceMatchesSubgroup(occurrence.groups.values, this.owner, options?.subgroup)) {
-                occurrences.push(occurrence);
+                occurrences.push(structuredClone(occurrence));
             }
         }
         for (const occurrence of direct) {
@@ -179,10 +194,16 @@ export class Schedule {
             if (!attendanceMatchesSubgroup(occurrence.groups.values, this.owner, options?.subgroup)) {
                 continue;
             }
-            occurrences.push(occurrence);
+            occurrences.push(structuredClone(occurrence));
         }
         return occurrences.sort(sortOccurrences);
     }
+    materialize(options) {
+        return materializeSchedule(this, options);
+    }
+    materializeSnapshot(options) {
+        return materializeScheduleSnapshot(this, options);
+    }
     week(week, options) {
         const period = this.period === AcademicPeriod.WinterSession ||
             this.period === AcademicPeriod.SummerSession

package/dist/tt/parse/overlays.js

@@ -1,8 +1,9 @@
 import { parseTeacher, text } from "../../common/parse.js";
 import { parseGroupsString } from "./groups.js";
-import { hasDistanceMarker } from "./entry-parts.js";
-import { LESSON_TYPE_PATTERN, LESSON_TYPE_RE, LESSON_TYPE_RE_I, SUBGROUP_RE, } from "./patterns.js";
+import { containsGroupCode, hasDistanceMarker, linesAfterSubject, stripDistanceMarker, } from "./entry-parts.js";
+import { LESSON_TYPE_RE, LESSON_TYPE_RE_I, SUBGROUP_RE, } from "./patterns.js";
 const GROUP_CODE_RE = /[A-ZА-ЯЁ]{1,}(?:-[A-ZА-ЯЁa-zа-яё0-9]+)+/u;
+const ROOM_CODE_RE = /^[А-Яа-яA-Za-z]-\d+$/u;
 const BLUE_SPAN_RE = /<span\b(?=[^>]*(?:style=["'][^"']*color:\s*blue|class=["'][^"']*\bblue\b))[^>]*>([^<]+)<\/span>/i;
 export function parseDate(dd, mm, yyyy) {
     return `${yyyy}-${mm}-${dd}`;
@@ -94,8 +95,9 @@ export function parseSubstituteForDiv(div) {
     const date = parseDate(m[1], m[2], m[3]);
     // Original teacher: first blue span (right after "замена вместо:")
     const origTeacherMatch = divHtml.match(/замена\s*вместо:\s*<\/b><\/span>\s*<span[^>]*>([^<]+)<\/span>/);
-    const originalTeacher = origTeacherMatch
-        ? parseTeacher(origTeacherMatch[1].trim())
+    const originalValue = origTeacherMatch?.[1].trim();
+    const originalTeacher = originalValue && !ROOM_CODE_RE.test(originalValue)
+        ? parseTeacher(originalValue)
         : undefined;
     // Subject: second blue span
     const subjectEl = div.querySelectorAll('span[style*="color: blue"]');
@@ -111,14 +113,20 @@ export function parseSubstituteForDiv(div) {
         return null;
     const roomMatch = divHtml.match(/(?:<br\s*\/?>)\s*([А-Яа-яA-Za-z]-\d+)/);
     const typeMatch = divText.match(LESSON_TYPE_RE);
-    const groupsMatch = divHtml.match(new RegExp(`\\((?:${LESSON_TYPE_PATTERN})\\)\\s*(?:<br\\s*\\/?>)\\s*([^<]+?)(?:\\s*<i|$)`));
+    const parts = linesAfterSubject(divHtml, subject);
+    const teacherLine = stripDistanceMarker(parts.find((line) => !containsGroupCode(stripDistanceMarker(line))) ?? "");
+    const groupsLine = parts
+        .filter((line) => containsGroupCode(stripDistanceMarker(line)))
+        .map(stripDistanceMarker)
+        .join(" ");
     const subgroupMatch = divText.match(SUBGROUP_RE);
-    const groups = parseGroupsString(groupsMatch?.[1]);
+    const groups = parseGroupsString(groupsLine);
     return {
         entry: {
             room: roomMatch?.[1] || undefined,
             subject,
             type: typeMatch?.[1] ?? "",
+            teacher: teacherLine ? parseTeacher(teacherLine) : undefined,
             groups: groups.length > 0 ? groups : undefined,
             subgroup: subgroupMatch ? parseInt(subgroupMatch[1]) : undefined,
             isDistance: hasDistanceMarker(divText) || hasDistanceMarker(roomMatch?.[1] ?? ""),

package/docs/v5-migration.md

@@ -276,6 +276,31 @@ const client = new TimetableClient({
 const snapshot = await client.exportRepository();
 ```
 
+Репозиторий предназначен для серверного хранения и дополнения данных. Не
+отправляйте полный `TimetableRepositorySnapshot` в браузер: его размер растет
+вместе со всеми когда-либо загруженными расписаниями, а восстановление требует
+повторной агрегации связей.
+
+Для API, SSR и офлайн-кеша материализуйте только готовое расписание владельца:
+
+```ts
+// Сервер: агрегация выполняется один раз, источники можно убрать из payload.
+const payload = schedule.materializeSnapshot({ includeSources: false });
+return Response.json(payload);
+
+// Браузер: JSON восстанавливается в индексированное по дате представление.
+import { MaterializedSchedule } from "chuvsu-js/browser";
+
+const schedule = new MaterializedSchedule(await response.json());
+schedule.on(date);                  // O(1) поиск даты
+schedule.dateKeys({ subgroup: 2 }); // даты для календаря
+```
+
+`MaterializedScheduleSnapshot` содержит уже объединенные `LessonOccurrence`,
+но не канонический репозиторий. Поле `repositoryRevision` позволяет серверному
+кешу инвалидировать снимок после дополнения пары из расписания преподавателя,
+аудитории или другой группы.
+
 Не передавайте экспорт `exportCache()` из v4 в `importCache()` v5: изменились
 ключи, категории и форма закешированных страниц. Старый TTL-кеш и старые blob-
 ключи следует удалить. Снимок репозитория v5 имеет `schemaVersion: 5`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chuvsu-js",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Библиотека для расписания и личного кабинета ЧГУ им. И. Н. Ульянова",
   "type": "module",
   "main": "dist/index.js",