8 KiB
| id | title |
|---|---|
| scheduling | Dependencies & Scheduling |
eventDependencyFeature links events into a graph. When one event moves, the ones that depend on
it move with it, and a move that cannot be carried through is rejected as a whole. See
ADR 0007
for why the solver is a stage of the write pipeline from
ADR 0001
and not a separate reactive engine.
Setup
import { calendarFeatures, createCalendar, eventDependencyFeature } from '@tanstack/time'
import type { Event } from '@tanstack/time'
const events: Array<Event> = [
{ id: 'design', title: 'Design', start: '2026-10-05T09:00:00', end: '2026-10-05T12:00:00' },
{
id: 'build',
title: 'Build',
start: '2026-10-05T13:00:00',
end: '2026-10-05T17:00:00',
dependsOn: [{ id: 'design', type: 'FS', lag: 60 }],
},
]
const calendar = createCalendar({
features: calendarFeatures([eventDependencyFeature]),
timeZone: 'Europe/Warsaw',
viewMode: { value: 1, unit: 'week' },
events,
})
eventDependencyFeature is also part of stockFeatures.
Links
A link lives on the successor. dependsOn[].id is the predecessor:
interface EventDependency {
id: string
type: DependencyType
lag?: number
}
| Type | Rule |
|---|---|
FS |
successor start ≥ predecessor end + lag |
SS |
successor start ≥ predecessor start + lag |
FF |
successor end ≥ predecessor end + lag |
SF |
successor end ≥ predecessor start + lag |
lag is in minutes and defaults to 0. A negative lag is a lead: { type: 'FS', lag: -30 }
lets the successor start half an hour before the predecessor ends.
Every rule is a lower bound. Moving a predecessor earlier leaves its successors where they are. The solver closes gaps that break a rule. It never compacts slack.
Propagation on write
Every write that changes an event's start or end runs the schedule stage before validation:
- The events you moved are fixed for this write. So is every event with
manuallyScheduled: true. - A broken link with a free successor pushes the successor forward.
- A broken link with a fixed successor pulls the predecessor backward.
- Shifts keep each event's length and continue through the whole chain, to a fixed point.
calendar.commitUpdate('design', { end: '2026-10-05T14:00:00' })
calendar.getEvents().find((event) => event.id === 'build')?.start
build now starts at 15:00: design ends at 14:00, plus the 60-minute lag.
The shifted events join the same write batch. The availability, constraint and duration validate
stages then check every event in the batch. If one cascaded event lands in unavailable time or
breaks its constraint, the whole write is rejected, including the event you moved. With historyFeature, one
undo reverts the whole cascade.
The calendar's schedule stage moves events by wall-clock time. It does not skew a pushed event
across non-working time and it does not clamp to constraints. A cascade into a closed hour is
rejected, not snapped to the next working minute.
Manually scheduled events
manuallyScheduled: true makes an event an anchor. Propagation never moves it:
const result = await calendar.editEvent('design', {
start: '2026-10-05T12:00:00',
end: '2026-10-05T15:00:00',
})
if (!result.success) {
console.log(result.error.message)
}
If build is manually scheduled, this is rejected with
"Build" cannot start before "Design" ends +60m (FS) — "Build" is manually scheduled. Nothing
moves. A move that the anchor still has slack for is allowed.
You can still move an anchor directly. It pushes its free dependents like any other event.
Use editEvent, not commitUpdate
commitUpdate returns nothing. A vetoed write is dropped silently. editEvent returns a
SaveEventResult and runs validateMove first, so the error tells you which event blocked the
move and why:
- a manually scheduled event would have to move,
- the moved event breaks its own constraint or declared duration,
- a pulled predecessor or pushed dependent would land in unavailable time, or break its constraint or duration.
Creating links
const result = calendar.createDependency('design', 'build', 'SS', 30)
if (result.blocked) {
console.log(result.error?.message)
}
createDependency(sourceId, targetId, type?, lag?) adds sourceId as a predecessor of
targetId. type defaults to 'FS'. If the target breaks the new rule, it moves forward by the
shortfall in the same write. The call returns { blocked: true, error } when:
sourceId === targetId, or the source already depends on the target, directly or indirectly,- the target is manually scheduled and would have to move,
- the target's new position fails
validateMove. Theerror.reasonis'unavailable-time'.
Adding a link that already exists with the same type and lag is a no-op. The same pair with a different type is a second link.
If either id is unknown, the call returns { blocked: false } and does nothing.
Cycles
createDependency refuses cycles. Links you load through events or write with commitUpdate
are not checked. When the data already has a cycle, the solver skips the links inside the cycle
and propagates the rest. You get no error. The solver has an iteration cap, so a cycle can not
make a write hang.
Checking before you commit
All of these are read-only. newStart and newEnd are plain date-time strings in the calendar's
timeZone.
calendar.validateEventDependencies(
{ title: 'Review', start: '2026-10-05T10:00:00', end: '2026-10-05T11:00:00' },
[{ id: 'design', type: 'FS' }],
)
validateEventDependencies(event, dependsOn) returns { valid, error? } for the first broken
link. It skips unknown predecessor ids and does not check for cycles. addEvent and editEvent
call it when you pass options.dependsOn, but that option is only a check. The links are
stored only when they are also in the event's own dependsOn.
findViolatedDependency(event, proposedStartMs, proposedEndMs) checks only the event's own links
against a span in epoch milliseconds. It returns { dependency, predecessor } or null. The
resize feature uses it.
getAnchorConflicts(eventId, newStart, newEnd) runs the same pull and push as a real move. It
returns the links that touch a manually scheduled event and are still broken:
const [conflict] = calendar.getAnchorConflicts(
'design',
'2026-10-05T12:00:00',
'2026-10-05T15:00:00',
)
conflict?.anchorId
Each entry has eventId, eventTitle, predecessorId, predecessorTitle, type, message,
originalStart, originalEnd and anchorId. validateMove checks this first.
The preview methods return Array<DependencyShift<TEvent>>, where each item is
{ event, newStart, newEnd }:
| Method | Previews |
|---|---|
getDependentShifts(eventId, newStart, newEnd) |
successors pushed forward by the new span |
getPredecessorShifts(eventId, newStart, newEnd) |
predecessors pulled back by the new span |
getAffectedByDelta(eventId, deltaMs) |
successors pushed when the event moves by deltaMs |
Previews are geometry only. They skip manually scheduled events and do not check availability,
constraints or duration. Use validateMove for the full answer.
Not covered
The pure solve core also supports ASAP/ALAP direction, working-time skew and constraint clamping
(ADR 0007). It is not exported from @tanstack/time, and the calendar's schedule stage does not
use those options yet. Solver conflicts are not returned to you. You only get the veto from the
validate stages. See Working time and Features.