Refactor: split runtime state (#1725)

* refactor: runtime types

* refactor: runtimeState functions to use the split type

* refactor: RuntimeService to use the new split data

* refactor: use the split data in the UI

* update comments

* refactor: rename runtime to offset

* fix utils test
This commit is contained in:
Alex Christoffer Rasmussen
2025-08-14 19:29:25 +02:00
committed by Carlos Valente
parent ed93cf313a
commit 048a9c96ea
26 changed files with 400 additions and 518 deletions
+102 -129
View File
@@ -1,6 +1,4 @@
import {
GroupState,
UpcomingEntry,
isOntimeEvent,
MaybeNumber,
MaybeString,
@@ -10,10 +8,11 @@ import {
PlayableEvent,
Playback,
Rundown,
Runtime,
Offset,
runtimeStorePlaceholder,
TimerPhase,
TimerState,
RundownState,
} from 'ontime-types';
import {
calculateDuration,
@@ -36,13 +35,13 @@ type ExpectedMetadata = { event: OntimeEvent; accumulatedGap: number; isLinkedTo
export type RuntimeState = {
clock: number; // realtime clock
groupNow: GroupState | null;
groupNext: MaybeString;
nextFlag: UpcomingEntry | null;
groupNow: OntimeGroup | null;
eventNow: PlayableEvent | null;
eventNext: PlayableEvent | null;
runtime: Runtime;
eventFlag: PlayableEvent | null;
offset: Offset;
timer: TimerState;
rundown: RundownState;
// private properties of the timer calculations
_timer: {
forceFinish: MaybeNumber; // whether we should declare an event as finished, will contain the finish time
@@ -61,12 +60,12 @@ export type RuntimeState = {
const runtimeState: RuntimeState = {
clock: timeNow(),
groupNow: null,
groupNext: null,
nextFlag: null,
eventNow: null,
eventNext: null,
runtime: { ...runtimeStorePlaceholder.runtime },
eventFlag: null,
offset: { ...runtimeStorePlaceholder.offset },
timer: { ...runtimeStorePlaceholder.timer },
rundown: { ...runtimeStorePlaceholder.rundown },
_timer: {
forceFinish: null,
pausedAt: null,
@@ -87,7 +86,10 @@ export function getState(): Readonly<RuntimeState> {
...runtimeState,
eventNow: runtimeState.eventNow ? { ...runtimeState.eventNow } : null,
eventNext: runtimeState.eventNext ? { ...runtimeState.eventNext } : null,
runtime: { ...runtimeState.runtime },
eventFlag: runtimeState.eventFlag ? { ...runtimeState.eventFlag } : null,
groupNow: runtimeState.groupNow ? { ...runtimeState.groupNow } : null,
offset: { ...runtimeState.offset },
rundown: { ...runtimeState.rundown },
timer: { ...runtimeState.timer },
_timer: { ...runtimeState._timer },
_rundown: { ...runtimeState._rundown },
@@ -101,13 +103,16 @@ export function clearEventData() {
runtimeState.eventNow = null;
runtimeState.eventNext = null;
runtimeState.runtime.offsetAbs = 0;
runtimeState.runtime.offsetRel = 0;
runtimeState.runtime.expectedEnd = null;
runtimeState.runtime.selectedEventIndex = null;
runtimeState.offset.absolute = 0;
runtimeState.offset.relative = 0;
runtimeState.offset.expectedFlagStart = null;
runtimeState.rundown.selectedEventIndex = null;
//TODO: is there any ExpectedMetadata stuff we need to clear here
if (runtimeState.groupNow) runtimeState.groupNow.expectedEnd = null;
runtimeState.offset.expectedGroupEnd = null;
runtimeState.offset.expectedFlagStart = null;
runtimeState.offset.expectedRundownEnd = null;
runtimeState.timer.playback = Playback.Stop;
runtimeState.clock = timeNow();
@@ -124,20 +129,22 @@ export function clearEventData() {
export function clearState() {
runtimeState.eventNow = null;
runtimeState.eventNext = null;
runtimeState.groupNow = null;
runtimeState.groupNext = null;
runtimeState._group = null;
runtimeState.nextFlag = null;
runtimeState.eventFlag = null;
runtimeState._flag = null;
runtimeState.runtime.offsetAbs = 0;
runtimeState.runtime.offsetRel = 0;
runtimeState.runtime.actualStart = null;
runtimeState.runtime.expectedEnd = null;
runtimeState.groupNow = null;
runtimeState._group = null;
runtimeState.rundown.actualStart = null;
runtimeState.rundown.selectedEventIndex = null;
runtimeState.offset.absolute = 0;
runtimeState.offset.relative = 0;
runtimeState.offset.expectedRundownEnd = null;
runtimeState.offset.expectedGroupEnd = null;
runtimeState.offset.expectedFlagStart = null;
runtimeState._end = null;
runtimeState.runtime.selectedEventIndex = null;
runtimeState.timer.playback = Playback.Stop;
runtimeState.clock = timeNow();
@@ -168,25 +175,23 @@ function patchTimer(newState: Partial<TimerState & RestorePoint>) {
}
}
type RundownData = {
/**
* Utility, allows updating data derived from the rundown
* @param playableRundown
*/
export function updateRundownData(rundownData: {
numEvents: number; // length of rundown filtered for timed events
firstStart: MaybeNumber;
lastEnd: MaybeNumber;
totalDelay: number;
totalDuration: number;
};
/**
* Utility, allows updating data derived from the rundown
* @param playableRundown
*/
export function updateRundownData(rundownData: RundownData) {
}) {
// we keep this in private state since there is no UI use case for it
runtimeState._rundown.totalDelay = rundownData.totalDelay;
runtimeState.runtime.numEvents = rundownData.numEvents;
runtimeState.runtime.plannedStart = rundownData.firstStart;
runtimeState.runtime.plannedEnd =
runtimeState.rundown.numEvents = rundownData.numEvents;
runtimeState.rundown.plannedStart = rundownData.firstStart;
runtimeState.rundown.plannedEnd =
rundownData.firstStart === null ? null : rundownData.firstStart + rundownData.totalDuration;
getExpectedTimes();
}
@@ -222,22 +227,19 @@ export function load(
runtimeState.timer.playback = Playback.Armed;
runtimeState.timer.duration = calculateDuration(event.timeStart, event.timeEnd);
runtimeState.timer.current = getCurrent(runtimeState);
runtimeState.runtime.numEvents = metadata.timedEventOrder.length;
runtimeState.rundown.numEvents = metadata.timedEventOrder.length;
// patch with potential provided data
if (initialData) {
patchTimer(initialData);
const firstStart = initialData?.firstStart;
if (firstStart === null || typeof firstStart === 'number') {
runtimeState.runtime.actualStart = firstStart;
const { offsetAbs, offsetRel } = getRuntimeOffset(runtimeState);
runtimeState.runtime.offsetAbs = offsetAbs;
runtimeState.runtime.offsetRel = offsetRel;
runtimeState.rundown.actualStart = firstStart;
const { absolute, relative } = getRuntimeOffset(runtimeState);
runtimeState.offset.absolute = absolute;
runtimeState.offset.relative = relative;
getExpectedTimes();
}
if (typeof initialData.groupStartAt === 'number' && runtimeState.groupNow) {
runtimeState.groupNow.startedAt = initialData.groupStartAt;
}
}
return event.id === runtimeState.eventNow?.id;
}
@@ -248,17 +250,17 @@ export function load(
export function loadNow(
rundown: Rundown,
metadata: RundownMetadata,
eventIndex: MaybeNumber = runtimeState.runtime.selectedEventIndex,
eventIndex: MaybeNumber = runtimeState.rundown.selectedEventIndex,
) {
if (eventIndex === null) {
// reset the state to indicate there is no selection
runtimeState.runtime.selectedEventIndex = null;
runtimeState.rundown.selectedEventIndex = null;
runtimeState.eventNow = null;
return;
}
const event = rundown.entries[metadata.timedEventOrder[eventIndex]] as PlayableEvent;
runtimeState.runtime.selectedEventIndex = eventIndex;
runtimeState.rundown.selectedEventIndex = eventIndex;
runtimeState.eventNow = event;
}
@@ -268,7 +270,7 @@ export function loadNow(
export function loadNext(
rundown: Rundown,
metadata: RundownMetadata,
eventIndex: MaybeNumber = runtimeState.runtime.selectedEventIndex,
eventIndex: MaybeNumber = runtimeState.rundown.selectedEventIndex,
) {
if (eventIndex === null) {
// reset the state to indicate there is no future event
@@ -314,7 +316,7 @@ export function updateLoaded(event?: PlayableEvent): string | undefined {
// handle edge cases with roll
if (runtimeState.timer.playback === Playback.Roll) {
const offsetClock = runtimeState.clock - runtimeState.runtime.offsetAbs;
const offsetClock = runtimeState.clock - runtimeState.offset.absolute;
// if waiting to roll, we update the targets and potentially start the timer
if (runtimeState._timer.secondaryTarget !== null) {
if (runtimeState.eventNow.timeStart < offsetClock && offsetClock < runtimeState.eventNow.timeEnd) {
@@ -358,13 +360,6 @@ export function updateAll(rundown: Rundown, metadata: RundownMetadata) {
loadNext(rundown, metadata, eventNowIndex >= 0 ? eventNowIndex : undefined);
updateLoaded(runtimeState.eventNow ?? undefined);
loadGroupFlagAndEnd(rundown, metadata, eventNowIndex);
// catch the edge case where the playing event is moved into a group
// if the group already has a start value then we dont overwrite it
// use the start value from the timer, so if the we are not running it will be set to null
if (runtimeState.groupNow && runtimeState.groupNow.startedAt === null) {
runtimeState.groupNow.startedAt = runtimeState.timer.startedAt;
}
}
export function start(state: RuntimeState = runtimeState): boolean {
@@ -389,31 +384,26 @@ export function start(state: RuntimeState = runtimeState): boolean {
state.timer.startedAt = state.clock;
}
// update group start time
if (state.groupNow && state.groupNow.startedAt === null) {
state.groupNow.startedAt = state.clock;
}
state.timer.playback = Playback.Play;
state.timer.expectedFinish = getExpectedFinish(state);
state.timer.elapsed = 0;
if (state.runtime.actualStart === null) {
state.runtime.actualStart = state.clock;
if (state.rundown.actualStart === null) {
state.rundown.actualStart = state.clock;
}
// update timer phase
runtimeState.timer.phase = getTimerPhase(runtimeState);
// update offset
const { offsetAbs, offsetRel } = getRuntimeOffset(runtimeState);
runtimeState.runtime.offsetAbs = offsetAbs;
runtimeState.runtime.offsetRel = offsetRel;
const { absolute, relative } = getRuntimeOffset(runtimeState);
runtimeState.offset.absolute = absolute;
runtimeState.offset.relative = relative;
// as long as there is a timer, we need an planned end
// eslint-disable-next-line no-unused-labels -- dev code path
DEV: {
if (state.runtime.plannedEnd === null) {
if (state.rundown.plannedEnd === null) {
throw new Error('runtimeState.start: invalid state received');
}
}
@@ -477,9 +467,9 @@ export function addTime(amount: number) {
runtimeState.timer.current += amount;
// update runtime delays: over - under
const { offsetAbs, offsetRel } = getRuntimeOffset(runtimeState);
runtimeState.runtime.offsetAbs = offsetAbs;
runtimeState.runtime.offsetRel = offsetRel;
const { absolute, relative } = getRuntimeOffset(runtimeState);
runtimeState.offset.absolute = absolute;
runtimeState.offset.relative = relative;
getExpectedTimes();
return true;
@@ -524,9 +514,9 @@ export function update(): UpdateResult {
runtimeState.timer.elapsed = runtimeState.timer.duration - runtimeState.timer.current;
// update runtime, needs up-to-date timer state
const { offsetAbs, offsetRel } = getRuntimeOffset(runtimeState);
runtimeState.runtime.offsetAbs = offsetAbs;
runtimeState.runtime.offsetRel = offsetRel;
const { absolute, relative } = getRuntimeOffset(runtimeState);
runtimeState.offset.absolute = absolute;
runtimeState.offset.relative = relative;
const finishedNow =
Boolean(runtimeState._timer.forceFinish) ||
@@ -556,7 +546,7 @@ export function update(): UpdateResult {
}
// account for offset
const offsetClock = runtimeState.clock + runtimeState.runtime.offsetAbs;
const offsetClock = runtimeState.clock + runtimeState.offset.absolute;
runtimeState.timer.phase = TimerPhase.Pending;
if (hasCrossedMidnight) {
@@ -576,7 +566,7 @@ export function roll(
offset = 0,
): { eventId: MaybeString; didStart: boolean } {
// 1. if an event is running, we simply take over the playback
if (runtimeState.timer.playback === Playback.Play && runtimeState.runtime.selectedEventIndex !== null) {
if (runtimeState.timer.playback === Playback.Play && runtimeState.rundown.selectedEventIndex !== null) {
runtimeState.timer.playback = Playback.Roll;
return { eventId: runtimeState.eventNow?.id ?? null, didStart: false };
}
@@ -590,7 +580,7 @@ export function roll(
}
}
runtimeState.runtime.offsetAbs = offset;
runtimeState.offset.absolute = offset;
runtimeState.timer.playback = Playback.Roll;
// account for event that finishes the day after
@@ -601,7 +591,7 @@ export function roll(
runtimeState.timer.expectedFinish = normalisedEndTime;
//account for offset
const offsetClock = runtimeState.clock - runtimeState.runtime.offsetAbs;
const offsetClock = runtimeState.clock - runtimeState.offset.absolute;
// state catch up
runtimeState.timer.duration = calculateDuration(runtimeState.eventNow.timeStart, normalisedEndTime);
@@ -613,12 +603,8 @@ export function roll(
if (isNow) {
runtimeState.timer.startedAt = runtimeState.clock;
// update runtime
if (runtimeState.groupNow && runtimeState.groupNow.startedAt === null) {
runtimeState.groupNow.startedAt = runtimeState.clock;
}
if (!runtimeState.runtime.actualStart) {
runtimeState.runtime.actualStart = runtimeState.clock;
if (runtimeState.rundown.actualStart === null) {
runtimeState.rundown.actualStart = runtimeState.clock;
}
runtimeState.timer.secondaryTimer = null;
} else {
@@ -639,8 +625,8 @@ export function roll(
clearEventData();
//account for offset but we only keep it if passed to us
runtimeState.runtime.offsetAbs = offset;
const offsetClock = runtimeState.clock - runtimeState.runtime.offsetAbs;
runtimeState.offset.absolute = offset;
const offsetClock = runtimeState.clock - runtimeState.offset.absolute;
const { index, isPending } = loadRoll(rundown, metadata, offsetClock);
@@ -651,7 +637,7 @@ export function roll(
// update roll state
runtimeState.timer.playback = Playback.Roll;
runtimeState.runtime.numEvents = metadata.timedEventOrder.length;
runtimeState.rundown.numEvents = metadata.timedEventOrder.length;
// in roll mode spec, there should always be something to load
// as long as playableEvents is not empty
@@ -676,12 +662,6 @@ export function roll(
}
// there is something to run, load event
// update runtime
if (runtimeState.groupNow && runtimeState.groupNow.startedAt === null) {
runtimeState.groupNow.startedAt = runtimeState.clock;
}
// event will finish on time
// account for event that finishes the day after
const endTime =
@@ -700,25 +680,26 @@ export function roll(
runtimeState.timer.elapsed = 0;
// update runtime
runtimeState.runtime.actualStart = runtimeState.clock;
runtimeState.rundown.actualStart = runtimeState.clock;
return { eventId: runtimeState.eventNow.id, didStart: true };
}
/**
* calculates and sets values directly in state
* - runtime.expectedEnd
* - groupNow.expectedEnd
* - nextFlag.expectedStart
* - offset.expectedRundownEnd
* - offset.expectedGroupEnd
* - offset.expectedFlagStart
*/
function getExpectedTimes(state = runtimeState) {
const { offsetMode, offsetAbs, offsetRel, plannedStart, actualStart } = state.runtime;
const { offset } = state;
const { plannedStart, actualStart } = state.rundown;
const { eventNow } = state;
if (!eventNow) return;
state.runtime.expectedEnd = null;
state.offset.expectedRundownEnd = null;
if (state.groupNow) {
state.groupNow.expectedEnd = null;
state.offset.expectedGroupEnd = null;
const { _group } = state;
if (_group !== null) {
const { event: lastEvent, accumulatedGap, isLinkedToLoaded } = _group;
@@ -726,17 +707,17 @@ function getExpectedTimes(state = runtimeState) {
currentDay: eventNow.dayOffset,
totalGap: accumulatedGap,
isLinkedToLoaded,
offsetMode,
offset: offsetMode === OffsetMode.Absolute ? offsetAbs : offsetRel,
mode: offset.mode,
offset: offset.mode === OffsetMode.Absolute ? offset.absolute : offset.relative,
plannedStart,
actualStart,
});
state.groupNow.expectedEnd = lastEventExpectedStart + lastEvent.duration;
state.offset.expectedGroupEnd = lastEventExpectedStart + lastEvent.duration;
}
}
if (state.nextFlag) {
state.nextFlag.expectedStart = null;
if (state.eventFlag) {
state.offset.expectedFlagStart = null;
const { _flag } = state;
if (_flag) {
const { event, accumulatedGap, isLinkedToLoaded } = _flag;
@@ -744,12 +725,12 @@ function getExpectedTimes(state = runtimeState) {
currentDay: eventNow.dayOffset,
totalGap: accumulatedGap,
isLinkedToLoaded,
offsetMode,
offset: offsetMode === OffsetMode.Absolute ? offsetAbs : offsetRel,
mode: offset.mode,
offset: offset.mode === OffsetMode.Absolute ? offset.absolute : offset.relative,
plannedStart,
actualStart,
});
state.nextFlag.expectedStart = expectedStart;
state.offset.expectedFlagStart = expectedStart;
}
}
@@ -759,14 +740,14 @@ function getExpectedTimes(state = runtimeState) {
currentDay: eventNow.dayOffset,
totalGap: accumulatedGap,
isLinkedToLoaded,
offsetMode,
offset: offsetMode === OffsetMode.Absolute ? offsetAbs : offsetRel,
mode: offset.mode,
offset: offset.mode === OffsetMode.Absolute ? offset.absolute : offset.relative,
plannedStart,
actualStart,
});
state.runtime.expectedEnd = expectedStart + event.duration;
state.offset.expectedRundownEnd = expectedStart + event.duration;
} else {
state.runtime.expectedEnd = null;
state.offset.expectedRundownEnd = null;
}
}
@@ -790,7 +771,6 @@ export function loadGroupFlagAndEnd(
// if we don't have a any flags in the rundown then no need to look for it
let foundFlag = !flagsPresent;
let foundNextGroup = false;
// if we don't have a last event for the group there is no need to find its end time
let foundGroupEnd = lastEventInGroup === null;
@@ -809,7 +789,7 @@ export function loadGroupFlagAndEnd(
// and the loaded event is not allowed to be the next flag
if (!foundFlag && metadata.flags.includes(entry.id)) {
foundFlag = true;
state.nextFlag = { id: entry.id, expectedStart: null };
state.eventFlag = entry as PlayableEvent; // we know it is playable as it is coming from the playableEventOrder list
state._flag = { event: entry, isLinkedToLoaded, accumulatedGap };
}
}
@@ -818,11 +798,6 @@ export function loadGroupFlagAndEnd(
foundGroupEnd = true;
state._group = { event: lastEventInGroup, isLinkedToLoaded, accumulatedGap };
}
if (!foundNextGroup && entry.parent !== currentGroupId) {
foundNextGroup = true;
state.groupNext = entry.parent;
}
}
}
@@ -832,26 +807,24 @@ export function loadGroupFlagAndEnd(
state._end = { event: lastEvent, isLinkedToLoaded, accumulatedGap };
}
if (!foundFlag) state.nextFlag = null;
if (!foundFlag) state.eventFlag = null;
if (currentGroupId === null) {
state.groupNow = null;
} else if ((state.groupNow != null && state.groupNow.id != currentGroupId) || state.groupNow == null) {
if ((state.groupNow?.id ?? null) !== currentGroupId) {
// we went into a new group - and it is different from the one we might have come from
// the id is set here, the start time is set when starting events
state.groupNow = { id: currentGroupId, startedAt: null, expectedEnd: null };
state.offset.expectedGroupEnd = null;
}
state.groupNow = currentGroupId ? (entries[currentGroupId] as OntimeGroup) : null;
}
const resetMetaData = (state = runtimeState) => {
state.groupNow = null;
state.groupNext = null;
state._group = null;
state.nextFlag = null;
state.eventFlag = null;
state._flag = null;
state._end = null;
};
export function setOffsetMode(mode: OffsetMode) {
runtimeState.runtime.offsetMode = mode;
runtimeState.offset.mode = mode;
}