@royalschedule/maps 4.0.0 → 4.0.1

package/dist/Additio/types/options.d.ts

@@ -1,6 +1,14 @@
 //#region src/Additio/types/options.d.ts
 type Options = {
+  /**
+   * If we should include events (lessons) in the export.
+   * @default true
+   */
   includeEvents?: boolean;
+  /**
+   * If we should include complementary times (locked times of type 'COMPLEMENTARY_TIME') in the export.
+   * @default true
+   */
   includeComplementaryTimes?: boolean;
 };
 //#endregion

package/dist/PlanDigital/index.d.ts

@@ -1,5 +1,5 @@
-import { AvailableLocation, GroupReference, ID, PersonReference } from "../core/types/common/index.js";
 import { DateType } from "../common/types.js";
+import { AvailableLocation, GroupReference, ID, PersonReference } from "../core/types/common/index.js";
 import { BreakLength } from "../core/types/common/break-lengths.js";
 import { AllowedInterval } from "../core/types/common/intervals.js";
 import { Day } from "../core/types/common/days.js";
@@ -15,55 +15,55 @@ declare class PlanDigitalMap {
       groups?: {
         exceptions?: string[] | undefined;
         lockedTimes?: string[] | undefined;
-        createdAt?: string | undefined;
-        updatedAt?: string | undefined;
-        lastModifiedBy?: unknown;
         ids?: ID | undefined;
+        createdAt?: DateType | undefined;
+        updatedAt?: DateType | undefined;
+        lastModifiedBy?: unknown;
         belongsTo?: string | undefined;
         rank?: number | undefined;
         displayName?: string | undefined;
-        days?: Day[] | undefined;
+        lunch?: string[] | undefined;
         intervals?: AllowedInterval[] | undefined;
+        days?: Day[] | undefined;
         minBreakLength?: BreakLength | undefined;
+        tags?: Tag[] | undefined;
         maximumScheduleSpan?: MaximumScheduleSpan | undefined;
         forbidOverlappingEvents?: boolean | undefined;
         disableDayLengthPunishment?: boolean | undefined;
         weight?: number | undefined;
+        rootInterval?: string | undefined;
+        maxNumWorkingHours?: number | boolean | undefined;
+        maxNumDailyWorkingHours?: number | number[] | boolean | undefined;
         species?: "class" | undefined;
         parentGroups?: string[] | undefined;
         subGroups?: string[] | undefined;
-        lunch?: string[] | undefined;
         members?: string[] | undefined;
-        rootInterval?: string | undefined;
-        tags?: Tag[] | undefined;
-        maxNumWorkingHours?: number | boolean | undefined;
-        maxNumDailyWorkingHours?: number | number[] | boolean | undefined;
       }[];
       teachers?: {
         exceptions?: string[] | undefined;
         lockedTimes?: string[] | undefined;
-        createdAt?: string | undefined;
-        updatedAt?: string | undefined;
-        lastModifiedBy?: unknown;
         ids?: ID | undefined;
+        createdAt?: DateType | undefined;
+        updatedAt?: DateType | undefined;
+        lastModifiedBy?: unknown;
         belongsTo?: string | undefined;
         rank?: number | undefined;
         displayName?: string | undefined;
-        days?: Day[] | undefined;
+        lunch?: string[] | undefined;
         intervals?: AllowedInterval[] | undefined;
+        days?: Day[] | undefined;
         minBreakLength?: BreakLength | undefined;
+        tags?: Tag[] | undefined;
+        plannedScheduledDuration?: PlannedScheduledDuration | undefined;
         maximumScheduleSpan?: MaximumScheduleSpan | undefined;
         forbidOverlappingEvents?: boolean | undefined;
         disableDayLengthPunishment?: boolean | undefined;
         weight?: number | undefined;
-        lunch?: string[] | undefined;
+        person?: string | undefined;
         rootInterval?: string | undefined;
-        tags?: Tag[] | undefined;
+        signature?: string | undefined;
         maxNumWorkingHours?: number | boolean | undefined;
         maxNumDailyWorkingHours?: number | number[] | boolean | undefined;
-        plannedScheduledDuration?: PlannedScheduledDuration | undefined;
-        person?: string | undefined;
-        signature?: string | undefined;
       }[];
       courses?: {
         exceptions?: string[] | undefined;
@@ -72,26 +72,26 @@ declare class PlanDigitalMap {
         locations?: AvailableLocation<string>[] | undefined;
         events?: string[] | undefined;
         lockedTimes?: string[] | undefined;
-        createdAt?: string | undefined;
-        updatedAt?: string | undefined;
-        lastModifiedBy?: unknown;
         ids?: ID | undefined;
+        createdAt?: DateType | undefined;
+        updatedAt?: DateType | undefined;
+        lastModifiedBy?: unknown;
         belongsTo?: string | undefined;
-        type?: string | undefined;
         displayName?: string | undefined;
-        days?: Day[] | undefined;
-        weeks?: number[] | undefined;
-        period?: string | undefined;
         intervals?: AllowedInterval[] | undefined;
+        days?: Day[] | undefined;
         minBreakLength?: BreakLength | undefined;
-        weight?: number | undefined;
         tags?: Tag[] | undefined;
-        color?: string | undefined;
+        weeks?: number[] | undefined;
+        weight?: number | undefined;
+        period?: string | undefined;
         participants?: PersonReference<string>[] | undefined;
         density?: number | undefined;
         subject?: string | undefined;
+        color?: string | undefined;
         eventDurationVariance?: number | undefined;
         totalTime?: string | undefined;
+        type?: string | undefined;
         comment?: string | undefined;
         startDate?: DateType | undefined;
         endDate?: DateType | undefined;

package/dist/RS/types/event-configuration.d.ts

@@ -6,6 +6,9 @@ interface EventConfiguration {
   day: number;
   collection?: string;
   dependencies?: string[];
+  /**
+   * @deprecated Currently no need to use this as groups are fixed
+   */
   groups?: ({
     groups: string[];
   } | {

package/dist/RS/types/groups.d.ts

@@ -16,7 +16,9 @@ interface Group {
   days?: (Types.day | number)[];
   minimizeGaps?: boolean;
   minimizeDependencyAlternation?: boolean;
+  /** @deprecated in v3 */
   forbidOverlappingEvents?: boolean;
+  /** @deprecated replaced by minimizeGaps in v3 */
   disableDayLengthPunishment?: boolean;
   meta?: Record<string, unknown>;
 }

package/dist/RS/types/to.d.ts

@@ -7,7 +7,9 @@ import { Types as Types$1 } from "./index.js";
 //#region src/RS/types/to.d.ts
 type ToInput = MixedScheduleData;
 type PartialScheduleOptions<IDs extends Array<string> | Set<string>> = {
+  /** @description undefined means all included */
   includedEvents?: IDs;
+  /** @description undefined means all included */
   includedLocations?: IDs;
   omittedEventsHandling: 'ignore' | 'freeze';
 };
@@ -17,9 +19,22 @@ interface ToOptions extends BaseOptions {
   isPublicId?: boolean;
   appendCoreData?: boolean;
   appendOutput?: boolean;
+  /**
+   * @deprecated
+   * If true, the mapping becomes the same as the previous version 2 one. That means:
+   *
+   * - New root level entries: `intervals` and `individuals`
+   * - As the there is now a root level `intervals` the former may be references from `Collection.intervals`, `Group.intervals` etc.
+   * - The `Collection.groups` and `Event.groups` supports referencing `individuals` (and `individuals sets`) in addition to `groups`
+   * - The `Group.forbidOverlappingEvents` has been removed.
+   * - The `Group.disableDayLengthPunishment` has been replaced by `Group.minimizeGaps`
+   */
   oldFormat?: boolean;
   partialScheduleOptions?: PartialScheduleOptions<Array<string> | Set<string>>;
   algorithmWeightParameters?: AlgorithmWeightParameters;
+  /**
+   * to be used before whe have migrated from "maxNumWorkingHours" and "maxNumDailyWorkingHours" to "maximumScheduleSpan"
+   */
   useMaximumScheduleSpan?: boolean;
 }
 interface ParsedToOptions extends Omit<ToOptions, 'partialScheduleOptions'> {

package/dist/Skola24/txt/types/index.d.ts

@@ -116,10 +116,23 @@ declare namespace Types {
   type ta = TA;
   type lesson = Lesson;
   type student = Student;
+  type errorType = ErrorType;
   type errorCode = ErrorCode;
 }
 type Options = {
+  /**
+   * Specifies which field to use as the source for creating additional scheduling periods.
+   * By default, lessons are associated with their course's period, but this option allows
+   * creating distinct periods based on all unique values found in either the 'Week' or
+   * 'ActualWeeks' field of lesson data, and applying these periods to the lessons.
+   */
   createPeriodsFrom?: 'Week' | 'ActualWeeks' | null;
+  /**
+   * Import also events for which we cannot deduce the course.
+   * This is useful for example when you want to load all events for a teacher or a group
+   * but you don't care about the course. If you set this to true, we will create a
+   * dummy course for each event that doesn't have a course.
+   */
   includeEventsMissingCourse?: boolean;
 };
 //#endregion

package/dist/common/types.d.ts

@@ -3,10 +3,17 @@ import { Moment } from "moment";
 
 //#region src/common/types.d.ts
 type DateType = Moment | string | Date;
+/**
+ * T1 | T2 | ... => T1 & T2 & ...
+ */
 type Intersect<T> = (T extends any ? ((x: T) => 0) : never) extends ((x: infer R) => 0) ? R : never;
 type BaseOptions = {
   idKey?: IdKey;
 };
+/**
+ * The interface required for the "from" mapping functions.
+ */
+
 //#endregion
 export { BaseOptions, DateType, Intersect };
 //# sourceMappingURL=types.d.ts.map

package/dist/core/to/util.d.ts

@@ -1,10 +1,14 @@
-import { Vertex } from "../types/common/index.js";
 import { Intersect } from "../../common/types.js";
+import { Vertex } from "../types/common/index.js";
 
 //#region src/core/to/util.d.ts
 
 declare const keys: readonly ["_id", "createdAt", "updatedAt", "belongsTo", "lastModifiedBy", "CONTEXT"];
 type InternalKeysOmitted<V extends Vertex> = Omit<Intersect<V>, typeof keys[number]>;
+/**
+ * Returns a copy of the vertex with internal keys omitted, such as `_id`, `createdAt`, `updatedAt`, etc.
+ * The output type also omits all edges for ease of use.
+ */
 //#endregion
 export { InternalKeysOmitted };
 //# sourceMappingURL=util.d.ts.map

package/dist/core/types/common/index.d.ts

@@ -1,3 +1,4 @@
+import { DateType } from "../../../common/types.js";
 import { Types } from "mongoose";
 
 //#region src/core/types/common/index.d.ts
@@ -8,8 +9,8 @@ type Vertex = ({
 } | {
   id: ID;
 }) & {
-  createdAt?: string;
-  updatedAt?: string;
+  createdAt?: DateType;
+  updatedAt?: DateType;
   lastModifiedBy?: unknown;
   ids?: ID;
 };

package/dist/core/types/common/intervals.d.ts

@@ -6,7 +6,13 @@ type Interval<T = DateType> = {
   end: T;
 };
 interface AllowedInterval<T = DateType> extends Interval<T> {
+  /**
+   * @deprecated IS THIS REALLY OPTIONAL? ALSO, IS THIS USED ANYWHERE?
+   */
   day?: number;
+  /**
+   * @deprecated WHAT IS THE VALUE OF THE STRING!?
+   */
   type?: string;
 }
 //#endregion

package/dist/core/types/common/maximum-schedule-span.d.ts

@@ -1,6 +1,17 @@
 //#region src/core/types/common/maximum-schedule-span.d.ts
+/**
+ * The maximum number of minutes a schedule is allowed to span over a day and week
+ */
 type MaximumScheduleSpan = {
+  /**
+   * The maximum number of minutes a schedule is allowed to span over a day.
+   * The daily schedule span is the duration between the start of the first event and the end of the last event that day.
+   */
   daily?: number | null;
+  /**
+   * The maximum number of minutes a schedule is allowed to span over a week.
+   * The weekly schedule span is the sum of the daily schedule spans for each day of the week.
+   */
   weekly?: number | null;
 };
 //#endregion

package/dist/core/types/common/planned-schedule-duration.d.ts

@@ -1,5 +1,11 @@
 //#region src/core/types/common/planned-schedule-duration.d.ts
+/**
+ * The planned/expected total weekly minutes of schedule events assigned to a teacher
+ */
 type PlannedScheduledDuration = {
+  /**
+   * The planned/expected total weekly minutes of schedule events assigned to a teacher
+   */
   weekly?: number | null;
 };
 //#endregion

package/dist/core/types/courses.d.ts

@@ -1,5 +1,5 @@
-import { AvailableLocation, GroupReference, PersonReference, Vertex } from "./common/index.js";
 import { DateType } from "../../common/types.js";
+import { AvailableLocation, GroupReference, PersonReference, Vertex } from "./common/index.js";
 import { BreakLength } from "./common/break-lengths.js";
 import { AllowedInterval } from "./common/intervals.js";
 import { Day } from "./common/days.js";
@@ -48,7 +48,9 @@ type Course = Vertex & {
   overlapSpecies?: OverlapGroup | null;
   plannedDuration?: string;
   tags?: Tag[];
+  /** @deprecated replaced by plannedDuration? */
   minutesPerWeek?: number;
+  /** @deprecated replaced by plannedDuration? */
   expectedTotalHours?: number;
 };
 //#endregion

package/dist/core/types/division-settings.d.ts

@@ -1,5 +1,5 @@
-import { Vertex } from "./common/index.js";
 import { DateType } from "../../common/types.js";
+import { Vertex } from "./common/index.js";
 import { RootInterval } from "./root-intervals.js";
 import { MaximumScheduleSpan } from "./common/maximum-schedule-span.js";
 import { PlannedScheduledDuration } from "./common/planned-schedule-duration.js";
@@ -44,7 +44,9 @@ type DivisionSettings = Vertex & {
   eventTime?: number;
   eventTimeActive?: boolean;
   defaultRootInterval?: RootInterval;
+  /** @deprecated replaced by defaultMaximumScheduleSpan */
   defaultMaxNumWorkingHours?: number | null;
+  /** @deprecated replaced by defaultMaximumScheduleSpan */
   defaultMaxNumDailyWorkingHours?: number | null;
 };
 //#endregion

package/dist/core/types/divisions.d.ts

@@ -1,5 +1,5 @@
-import { Vertex } from "./common/index.js";
 import { DateType } from "../../common/types.js";
+import { Vertex } from "./common/index.js";
 import { DivisionSettings } from "./division-settings.js";
 import { Meta } from "./common/meta.js";
 
@@ -8,7 +8,7 @@ import { Meta } from "./common/meta.js";
 type StepGuideProgress = {
   checked: string[];
   completed: boolean;
-  updatedAt?: string;
+  updatedAt?: DateType;
 };
 type Division = Vertex & {
   settings?: DivisionSettings;

package/dist/core/types/events.d.ts

@@ -1,5 +1,5 @@
-import { AvailableLocation, GroupReference, PersonReference, Vertex } from "./common/index.js";
 import { DateType } from "../../common/types.js";
+import { AvailableLocation, GroupReference, PersonReference, Vertex } from "./common/index.js";
 import { BreakLength } from "./common/break-lengths.js";
 import { AllowedInterval } from "./common/intervals.js";
 import { Day } from "./common/days.js";

package/dist/core/types/exceptions.d.ts

@@ -1,5 +1,5 @@
-import { Coalesced, Vertex } from "./common/index.js";
 import { DateType } from "../../common/types.js";
+import { Coalesced, Vertex } from "./common/index.js";
 import { Group } from "./groups.js";
 import { Person } from "./persons.js";
 import { Teacher } from "./teachers.js";

package/dist/core/types/groups.d.ts

@@ -31,7 +31,9 @@ type Group = Vertex & {
   rootInterval?: RootInterval;
   days?: Day[];
   tags?: Tag[];
+  /** @deprecated replaced by maximumScheduleSpan */
   maxNumWorkingHours?: number | boolean;
+  /** @deprecated replaced by maximumScheduleSpan */
   maxNumDailyWorkingHours?: number | number[] | boolean;
 };
 //#endregion

package/dist/core/types/locked-times.d.ts

@@ -1,5 +1,5 @@
-import { Coalesced, Vertex } from "./common/index.js";
 import { DateType } from "../../common/types.js";
+import { Coalesced, Vertex } from "./common/index.js";
 import { AllowedInterval } from "./common/intervals.js";
 import { Day } from "./common/days.js";
 import { Tag } from "./common/tag.js";
@@ -11,7 +11,7 @@ import { Course } from "./courses.js";
 import { Division } from "./divisions.js";
 
 //#region src/core/types/locked-times.d.ts
-type Type = 'LUNCH' | 'COMPLEMENTARY_TIME';
+type Type = /* 'ANY' | */'LUNCH' | 'COMPLEMENTARY_TIME';
 type LockedTime = Vertex & {
   belongsTo?: Division;
   displayName?: string;

package/dist/core/types/persons.d.ts

@@ -1,5 +1,5 @@
-import { Vertex } from "./common/index.js";
 import { DateType } from "../../common/types.js";
+import { Vertex } from "./common/index.js";
 import { Tag } from "./common/tag.js";
 import { Group } from "./groups.js";
 import { LockedTime } from "./locked-times.js";

package/dist/core/types/teachers.d.ts

@@ -31,7 +31,9 @@ type Teacher = Vertex & {
   signature?: string;
   rank?: number;
   tags?: Tag[];
+  /** @deprecated replaced by maximumScheduleSpan */
   maxNumWorkingHours?: number | boolean;
+  /** @deprecated replaced by maximumScheduleSpan */
   maxNumDailyWorkingHours?: number | number[] | boolean;
 };
 //#endregion

package/dist/core/vertex-mapping.d.ts

@@ -42,8 +42,17 @@ type _Mixed<T extends Vertex, Depth extends SupportedDepths = MaxDepth, IgnoreIn
   depth: Depth;
   ignoreInternalId: IgnoreInternalId;
 }> };
+/**
+ * Given a vertex type, this will return a new type where all references to other vertices are replaced with their mixed type.
+ */
 type Mixed<T extends Vertex> = _Mixed<T>;
+/**
+ * Given a vertex type, this will return a new type where all references to other vertices are replaced with their mixed type, but without the internal id (`_id` and `id`)
+ */
 type MixedWithoutInternalId<T extends Vertex> = Omit<_Mixed<T, MaxDepth, true>, InternalIdKey>;
+/**
+ * Given a vertex type, this will return a new type where all references to other vertices are replaced with their serialized type at the specified depth.
+ */
 type Serialized<T extends Vertex, DepthIndex extends SupportedDepths = 0> = Vertex & { [K in keyof T]: TransformGeneral<T[K], {
   type: 'serialized';
   depth: DepthIndex;
@@ -51,6 +60,10 @@ type Serialized<T extends Vertex, DepthIndex extends SupportedDepths = 0> = Vert
   type: 'serialized';
   depth: DepthIndex;
 }> };
+/**
+ * Given a object that contains entries of vertices or arrays of vertices, this will return a new type where all references to other vertices are replaced with their serialized type.
+ */
+
 //#endregion
 export { Mixed, MixedWithoutInternalId, Serialized };
 //# sourceMappingURL=vertex-mapping.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@royalschedule/maps",
   "description": "",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",