@royalschedule/maps 4.1.4 → 4.1.5

package/dist/core/interfaces/vertices/properties/belongs-to.d.mts

@@ -0,0 +1,11 @@
+import { EdgeWrapper, Plain } from "../util/edges.mjs";
+import "../util/index.mjs";
+import { DivisionVertex } from "../divisions.mjs";
+
+//#region src/core/interfaces/vertices/properties/belongs-to.d.ts
+type BelongsTo = {
+  belongsTo?: EdgeWrapper<'single', Plain.Edge<DivisionVertex>>;
+};
+//#endregion
+export { BelongsTo };
+//# sourceMappingURL=belongs-to.d.mts.map

package/dist/core/interfaces/vertices/properties/coalesced.d.mts

@@ -0,0 +1,8 @@
+import { Coalesced as Coalesced$1 } from "../util/edges.mjs";
+import "../util/index.mjs";
+
+//#region src/core/interfaces/vertices/properties/coalesced.d.ts
+type Coalesced<T, M = string> = Coalesced$1.Util.Value<T, M>;
+//#endregion
+export { Coalesced };
+//# sourceMappingURL=coalesced.d.mts.map

package/dist/core/interfaces/vertices/properties/days.d.mts

@@ -0,0 +1,9 @@
+//#region src/core/interfaces/vertices/properties/days.d.ts
+interface Day {
+  is?: 'day';
+  day: number;
+  rank?: number;
+}
+//#endregion
+export { Day };
+//# sourceMappingURL=days.d.mts.map

package/dist/core/interfaces/vertices/properties/index.d.mts

@@ -0,0 +1,15 @@
+import { Coalesced } from "./coalesced.mjs";
+import { Species } from "./species.mjs";
+import { AllWeeks, Week, allWeeks } from "./week.mjs";
+import { Day } from "./days.mjs";
+import { Interval } from "./intervals.mjs";
+import { Tag, TagType } from "./tags.mjs";
+import { MaximumScheduleSpan } from "./maximum-schedule-span.mjs";
+import { PlannedScheduledDuration } from "./planned-scheduled-duration.mjs";
+import { MinBreakLength } from "./min-break-length.mjs";
+
+//#region src/core/interfaces/vertices/properties/index.d.ts
+type PublicId = string;
+//#endregion
+export { PublicId };
+//# sourceMappingURL=index.d.mts.map

package/dist/core/interfaces/vertices/properties/intervals.d.mts

@@ -0,0 +1,10 @@
+import { DateType } from "../../other/etc.mjs";
+
+//#region src/core/interfaces/vertices/properties/intervals.d.ts
+type Interval<T extends DateType = DateType> = {
+  start: T;
+  end: T;
+};
+//#endregion
+export { Interval };
+//# sourceMappingURL=intervals.d.mts.map

package/dist/core/interfaces/vertices/properties/maximum-schedule-span.d.mts

@@ -0,0 +1,19 @@
+//#region src/core/interfaces/vertices/properties/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
+export { MaximumScheduleSpan };
+//# sourceMappingURL=maximum-schedule-span.d.mts.map

package/dist/core/interfaces/vertices/properties/min-break-length.d.mts

@@ -0,0 +1,5 @@
+//#region src/core/interfaces/vertices/properties/min-break-length.d.ts
+type MinBreakLength = number | [number, number] | false;
+//#endregion
+export { MinBreakLength };
+//# sourceMappingURL=min-break-length.d.mts.map

package/dist/core/interfaces/vertices/properties/planned-scheduled-duration.d.mts

@@ -0,0 +1,13 @@
+//#region src/core/interfaces/vertices/properties/planned-scheduled-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
+export { PlannedScheduledDuration };
+//# sourceMappingURL=planned-scheduled-duration.d.mts.map

package/dist/core/interfaces/vertices/properties/species.d.mts

@@ -0,0 +1,9 @@
+//#region src/core/interfaces/vertices/properties/species.d.ts
+interface Species<T, M = string> {
+  to: T;
+  toModel: M;
+  id: string;
+}
+//#endregion
+export { Species };
+//# sourceMappingURL=species.d.mts.map

package/dist/core/interfaces/vertices/properties/tags.d.mts

@@ -0,0 +1,9 @@
+//#region src/core/interfaces/vertices/properties/tags.d.ts
+type TagType = 'COMPLEMENTARY_TIME' | 'category';
+type Tag = {
+  type?: TagType;
+  value: string;
+};
+//#endregion
+export { Tag, TagType };
+//# sourceMappingURL=tags.d.mts.map

package/dist/core/interfaces/vertices/properties/week.d.mts

@@ -0,0 +1,22 @@
+import { Moment } from "moment";
+
+//#region src/core/interfaces/vertices/properties/week.d.ts
+type Week = {
+  id: string;
+  range: {
+    start: Moment;
+    end: Moment;
+  };
+  number: number;
+  string: string;
+  excludedDays: {
+    date: string;
+    day: number;
+    reason?: string;
+  }[];
+};
+declare const allWeeks = "all";
+type AllWeeks = typeof allWeeks;
+//#endregion
+export { AllWeeks, Week, allWeeks };
+//# sourceMappingURL=week.d.mts.map

package/dist/core/interfaces/vertices/properties/week.mjs

@@ -0,0 +1,6 @@
+//#region src/core/interfaces/vertices/properties/week.ts
+const allWeeks = "all";
+
+//#endregion
+export { allWeeks };
+//# sourceMappingURL=week.mjs.map

package/dist/core/interfaces/vertices/properties/week.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"week.mjs","names":[],"sources":["../../../../../src/core/interfaces/vertices/properties/week.ts"],"sourcesContent":["import type { Moment } from 'moment';\n\nexport type Week = {\n  id:           string;\n  range:        { start: Moment; end: Moment };\n  number:       number;\n  string:       string;\n  excludedDays: { date: string, day: number, reason?: string }[];\n};\n\nexport const allWeeks = 'all';\nexport type AllWeeks = typeof allWeeks;"],"mappings":";AAUA,MAAa,WAAW"}

package/dist/core/interfaces/vertices/root-intervals.d.mts

@@ -0,0 +1,14 @@
+import { VertexFactory } from "./util/vertex.mjs";
+import "./util/index.mjs";
+import { Interval } from "./properties/intervals.mjs";
+import "./properties/index.mjs";
+import { BelongsTo } from "./properties/belongs-to.mjs";
+import { Moment } from "moment";
+
+//#region src/core/interfaces/vertices/root-intervals.d.ts
+type RootIntervalVertex = VertexFactory<'rootIntervals', BelongsTo & {
+  intervals: Interval<string | Moment>[];
+}>;
+//#endregion
+export { RootIntervalVertex };
+//# sourceMappingURL=root-intervals.d.mts.map

package/dist/core/interfaces/vertices/syllabuses.d.mts

@@ -0,0 +1,20 @@
+import { VertexFactory } from "./util/vertex.mjs";
+import "./util/index.mjs";
+import { BelongsTo } from "./properties/belongs-to.mjs";
+
+//#region src/core/interfaces/vertices/syllabuses.d.ts
+type SyllabusVertex = VertexFactory<'syllabuses', BelongsTo & {
+  schoolType: string;
+  subjectCode?: string;
+  subjectName: string;
+  color?: string | null;
+  icon?: string | null;
+  subjectDesignation?: string;
+  courseCode?: string;
+  courseName?: string;
+  points?: number;
+  official: boolean;
+}>;
+//#endregion
+export { SyllabusVertex };
+//# sourceMappingURL=syllabuses.d.mts.map

package/dist/core/interfaces/vertices/teachers.d.mts

@@ -0,0 +1,41 @@
+import { VertexFactory } from "./util/vertex.mjs";
+import { EdgeWrapper, Plain } from "./util/edges.mjs";
+import "./util/index.mjs";
+import { Day } from "./properties/days.mjs";
+import { Interval } from "./properties/intervals.mjs";
+import { Tag } from "./properties/tags.mjs";
+import { MaximumScheduleSpan } from "./properties/maximum-schedule-span.mjs";
+import { PlannedScheduledDuration } from "./properties/planned-scheduled-duration.mjs";
+import { RootIntervalVertex } from "./root-intervals.mjs";
+import { BelongsTo } from "./properties/belongs-to.mjs";
+import { PersonVertex } from "./persons.mjs";
+import { ExceptionVertex } from "./exceptions.mjs";
+import { LockedTimeVertex } from "./locked-times.mjs";
+
+//#region src/core/interfaces/vertices/teachers.d.ts
+type TeacherVertex = VertexFactory<'teachers', BelongsTo & {
+  tags?: Tag[];
+  signature?: string;
+  minBreakLength?: number; /** @deprecated replaced by defaultMaximumScheduleSpan */
+  maxNumWorkingHours?: number | false; /** @deprecated replaced by defaultMaximumScheduleSpan */
+  maxNumDailyWorkingHours?: number | number[] | false;
+  plannedScheduledDuration?: PlannedScheduledDuration;
+  maximumScheduleSpan?: MaximumScheduleSpan;
+  forbidOverlappingEvents?: boolean;
+  disableDayLengthPunishment?: boolean;
+  weight?: number;
+  /**
+   * @note an empty array is the same as undefined
+   */
+  intervals?: Interval[];
+  days?: Day[];
+  rootInterval?: EdgeWrapper<'single', Plain.Edge<RootIntervalVertex>>;
+  lockedTimes?: EdgeWrapper<'array', Plain.Edge<LockedTimeVertex>>;
+  lunch?: EdgeWrapper<'array', Plain.Edge<LockedTimeVertex>>;
+  complementaryTimes?: EdgeWrapper<'array', Plain.Edge<LockedTimeVertex>>;
+  exceptions?: EdgeWrapper<'array', Plain.Edge<ExceptionVertex>>;
+  person?: EdgeWrapper<'single', Plain.Edge<PersonVertex>>;
+}>;
+//#endregion
+export { TeacherVertex };
+//# sourceMappingURL=teachers.d.mts.map

package/dist/core/interfaces/vertices/threads.d.mts

@@ -0,0 +1,33 @@
+import { VertexFactory } from "./util/vertex.mjs";
+import { Coalesced, EdgeWrapper, Plain, ThreadMessage } from "./util/edges.mjs";
+import "./util/index.mjs";
+import { UserVertex } from "./users.mjs";
+import { EventVertex } from "./events.mjs";
+
+//#region src/core/interfaces/vertices/threads.d.ts
+type State = {
+  view?: 'data-tables' | 'editor';
+  filter?: Record<string, string>;
+  selector: string;
+};
+type ThreadVertex = VertexFactory<'threads', {
+  source?: EdgeWrapper<'single', Coalesced.Edge<EventVertex>>;
+  state?: State;
+  messages: EdgeWrapper<'array', ThreadMessage.Edge<UserVertex, UserVertex, {
+    id: string;
+    content: string;
+    edited?: boolean;
+    createdAt?: string | Date;
+    updatedAt?: string | Date;
+  }>>;
+  taggedPersons?: EdgeWrapper<'array', Plain.Edge<UserVertex>>;
+  color?: string;
+  resolved?: boolean;
+  positionMeta?: {
+    x: number;
+    y: number;
+  };
+}>;
+//#endregion
+export { ThreadVertex };
+//# sourceMappingURL=threads.d.mts.map

package/dist/core/interfaces/vertices/users.d.mts

@@ -0,0 +1,11 @@
+import { VertexFactory } from "./util/vertex.mjs";
+import "./util/index.mjs";
+
+//#region src/core/interfaces/vertices/users.d.ts
+type UserVertex = VertexFactory<'users', {
+  username: string;
+  color?: string;
+}>;
+//#endregion
+export { UserVertex };
+//# sourceMappingURL=users.d.mts.map

package/dist/core/interfaces/vertices/util/common.d.mts

@@ -0,0 +1,28 @@
+import { Collection, OmitVertexProperties, PickVertexProperties, Vertex } from "./vertex.mjs";
+import { EdgeMultiplicity, EdgeWrapper } from "./edges.mjs";
+import { Tail } from "./util.mjs";
+
+//#region src/core/interfaces/vertices/util/common.d.ts
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+/**
+ * Picks all properties of a vertex that are edges to other vertices. (we ignore explicit any types)
+ */
+type PickEdges<V extends Vertex<Collection>> = { [K in keyof V as NonNullable<V[K]> extends EdgeWrapper<EdgeMultiplicity, any> ? IsAny<V[K]> extends true ? never : K : never]: V[K] };
+/**
+ * Omits all properties of a vertex that are edges to other vertices.
+ */
+type OmitEdges<V extends Vertex<Collection>> = PickVertexProperties<V> & OmitVertexProperties<{ [K in keyof V as NonNullable<V[K]> extends EdgeWrapper<EdgeMultiplicity, any> ? never : K]: V[K] }>;
+declare const SELECT_KEY = "select";
+type SelectKey = typeof SELECT_KEY;
+declare const EXPAND_KEY = "expand";
+type ExpandKey = typeof EXPAND_KEY;
+type InvalidEdgeMessage = 'INVALID VERTEX EDGE';
+type RemoveNeverValues<T extends object> = { [K in keyof T as T[K] extends never ? never : K]: T[K] };
+type DepthDecrementMap = [never, 0, 1, 2, 3];
+type SupportedDepths = DepthDecrementMap[number];
+type MaxDepth = Tail<DepthDecrementMap>;
+type MinDepth = Extract<SupportedDepths, 0>;
+type Decrement<T extends SupportedDepths> = DepthDecrementMap[T];
+//#endregion
+export { Decrement, EXPAND_KEY, ExpandKey, InvalidEdgeMessage, MaxDepth, MinDepth, OmitEdges, PickEdges, RemoveNeverValues, SELECT_KEY, SelectKey, SupportedDepths };
+//# sourceMappingURL=common.d.mts.map

package/dist/core/interfaces/vertices/util/custom-vertex-export/assert-no-invalid-expand-keys.d.mts

@@ -0,0 +1,16 @@
+import { Collection, Vertex } from "../vertex.mjs";
+import { DeepNonNullable } from "../util.mjs";
+import { ExpandKey } from "../common.mjs";
+import { VertexQuery } from "../vertex-query/index.mjs";
+import { Lookup } from "./util.mjs";
+
+//#region src/core/interfaces/vertices/util/custom-vertex-export/assert-no-invalid-expand-keys.d.ts
+type _AssertNoInvalidExpandKeys<Selected extends object, Available extends object> = { [K in keyof Selected]: K extends keyof Available ? Lookup<Selected[K], ExpandKey, false> extends infer a extends object ? Lookup<Available[K], ExpandKey, false> extends infer b extends object ? _AssertNoInvalidExpandKeys<a, b> : 'wtf!?' : never : `invalid expand key: ${K & string}` }[keyof Selected];
+/**
+ * Recursively asserts that all keys in the 'expand' section of Q are valid.
+ * If any invalid keys are found, a descriptive string literal type is returned, otherwise `unknown` is returned.
+ */
+type AssertNoInvalidExpandKeys<V extends Vertex<Collection>, Q extends VertexQuery<V>> = ExpandKey & keyof Q extends never ? unknown : [_AssertNoInvalidExpandKeys<DeepNonNullable<Q>[ExpandKey], DeepNonNullable<VertexQuery<V>>[ExpandKey]>] extends [infer T] ? [T] extends [never] ? unknown : T : never;
+//#endregion
+export { AssertNoInvalidExpandKeys };
+//# sourceMappingURL=assert-no-invalid-expand-keys.d.mts.map

package/dist/core/interfaces/vertices/util/custom-vertex-export/index.d.mts

@@ -0,0 +1,34 @@
+import { Collection, Vertex } from "../vertex.mjs";
+import { AvailableLocation, Coalesced, EdgeBase, EdgeWrapper, GroupWithExclude, Plain, ThreadMessage, Wrapped } from "../edges.mjs";
+import { ExtractNullish, Prettify, SetMultiplicity } from "../util.mjs";
+import { ExpandKey, OmitEdges, PickEdges } from "../common.mjs";
+import { KeysOf } from "../keys-of.mjs";
+import { VertexQuery } from "../vertex-query/index.mjs";
+import { ExtractChildKeys, ExtractChildObject, ExtractParentKeys, IntersectExpandSelectPath, Lookup, RelaxedPick } from "./util.mjs";
+import { AssertNoInvalidExpandKeys } from "./assert-no-invalid-expand-keys.mjs";
+
+//#region src/core/interfaces/vertices/util/custom-vertex-export/index.d.ts
+declare namespace HandleEdge {
+  type Recursion<V extends Vertex<Collection>, Query> = [Query] extends [never] ? string : Query extends VertexQuery<V> ? _CustomVertexExport<V, Query> : never;
+  export type Plain<E extends EdgeBase<any, any>, Query> = E extends Plain.Edge<infer V> ? Recursion<V, Query> : never;
+  export type Wrapped<E extends EdgeBase<any, any>, Query> = E extends Wrapped.Edge<infer K, infer V extends Vertex<Collection>, infer Extra extends object> ? Wrapped.Util.Value<K, Recursion<V, IntersectExpandSelectPath<Lookup<Query, K>, VertexQuery<V>>>, Extra> : never;
+  export type Coalesced<E extends EdgeBase<any, any>, Query> = E extends Coalesced.Edge<infer V, infer O, infer Extra extends object> ? V extends Vertex<Collection> ? Coalesced.Util.Value<Recursion<V, IntersectExpandSelectPath<Lookup<Query, Coalesced.Util.Keys.To>, VertexQuery<V>>>, Coalesced.Util.ToModel<V>, O, Extra> : never : never;
+  export type GroupWithExclude<E extends EdgeBase<any, any>, Query> = E extends GroupWithExclude.Edge<infer G extends Vertex<any>, infer P extends Vertex<any>, infer Extra extends object> ? GroupWithExclude.Util.Value<Recursion<G, IntersectExpandSelectPath<Lookup<Query, GroupWithExclude.Util.Keys.To>, VertexQuery<G>>>, Recursion<P, IntersectExpandSelectPath<Lookup<Query, GroupWithExclude.Util.Keys.Exclude>, VertexQuery<P>>>, Extra> : never;
+  export type AvailableLocation<E extends EdgeBase<any, any>, Query> = E extends AvailableLocation.Edge<infer L extends Vertex<any>, infer Extra extends object> ? AvailableLocation.Util.Value<Recursion<L, IntersectExpandSelectPath<Lookup<Query, AvailableLocation.Util.Keys.Locations>, VertexQuery<L>>>, Extra> : never;
+  export type ThreadMessage<E extends EdgeBase<any, any>, Query> = E extends ThreadMessage.Edge<infer U extends Vertex<Collection>, infer T extends Vertex<Collection>, infer Extra extends object> ? ThreadMessage.Util.Value<Recursion<U, IntersectExpandSelectPath<Lookup<Query, ThreadMessage.Util.Keys.User>, VertexQuery<U>>>, Recursion<T, IntersectExpandSelectPath<Lookup<Query, ThreadMessage.Util.Keys.TaggedPersons>, VertexQuery<T>>>, Extra> : never;
+  export {};
+}
+type _CustomVertexExport<V extends Vertex<Collection>, Q extends VertexQuery<V>> = Prettify<{ [K in keyof OmitEdges<V> as K extends KeysOf<V, Q> ? K : never]: V[K] } & { [K in keyof PickEdges<V> as K extends ExtractParentKeys<KeysOf<V, Q>> ? K : never]: [V[K]] extends [never] ? never : NonNullable<V[K]> extends EdgeWrapper<infer M, infer E extends EdgeBase<any, any> | null | undefined> ? (SetMultiplicity<Prettify<E extends EdgeBase<any, any> ? (HandleEdge.Plain<E, Lookup<Q[ExpandKey], K>> | RelaxedPick<HandleEdge.Wrapped<E, ExtractChildObject<Q[ExpandKey], K>> | HandleEdge.Coalesced<E, ExtractChildObject<Q[ExpandKey], K>> | HandleEdge.GroupWithExclude<E, ExtractChildObject<Q[ExpandKey], K>> | HandleEdge.AvailableLocation<E, ExtractChildObject<Q[ExpandKey], K>> | HandleEdge.ThreadMessage<E, ExtractChildObject<Q[ExpandKey], K>>, ExtractChildKeys<KeysOf<V, Q>, K>>) : E>, M> | ExtractNullish<V[K]>) : never }>;
+/**
+ * Recursively exports a Vertex type to a plain object structure,
+ * selecting and expanding properties and edges according to the provided expand/select path.
+ * - Non-edge properties are included based on selection.
+ * - Edge properties are exported and expanded according to their type (Plain, Coalesced, GroupWithExclude, AvailableLocation, ThreadMessage).
+ * - Handles edge multiplicity (single/array) and optional/null cases.
+ * - Invalid or unsupported edge unions are filtered out as `never`.
+ * - Supports dot-notation for nested property selection and expansion.
+ */
+type CustomVertexExport<V extends Vertex<Collection>, Q extends VertexQuery<V> & AssertNoInvalidExpandKeys<V, Q>> = _CustomVertexExport<V, Q>;
+//#endregion
+export { CustomVertexExport };
+//# sourceMappingURL=index.d.mts.map

package/dist/core/interfaces/vertices/util/custom-vertex-export/util.d.mts

@@ -0,0 +1,52 @@
+import { DeepNonNullable } from "../util.mjs";
+import { ExpandKey, SelectKey } from "../common.mjs";
+
+//#region src/core/interfaces/vertices/util/custom-vertex-export/util.d.ts
+/**
+ * Lookup type that returns the value type for key K in object Obj,
+ */
+type Lookup<Obj, K, ELSE = never> = K extends keyof Obj ? Obj[K] : ELSE;
+/**
+ * Intersect two expand/select specifications.
+ *
+ * - For the SelectKey ('select'): returns an array whose element type is the
+ *   intersection of the element types from A and B, preserving null/undefined from A.
+ * - For the ExpandKey ('expand'): keeps only keys present in both A and B and
+ *   recurses into their sub-specs.
+ * - Other keys are dropped.
+ *
+ * Useful to constrain a requested expand/select spec (A) by an allowed/spec (B),
+ * yielding only the common subset.
+ */
+type IntersectExpandSelectPath<A, B> = _IntersectExpandSelectPath<DeepNonNullable<A>, DeepNonNullable<B>>;
+type _IntersectExpandSelectPath<A, B> = [A] extends [never] ? never : { [K in keyof A & keyof B]: K extends SelectKey ? A[K] extends (infer V1)[] ? B[K] extends (infer V2)[] ? (V1 & V2)[] | Extract<A[K], null | undefined> : never : never : K extends ExpandKey ? { [S in keyof A[K] & keyof B[K]]: A[K][S] extends object ? B[K][S] extends object ? IntersectExpandSelectPath<A[K][S], B[K][S]> : never : never } : never };
+/**
+ * Extracts the parent keys from a set of dot-notation keys.
+ *
+ * @example
+ * Keys: 'a' | 'b.1' | 'c.2' | 'd'  =>  'a' | 'b' | 'c' | 'd'
+ */
+type ExtractParentKeys<Keys extends keyof any> = Keys extends `${infer B}.${string}` ? B : Keys;
+/**
+ * Extracts the child keys from a set of dot-notation keys, given a parent key.
+ *
+ * @example
+ * ParentKey: 'a'
+ * Keys:      'a' | 'a.1' | 'a.2' | 'b.1' | 'c'  =>  '1' | '2'
+ */
+type ExtractChildKeys<Keys extends keyof any, ParentKey extends string> = Keys extends `${ParentKey}.${infer K}` ? K : never;
+/**
+ * Extracts the child object from an object, given a parent key.
+ *
+ * @example
+ * ParentKey: 'a'
+ * Object:    { 'a': string; 'a.1': number; 'a.2': boolean; 'b.1': string; 'c': Date }  =>  { '1': number; '2': boolean }
+ */
+type ExtractChildObject<Object, ParentKey> = { [K in keyof Object as K extends `${ParentKey & string}.${infer S}` ? S : never]: Object[K] };
+/**
+ * Does the same as the built-in Pick<T, Keys>, but does not restrict the Keys to keyof T. Nullish and undefined values are preserved.
+ */
+type RelaxedPick<T extends object | null | undefined, Keys extends keyof any> = Extract<T, null | undefined> | (T extends object ? { [K in keyof NonNullable<T> as K extends Keys ? K : never]: NonNullable<T>[K] } : never);
+//#endregion
+export { ExtractChildKeys, ExtractChildObject, ExtractParentKeys, IntersectExpandSelectPath, Lookup, RelaxedPick };
+//# sourceMappingURL=util.d.mts.map

package/dist/core/interfaces/vertices/util/deep-vertex-export/index.d.mts

@@ -0,0 +1,65 @@
+import { Collection, IDKey, IDType, OmitInternalVertexKeys, PrivateIDKey, PrivateIDType, Vertex } from "../vertex.mjs";
+import { AvailableLocation, Coalesced, EdgeBase, EdgeWrapper, GroupWithExclude, Plain, ThreadMessage, Wrapped } from "../edges.mjs";
+import { ExtractNullish, Prettify, SetMultiplicity } from "../util.mjs";
+import { Decrement, MaxDepth, MinDepth, OmitEdges, PickEdges, SupportedDepths } from "../common.mjs";
+
+//#region src/core/interfaces/vertices/util/deep-vertex-export/index.d.ts
+type ExportOptions = {
+  mixed?: boolean;
+  optionalId?: boolean;
+  omitPrivateId?: boolean;
+};
+type IDTypes = IDType | PrivateIDType;
+declare namespace HandleEdge {
+  type Recursion<V extends Vertex<Collection>, D extends SupportedDepths, Opts extends ExportOptions> = _DeepVertexExport<V, Decrement<D>, Opts> | (Opts['mixed'] extends true ? IDTypes : never);
+  export type Plain<E extends EdgeBase<any, any>, D extends SupportedDepths, Opts extends ExportOptions> = E extends Plain.Edge<infer V> ? Recursion<V, D, Opts> : never;
+  export type Wrapped<E extends EdgeBase<any, any>, D extends SupportedDepths, Opts extends ExportOptions> = E extends Wrapped.Edge<infer K, infer V extends Vertex<any>, infer Extra extends object> ? Wrapped.Util.Value<K, Recursion<V, D, Opts>, Extra> : never;
+  export type Coalesced<E extends EdgeBase<any, any>, D extends SupportedDepths, Opts extends ExportOptions> = E extends Coalesced.Edge<infer V, infer O extends object, infer Extra extends object> ? V extends Vertex<Collection> ? Coalesced.Util.Value<Recursion<V, D, Opts>, Coalesced.Util.ToModel<V>, O, Extra> : never : never;
+  export type GroupWithExclude<E extends EdgeBase<any, any>, D extends SupportedDepths, Opts extends ExportOptions> = E extends GroupWithExclude.Edge<infer G extends Vertex<any>, infer P extends Vertex<any>, infer Extra extends object> ? GroupWithExclude.Util.Value<Recursion<G, D, Opts>, Recursion<P, D, Opts>, Extra> : never;
+  export type AvailableLocation<E extends EdgeBase<any, any>, D extends SupportedDepths, Opts extends ExportOptions> = E extends AvailableLocation.Edge<infer L extends Vertex<any>, infer Extra extends object> ? AvailableLocation.Util.Value<Recursion<L, D, Opts>, Extra> : never;
+  export type ThreadMessage<E extends EdgeBase<any, any>, D extends SupportedDepths, Opts extends ExportOptions> = E extends ThreadMessage.Edge<infer U extends Vertex<any>, infer T extends Vertex<any>, infer Extra extends object> ? ThreadMessage.Util.Value<Recursion<U, D, Opts>, Recursion<T, D, Opts>, Extra> : never;
+  export {};
+}
+type _MinDepthType = any;
+type TryPrettify<T> = 0 extends (1 & T) ? _MinDepthType : Prettify<T>;
+type InternalIdKeys = IDKey | PrivateIDKey;
+type PartialIf<T extends object, Condition extends boolean | undefined> = Condition extends true ? Partial<T> : T;
+type OmitPrivateIdIf<T extends object, Condition extends boolean | undefined> = Condition extends true ? Omit<T, PrivateIDKey> : T;
+type _DeepVertexExport<V extends Vertex<Collection>, D extends SupportedDepths, Opts extends ExportOptions> = D extends MinDepth ? _MinDepthType : Prettify<OmitPrivateIdIf<PartialIf<{ [K in keyof Pick<V, InternalIdKeys>]: V[K] }, Opts['optionalId']>, Opts['omitPrivateId']> & { [K in keyof Omit<OmitInternalVertexKeys<OmitEdges<V>>, InternalIdKeys>]: V[K] } & { [K in keyof PickEdges<V>]: [V[K]] extends [never] ? never : NonNullable<V[K]> extends EdgeWrapper<infer M, infer E extends EdgeBase<any, any> | null | undefined> ? (SetMultiplicity<TryPrettify<E extends EdgeBase<any, any> ? (HandleEdge.Plain<E, D, Opts> | HandleEdge.Wrapped<E, D, Opts> | HandleEdge.Coalesced<E, D, Opts> | HandleEdge.GroupWithExclude<E, D, Opts> | HandleEdge.AvailableLocation<E, D, Opts> | HandleEdge.ThreadMessage<E, D, Opts>) : E>, M> | ExtractNullish<V[K]>) : never }>;
+/**
+ * Recursively transforms a Vertex type into a deeply exported, plain object structure.
+ * - Non-edge properties are preserved as-is.
+ * - Edge properties are expanded according to their edge type (Plain, Coalesced, GroupWithExclude, AvailableLocation, ThreadMessage ).
+ * - Invalid or unsupported edge unions are filtered out as `never`.
+ * - Handles multiplicity (single/array) and optional/null edge cases.
+ * - There is a maximum recursion depth to increase performance.
+ * - Once the maximum depth is reached, all vertices are represented as `any`.
+ */
+type DeepVertexExport<V extends Vertex<Collection>> = _DeepVertexExport<V, MaxDepth, {
+  mixed: false;
+  optionalId: false;
+}>;
+/**
+ * Similar to {@link DeepVertexExport}, but each edge is represented as both the fully expanded object
+ * and the vertex ID (`string | ObjectId`).
+ */
+type MixedVertexExport<V extends Vertex<Collection>> = _DeepVertexExport<V, MaxDepth, {
+  mixed: true;
+  optionalId: false;
+}>;
+/**
+ * Similar to {@link MixedVertexExport}, but the ID fields (`_id` and `id`) are optional.
+ */
+type MixedWithOptionalIdVertexExport<V extends Vertex<Collection>> = _DeepVertexExport<V, MaxDepth, {
+  mixed: true;
+  optionalId: true;
+}>;
+/**
+ * Similar to {@link DeepVertexExport}, but omits the private ID field (`_id`) from the exported type.
+ */
+type DeepVertexExportOmitPrivateId<V extends Vertex<Collection>> = _DeepVertexExport<V, MaxDepth, {
+  omitPrivateId: true;
+}>;
+//#endregion
+export { DeepVertexExport, DeepVertexExportOmitPrivateId, MixedVertexExport, MixedWithOptionalIdVertexExport };
+//# sourceMappingURL=index.d.mts.map

package/dist/core/interfaces/vertices/util/edges.d.mts

@@ -0,0 +1,123 @@
+import { Collection, Vertex } from "./vertex.mjs";
+import { AllTrue, IsUnion, NoneIsUnion } from "./util.mjs";
+
+//#region src/core/interfaces/vertices/util/edges.d.ts
+declare const EDGE_TYPE_ID_KEY = "__edge_type_id";
+declare const EDGE_INVALID_KEY = "__invalid";
+declare const EDGE_VALUE_KEY = "__value";
+type EdgeValueKey = typeof EDGE_VALUE_KEY;
+type EdgeTypeIdValues = {
+  PLAIN: 'PLAIN';
+  WRAPPED: 'WRAPPED';
+  COALESCED: 'COALESCED';
+  GROUP_WITH_EXCLUDE: 'GROUP_WITH_EXCLUDE';
+  AVAILABLE_LOCATION: 'AVAILABLE_LOCATION';
+  THREAD_MESSAGE: 'THREAD_MESSAGE';
+};
+type EdgeTypeIdValue = (EdgeTypeIdValues)[keyof EdgeTypeIdValues];
+type EdgeBase<ID extends EdgeTypeIdValue, Invalid extends boolean> = {
+  [EDGE_TYPE_ID_KEY]: ID;
+  [EDGE_INVALID_KEY]: Invalid;
+};
+type EdgeIsValid<T extends EdgeBase<any, any>> = [T] extends [{
+  [EDGE_INVALID_KEY]: false;
+}] ? true : false;
+declare namespace Plain {
+  namespace Util {}
+  type Edge<V extends Vertex<Collection>> = EdgeBase<EdgeTypeIdValues['PLAIN'], NoneIsUnion<[V]> extends never ? true : false> & {
+    [EDGE_VALUE_KEY]: V;
+  };
+}
+declare namespace Wrapped {
+  namespace Util {
+    type Options<T extends string> = {
+      key: T;
+    };
+    type Value<K extends string, To, Extra = object> = Extra & { [k in K]: To };
+  }
+  type Edge<K extends string, V extends Vertex<Collection>, E extends object = object> = EdgeBase<EdgeTypeIdValues['WRAPPED'], NoneIsUnion<[K, V]> extends never ? true : false> & {
+    [EDGE_VALUE_KEY]: Util.Value<K, V, E>;
+  };
+}
+declare namespace Coalesced {
+  namespace Util {
+    export namespace Keys {
+      const TO = "to";
+      type To = typeof TO;
+      const TO_MODEL = "toModel";
+      type ToModel = typeof TO_MODEL;
+    }
+    export type Options = {
+      optional?: boolean;
+    };
+    type makePartial<T, O extends Options> = O extends {
+      optional: true;
+    } ? Partial<T> : T;
+    export type ToModel<V extends Vertex<Collection>> = V extends Vertex<infer C> ? C extends 'events' ? C | 'courseevents' : C : never;
+    export type Value<To, ToModel, Opts extends Util.Options = object, Extra = object> = Extra & makePartial<{
+      [Keys.TO]: To;
+      [Keys.TO_MODEL]: ToModel;
+    }, Opts>;
+    export {};
+  }
+  type Edge<V extends Vertex<Collection>, Opts extends Util.Options = object, E extends object = object> = EdgeBase<EdgeTypeIdValues['COALESCED'], NoneIsUnion<[V]> extends never ? true : false> & {
+    [EDGE_VALUE_KEY]: Util.Value<V, Util.ToModel<V>, Opts, E>;
+  };
+}
+declare namespace GroupWithExclude {
+  namespace Util {
+    namespace Keys {
+      const TO = "to";
+      type To = typeof TO;
+      const EXCLUDE = "exclude";
+      type Exclude = typeof EXCLUDE;
+    }
+    type Value<To, Exclude, Extra = object> = Extra & {
+      [Keys.TO]: To;
+      [Keys.EXCLUDE]?: Exclude[];
+    };
+  }
+  type Edge<G extends Vertex<Collection>, P extends Vertex<Collection>, E extends object = object> = EdgeBase<EdgeTypeIdValues['GROUP_WITH_EXCLUDE'], NoneIsUnion<[G, P]> extends never ? true : false> & {
+    [EDGE_VALUE_KEY]: Util.Value<G, P[], E>;
+  };
+}
+declare namespace AvailableLocation {
+  namespace Util {
+    namespace Keys {
+      const LOCATIONS = "locations";
+      type Locations = typeof LOCATIONS;
+    }
+    type Value<L, Extra = object> = Extra & {
+      [Keys.LOCATIONS]: [L];
+    };
+  }
+  type Edge<L extends Vertex<Collection>, E extends object = object> = EdgeBase<EdgeTypeIdValues['AVAILABLE_LOCATION'], NoneIsUnion<[L]> extends never ? true : false> & {
+    [EDGE_VALUE_KEY]: Util.Value<L, E>;
+  };
+}
+declare namespace ThreadMessage {
+  namespace Util {
+    namespace Keys {
+      const USER = "user";
+      type User = typeof USER;
+      const TAGGED_PERSONS = "taggedPersons";
+      type TaggedPersons = typeof TAGGED_PERSONS;
+    }
+    type Value<P, T, Extra = object> = Extra & {
+      [Keys.USER]: P;
+      [Keys.TAGGED_PERSONS]?: T[];
+    };
+  }
+  type Edge<P extends Vertex<Collection>, T extends Vertex<Collection>, E extends object = object> = EdgeBase<EdgeTypeIdValues['THREAD_MESSAGE'], NoneIsUnion<[P, T]> extends never ? true : false> & {
+    [EDGE_VALUE_KEY]: Util.Value<P, T, E>;
+  };
+}
+type AllowedEdgeType<T extends EdgeBase<EdgeTypeIdValue, boolean>> = IsUnion<T> extends never ? true : T extends Coalesced.Edge<any, any> ? true : false;
+type EdgeMultiplicity = 'single' | 'array';
+type EdgeWrapper<M extends EdgeMultiplicity, T extends EdgeBase<EdgeTypeIdValue, boolean> | null | undefined> = AllTrue<[AllowedEdgeType<NonNullable<T>>, EdgeIsValid<NonNullable<T>>]> extends false ? never : {
+  __edge_multiplicity: M;
+  __edge_type: T;
+};
+//#endregion
+export { AvailableLocation, Coalesced, EdgeBase, EdgeMultiplicity, EdgeValueKey, EdgeWrapper, GroupWithExclude, Plain, ThreadMessage, Wrapped };
+//# sourceMappingURL=edges.d.mts.map

package/dist/core/interfaces/vertices/util/index.d.mts

@@ -0,0 +1,6 @@
+import { Collection, PseudoCollection, RealCollection, Vertex, VertexFactory } from "./vertex.mjs";
+import { AvailableLocation, Coalesced, EdgeWrapper, GroupWithExclude, Plain, ThreadMessage, Wrapped } from "./edges.mjs";
+import { AssertNoInvalidExpandKeys } from "./custom-vertex-export/assert-no-invalid-expand-keys.mjs";
+import { CustomVertexExport } from "./custom-vertex-export/index.mjs";
+import { DeepVertexExport, MixedVertexExport, MixedWithOptionalIdVertexExport } from "./deep-vertex-export/index.mjs";
+import { SerializedVertexExport } from "./serialized-vertex-export.mjs";