Skip to main content

Availability Governor

import { availabilityGovernor } from 'tods-competition-factory';
// or, with the AvailabilityEngine: the `availability` namespace re-exports every module below
import { availability } from 'tods-competition-factory';

The availabilityGovernor is the pure utility layer under the Availability Engine: the algorithms and translations the engine is built from, exported so they can be used without an engine instance. It holds no state and mutates nothing except where a function is explicitly a writer (applyAvailabilityToTournamentRecord).

Court availability works in the inverted paradigm: a court is available unless a block says otherwise, and overlapping blocks resolve to non-overlapping segments by type precedence. See Block Types and Algorithms for the model; this page maps each module's exports to where they are described.

Most applications use the AvailabilityEngine, which calls these for you.


Types and constants​

BLOCK_TYPES (also a top-level export) and the engine's types: blocks, rail segments, timelines, capacity points, plan items, conflicts. → Block Types, Block Interface


Rail derivation​

Converts overlapping blocks into non-overlapping rail segments with a sweep line, resolving each segment's status by type precedence.

exportwhat it does
deriveRailSegmentsthe sweep: blocks to non-overlapping segments for a court-day
mergeAdjacentSegmentsjoins neighbouring segments with the same status
validateSegmentschecks a rail is ordered, non-overlapping and within its day
resolveStatusthe winning status among overlapping block types
buildEdges, sortEdgesthe sweep's edge list
clampToDayRange, buildDayRange, extractDayday bounds
rangesOverlap, overlappingRange, diffMinutesinterval arithmetic
courtKey, courtDayKey, venueKey, venueDayKey, resolveCourtId, resolveVenueIdthe keys rails and timelines are indexed by

→ Rail Derivation Algorithm, Rail Derivation Functions


Capacity curves​

Time series of how many courts are available, soft-blocked or hard-blocked at each point of a day.

exportwhat it does
generateCapacityCurve(day, timelines)the curve for one day, from the venues' day timelines
calculateCapacityStatspeak, minimum and average availability (with their times), total court-hours and utilization
filterCapacityCurvethe curve within a time range
sampleCapacityCurvethe curve at a fixed interval
compareCapacityCurves(baseline, modified)the per-time differences between two curves, e.g. before and after a change

→ Capacity Curves


Collision detection​

Collision-aware clamping for drag-to-create, so a new block stops at its neighbours instead of overlapping them.

exportwhat it does
clampDragToCollisionsclamps a dragged range against the court's existing blocks
intervalsOverlap, timeInsideBlock, findBlocksContainingTime, sortBlocksByStartthe checks it is built from

→ Collision Detection, clampDragToCollisions


Conflict evaluators​

Pluggable checks that inspect a proposed block mutation and return conflicts with a severity.

exportwhat it does
defaultEvaluatorsthe built-in set, as passed to AvailabilityEngine.init
courtOverlapEvaluator, matchWindowEvaluator, adjacentBlockEvaluator, lightingEvaluator, blockDurationEvaluator, dayBoundaryEvaluator, maintenanceWindowEvaluatorthe built-in evaluators, usable individually
EvaluatorRegistrya registry of evaluators: register, unregister, get, getAll, clear
createFollowByEvaluatora placeholder for player-rest and follow-by conflicts: it returns no conflicts yet
groupConflictsBySeverity, getHighestSeverity, formatConflictssummarising a set of conflicts

→ Conflict Evaluators, Built-in Evaluators, Custom Evaluator Example


Time granularity​

The one authority for snapping and converting times, in place of ad hoc slot lengths.

exportwhat it does
snapToGranularity, snapIsoToGranularitysnap minutes, or an ISO time, to the granularity
hhmmToMinutes, minutesToHhmm'HH:MM' and minutes since midnight

→ Time Granularity


Plan state​

exportwhat it does
computePlanItemId(item)the id of a scheduling plan item, from its key fields: day|venueId|eventId[|drawId]|R{roundNumber}. Two items with the same key fields share an id, which is what makes adding one replace the other

→ Plan State


Validation pipeline​

exportwhat it does
runValidationPipelinevalidates a scheduling plan against engine state in ordered phases, collecting rule results with severity and fix actions

→ Validation Pipeline


CODES bridge​

The only place availability structures meet CODES (TODS) structures.

exportwhat it does
railsToDateAvailabilityrails to a court's CODES dateAvailability
todsAvailabilityToBlocksCODES availability to blocks
applyAvailabilityToTournamentRecordwrites derived availability into a tournament record
buildSchedulingProfileFromUISelectionsa scheduling profile from plan selections
validateSchedulingProfileFormat, validateDateAvailabilityshape checks for both
mergeOverlappingAvailability, calculateCourtHoursutilities

→ CODES Bridge