refactor: UI for linking events (#763)

packages/utils/src/validate-events/validateEvent.test.ts

@@ -1,8 +1,7 @@
 import { EndAction, TimerType } from 'ontime-types';
 import { expect } from 'vitest';
 
-import { dayInMs } from '../timeConstants.js';
-import { calculateDuration, validateEndAction, validateTimerType, validateTimes } from './validateEvent.js';
+import { validateEndAction, validateTimerType } from './validateEvent.js';
 
 describe('validateEndAction()', () => {
   it('recognises a string representation of an action', () => {
@@ -29,90 +28,3 @@ describe('validateTimerType()', () => {
     expect(invalidType).toBe(TimerType.CountDown);
   });
 });
-
-describe('validateTimes()', () => {
-  it('passes through a well defined time list', () => {
-    const { timeStart, timeEnd, duration } = validateTimes(5, 10, 5);
-    expect(timeStart).toBe(5);
-    expect(timeEnd).toBe(10);
-    expect(duration).toBe(5);
-  });
-
-  it('handles cases when no times are given', () => {
-    const { timeStart, timeEnd, duration } = validateTimes(null, undefined, null);
-    expect(timeStart).toBe(0);
-    expect(timeEnd).toBe(0);
-    expect(duration).toBe(0);
-  });
-
-  it('calculates duration', () => {
-    const { timeStart, timeEnd, duration } = validateTimes(5, 10);
-    expect(timeStart).toBe(5);
-    expect(timeEnd).toBe(10);
-    expect(duration).toBe(5);
-  });
-
-  it('calculates end time', () => {
-    const { timeStart, timeEnd, duration } = validateTimes(5, undefined, 10);
-    expect(timeStart).toBe(5);
-    expect(timeEnd).toBe(15);
-    expect(duration).toBe(10);
-  });
-
-  it('handles events that finish the day after', () => {
-    const { timeStart, timeEnd, duration } = validateTimes(100, 10);
-    expect(timeStart).toBe(100);
-    expect(timeEnd).toBe(10);
-    expect(duration).toBe(dayInMs - 90);
-  });
-
-  it('corrects time in case of conflicts', () => {
-    const { timeStart, timeEnd, duration } = validateTimes(5, 15, 15);
-    expect(timeStart).toBe(5);
-    expect(timeEnd).toBe(15);
-    expect(duration).toBe(10);
-  });
-
-  it('calculates start time', () => {
-    const { timeStart, timeEnd, duration } = validateTimes(undefined, 15, 10);
-    expect(timeStart).toBe(5);
-    expect(timeEnd).toBe(15);
-    expect(duration).toBe(10);
-  });
-
-  it('calculates start and end time', () => {
-    const { timeStart, timeEnd, duration } = validateTimes(undefined, undefined, 10);
-    expect(timeStart).toBe(0);
-    expect(timeEnd).toBe(10);
-    expect(duration).toBe(10);
-  });
-
-  it('ensures values are integers', () => {
-    const { timeStart, timeEnd, duration } = validateTimes(0.000001, 10.312335342, 10);
-    expect(timeStart).toBe(0);
-    expect(timeEnd).toBe(10);
-    expect(duration).toBe(10);
-  });
-});
-
-describe('calculateDuration()', () => {
-  describe('Given start and end values', () => {
-    it('is the difference between end and start', () => {
-      const duration = calculateDuration(10, 20);
-      expect(duration).toBe(10);
-    });
-  });
-
-  describe('Handles edge cases', () => {
-    it('handles events that go over midnight', () => {
-      const duration = calculateDuration(51, 50);
-      expect(duration).toBe(dayInMs - 1);
-    });
-    it('handles no difference', () => {
-      const duration1 = calculateDuration(0, 0);
-      const duration2 = calculateDuration(dayInMs, dayInMs);
-      expect(duration1).toBe(0);
-      expect(duration2).toBe(0);
-    });
-  });
-});

packages/utils/src/validate-events/validateEvent.ts

@@ -1,6 +1,24 @@
-import { EndAction, TimerType } from 'ontime-types';
+import { EndAction, MaybeString, TimerType, TimeStrategy } from 'ontime-types';
 
-import { dayInMs } from '../timeConstants.js';
+/**
+ * Check if a given value is a valid type of string, returns null otherwise
+ * @param {MaybeString} maybeLinkStart
+ * @returns {MaybeString}
+ */
+export function validateLinkStart(maybeLinkStart: unknown): MaybeString {
+  return typeof maybeLinkStart === 'string' ? maybeLinkStart : null;
+}
+
+/**
+ * Check if a given value is a valid time strategy, returns the fallback otherwise
+ * @param {TimeStrategy} maybeTimeStrategy
+ * @returns {TimeStrategy}
+ */
+export function validateTimeStrategy(maybeTimeStrategy: unknown, fallback = TimeStrategy.LockDuration): TimeStrategy {
+  return Object.values(TimeStrategy).includes(maybeTimeStrategy as TimeStrategy)
+    ? (maybeTimeStrategy as TimeStrategy)
+    : fallback;
+}
 
 /**
  * Checks if given value is a valid type of EndAction, returns the fallback otherwise
@@ -23,71 +41,3 @@ export function validateTimerType(maybeTimerType: unknown, fallback = TimerType.
 export function isKnownTimerType(maybeTimerType: unknown) {
   return Object.values(TimerType).includes(maybeTimerType as TimerType);
 }
-
-/**
- * @description calculates event duration considering midnight
- * @param {number} timeStart
- * @param {number} timeEnd
- * @returns {number}
- */
-export const calculateDuration = (timeStart: number, timeEnd: number): number => {
-  // Durations must be positive
-  if (timeEnd < timeStart) {
-    return timeEnd + dayInMs - timeStart;
-  }
-  return timeEnd - timeStart;
-};
-
-/**
- * Converts a given value to an int, returns 0 otherwise
- * @param value
- * number
- */
-function convertToInteger(value: unknown): number {
-  const result = Number(value);
-  return isNaN(result) ? 0 : Math.floor(result);
-}
-
-/**
- * Ensures the time input variables are valid in relationship to each other
- * Infers values if necessary
- * @param _start
- * @param _end
- * @param _duration
- */
-export function validateTimes(
-  _start?: unknown,
-  _end?: unknown,
-  _duration?: unknown,
-): { timeStart: number; duration: number; timeEnd: number } {
-  const timeStart = convertToInteger(_start);
-  const timeEnd = convertToInteger(_end);
-  const duration = convertToInteger(_duration);
-
-  if (_start != null && _end != null) {
-    // Case 1. if we have start and end, duration must be derived
-    return { timeStart, duration: calculateDuration(timeStart, timeEnd), timeEnd };
-  }
-
-  if (_start == null && _end == null) {
-    if (_duration == null) {
-      // Case 2. no valid times were given
-      return { timeStart, duration, timeEnd };
-    }
-    // Case 3. we have a duration and infer the rest
-    return { timeStart, duration, timeEnd: duration };
-  }
-
-  if (_start != null) {
-    // Case 5. with only start, we can calculate the rest
-    return { timeStart, duration, timeEnd: timeStart + duration };
-  }
-
-  if (_end != null) {
-    // Case 6. with only end, we can calculate the rest
-    return { timeStart: timeEnd - duration, duration, timeEnd };
-  }
-
-  // we should have covered all cases
-  return { timeStart, duration, timeEnd };
-}

packages/utils/src/validate-times/validateTimes.test.ts

@@ -0,0 +1,190 @@
+import { OntimeEvent, TimeStrategy } from 'ontime-types';
+
+import { dayInMs } from '../timeConstants';
+import { calculateDuration, getLinkedTimes, validateTimes } from './validateTimes';
+
+describe('validateTimes()', () => {
+  describe('when time strategy is inferred', () => {
+    it('passes through a well defined time list', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(5, 10, 5);
+      expect(timeStart).toBe(5);
+      expect(timeEnd).toBe(10);
+      expect(duration).toBe(5);
+      expect(timeStrategy).toBe(TimeStrategy.LockDuration);
+    });
+
+    it('handles cases when no times are given', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(null, undefined, null);
+      expect(timeStart).toBe(0);
+      expect(timeEnd).toBe(0);
+      expect(duration).toBe(0);
+      expect(timeStrategy).toBe(TimeStrategy.LockDuration);
+    });
+
+    it('calculates duration', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(5, 10, undefined);
+      expect(timeStart).toBe(5);
+      expect(timeEnd).toBe(10);
+      expect(duration).toBe(5);
+      expect(timeStrategy).toBe(TimeStrategy.LockEnd);
+    });
+
+    it('calculates end time', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(5, undefined, 10);
+      expect(timeStart).toBe(5);
+      expect(timeEnd).toBe(15);
+      expect(duration).toBe(10);
+      expect(timeStrategy).toBe(TimeStrategy.LockDuration);
+    });
+
+    it('handles events that finish the day after', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(100, 10, undefined);
+      expect(timeStart).toBe(100);
+      expect(timeEnd).toBe(10);
+      expect(duration).toBe(dayInMs - 90);
+      expect(timeStrategy).toBe(TimeStrategy.LockEnd);
+    });
+
+    it('corrects time in case of conflicts', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(5, 15, 15);
+      expect(timeStart).toBe(5);
+      expect(timeEnd).toBe(15);
+      expect(duration).toBe(10);
+      expect(timeStrategy).toBe(TimeStrategy.LockDuration);
+    });
+
+    it('calculates start time', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(undefined, 15, 10);
+      expect(timeStart).toBe(5);
+      expect(timeEnd).toBe(15);
+      expect(duration).toBe(10);
+      expect(timeStrategy).toBe(TimeStrategy.LockDuration);
+    });
+
+    it('calculates start and end time', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(undefined, undefined, 10);
+      expect(timeStart).toBe(0);
+      expect(timeEnd).toBe(10);
+      expect(duration).toBe(10);
+      expect(timeStrategy).toBe(TimeStrategy.LockDuration);
+    });
+
+    it('ensures values are integers', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(0.000001, 10.312335342, 10);
+      expect(timeStart).toBe(0);
+      expect(timeEnd).toBe(10);
+      expect(duration).toBe(10);
+      expect(timeStrategy).toBe(TimeStrategy.LockDuration);
+    });
+    it('prevents values from overflowing', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(dayInMs - 5, undefined, 10);
+      expect(timeStart).toBe(dayInMs - 5);
+      expect(timeEnd).toBe(5);
+      expect(duration).toBe(10);
+      expect(timeStrategy).toBe(TimeStrategy.LockDuration);
+    });
+  });
+  describe('when time strategy is given', () => {
+    it('calculates end', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(5, 20, 20, TimeStrategy.LockDuration);
+      expect(timeStart).toBe(5);
+      expect(timeEnd).toBe(25);
+      expect(duration).toBe(20);
+      expect(timeStrategy).toBe(TimeStrategy.LockDuration);
+    });
+    it('calculates duration', () => {
+      const { timeStart, timeEnd, duration, timeStrategy } = validateTimes(5, 20, 20, TimeStrategy.LockEnd);
+      expect(timeStart).toBe(5);
+      expect(timeEnd).toBe(20);
+      expect(duration).toBe(15);
+      expect(timeStrategy).toBe(TimeStrategy.LockEnd);
+    });
+  });
+});
+
+describe('calculateDuration()', () => {
+  describe('Given start and end values', () => {
+    it('is the difference between end and start', () => {
+      const duration = calculateDuration(10, 20);
+      expect(duration).toBe(10);
+    });
+  });
+
+  describe('Handles edge cases', () => {
+    it('handles events that go over midnight', () => {
+      const duration = calculateDuration(51, 50);
+      expect(duration).toBe(dayInMs - 1);
+    });
+    it('handles no difference', () => {
+      const duration1 = calculateDuration(0, 0);
+      const duration2 = calculateDuration(dayInMs, dayInMs);
+      expect(duration1).toBe(0);
+      expect(duration2).toBe(0);
+    });
+  });
+});
+
+describe('getLinkedTimes()', () => {
+  it('returns times with lock end', () => {
+    const source = {
+      timeStart: 5,
+      timeEnd: 15,
+      duration: 10,
+    } as OntimeEvent;
+    const target = {
+      timeStart: 10,
+      timeEnd: 20,
+      duration: 10,
+      timeStrategy: TimeStrategy.LockEnd,
+    } as OntimeEvent;
+
+    const timePatch = getLinkedTimes(target, source);
+    expect(timePatch).toStrictEqual({
+      timeStart: 15,
+      timeEnd: 20,
+      duration: 5,
+    });
+  });
+
+  it('returns times with lock duration', () => {
+    const source = {
+      timeStart: 5,
+      timeEnd: 15,
+      duration: 10,
+    } as OntimeEvent;
+    const target = {
+      timeStart: 10,
+      timeEnd: 20,
+      duration: 10,
+      timeStrategy: TimeStrategy.LockDuration,
+    } as OntimeEvent;
+
+    const timePatch = getLinkedTimes(target, source);
+    expect(timePatch).toStrictEqual({
+      timeStart: 15,
+      timeEnd: 25,
+      duration: 10,
+    });
+  });
+
+  it('prevents overflow', () => {
+    const source = {
+      timeStart: 5,
+      timeEnd: dayInMs - 5,
+      duration: 10,
+    } as OntimeEvent;
+    const target = {
+      timeStart: 0,
+      timeEnd: 20,
+      duration: 10,
+      timeStrategy: TimeStrategy.LockDuration,
+    } as OntimeEvent;
+
+    const timePatch = getLinkedTimes(target, source);
+    expect(timePatch).toStrictEqual({
+      timeStart: dayInMs - 5,
+      timeEnd: 5,
+      duration: 10,
+    });
+  });
+});

packages/utils/src/validate-times/validateTimes.ts

@@ -0,0 +1,129 @@
+import { OntimeEvent, TimeStrategy } from 'ontime-types';
+
+import { dayInMs } from '../timeConstants.js';
+import { validateTimeStrategy } from '../validate-events/validateEvent.js';
+
+export function getLinkedTimes(
+  target: OntimeEvent,
+  source: OntimeEvent,
+): { timeStart: number; duration: number; timeEnd: number } {
+  const lockEnd = target.timeStrategy === TimeStrategy.LockEnd;
+  const lockDuration = target.timeStrategy === TimeStrategy.LockDuration;
+  const newStart = source.timeEnd;
+
+  const timePatch = {
+    timeStart: newStart,
+    timeEnd: lockEnd ? target.timeEnd : calculateEnd(newStart, target.duration),
+    duration: lockDuration ? target.duration : calculateDuration(newStart, target.timeEnd),
+  };
+
+  return timePatch;
+}
+
+function inferTimes(
+  _start?: unknown,
+  _end?: unknown,
+  _duration?: unknown,
+): { timeStart: number; duration: number; timeEnd: number; timeStrategy: TimeStrategy } {
+  const timeStart = convertToInteger(_start);
+  const timeEnd = convertToInteger(_end);
+  const duration = convertToInteger(_duration);
+
+  // TODO: prevent overflow
+
+  if (_start != null && _end != null) {
+    // Case 1. if we have start and end, duration must be derived
+    return {
+      timeStart,
+      duration: calculateDuration(timeStart, timeEnd),
+      timeEnd,
+      timeStrategy: _duration != null ? TimeStrategy.LockDuration : TimeStrategy.LockEnd,
+    };
+  }
+
+  if (_start == null && _end == null) {
+    if (_duration == null) {
+      // Case 2. no valid times were given
+      return { timeStart: 0, duration: 0, timeEnd: 0, timeStrategy: TimeStrategy.LockDuration };
+    }
+    // Case 3. we have a duration and infer the rest
+    return { timeStart, duration, timeEnd: duration, timeStrategy: TimeStrategy.LockDuration };
+  }
+
+  if (_start != null) {
+    // Case 5. with only start, we can calculate the rest
+    return { timeStart, duration, timeEnd: (timeStart + duration) % dayInMs, timeStrategy: TimeStrategy.LockDuration };
+  }
+
+  if (_end != null) {
+    // Case 6. with only end, we can calculate the rest
+    return {
+      timeStart: timeEnd - duration,
+      duration,
+      timeEnd,
+      timeStrategy: _duration != null ? TimeStrategy.LockDuration : TimeStrategy.LockEnd,
+    };
+  }
+
+  // we should have covered all cases
+  return { timeStart, duration, timeEnd, timeStrategy: TimeStrategy.LockDuration };
+}
+
+/**
+ * Ensures the time input variables are valid in relationship to each other
+ * Infers values if necessary
+ * @param _start
+ * @param _end
+ * @param _duration
+ */
+export function validateTimes(
+  _start?: unknown,
+  _end?: unknown,
+  _duration?: unknown,
+  _strategy?: TimeStrategy,
+): { timeStart: number; duration: number; timeEnd: number; timeStrategy: TimeStrategy } {
+  if (_strategy == null) {
+    // if no strategy is given we infer it from given parameters
+    return inferTimes(_start, _end, _duration);
+  }
+
+  const timeStrategy = validateTimeStrategy(_strategy);
+  const timeStart = convertToInteger(_start);
+  let timeEnd = convertToInteger(_end);
+  let duration = convertToInteger(_duration);
+
+  if (timeStrategy === TimeStrategy.LockEnd) {
+    duration = calculateDuration(timeStart, timeEnd);
+  } else {
+    timeEnd = calculateEnd(timeStart, duration);
+  }
+  return { timeStart, duration, timeEnd, timeStrategy };
+}
+
+/**
+ * @description calculates event duration considering midnight
+ * @param {number} timeStart
+ * @param {number} timeEnd
+ * @returns {number}
+ */
+export function calculateDuration(timeStart: number, timeEnd: number): number {
+  // Durations must be positive
+  if (timeEnd < timeStart) {
+    return timeEnd + dayInMs - timeStart;
+  }
+  return timeEnd - timeStart;
+}
+
+export function calculateEnd(timeStart: number, duration: number): number {
+  return (timeStart + duration) % dayInMs;
+}
+
+/**
+ * Converts a given value to an int, returns 0 otherwise
+ * @param value
+ * number
+ */
+function convertToInteger(value: unknown): number {
+  const result = Number(value);
+  return isNaN(result) ? 0 : Math.floor(result);
+}