Event Governor
Some methods on this page are candidates for removal from production engine exports at the 8.0.0 boundary. Their implementation references have moved: categoryCanContain, getEligibleEvents, removeScaleValues, validateCategory. Existing 7.x routes remain available; final decisions and external-integrator confirmations are tracked in the transition index.
import { eventGovernor } from 'tods-competition-factory';
addDrawDefinition
Adds a drawDefinition to an event in a tournamentRecord. Called after generateDrawDefinition. See examples: Complete Example, Creating Draws from Flight Profiles, Complete Example.
A draw whose entries exceed a matched sanction's maxWildcards (WILDCARD entries) or maxAlternates (ALTERNATE entries) is refused before anything is stored, with { error: NO_STAGE_SPACE_AVAILABLE_FOR_ENTRY_STATUS, context: { entryStatus, stage, limit, count, participantIds } }, where participantIds are the entries beyond the limit. AD_HOC draws, unsanctioned events and events the constraints do not match are unaffected.
When more than one of the constraints' events matches the event, the first in their list applies. The limits are checked WILDCARD first, then ALTERNATE, and for each status stage by stage in the order the draw's entries first name the stage (MAIN when an entry states none); the refusal names the first limit exceeded, with info '<entryStatus> entries exceed the sanctioned limit'. A participant entered twice in one stage with the same status counts once. The check comes after the entries are validated against the flight and before the existing-drawId check (DRAW_ID_EXISTS).
A drawDefinition built outside the factory may not carry the progression links between its matchUps (winnerMatchUpId, loserMatchUpId). They are derived from its structures and links and stored with the draw, as generateDrawDefinition would have stored them. A draw with a malformed round link is stored as it was.
const { drawDefinition, error } = engine.generateDrawDefinition(drawDefinitionValues);
if (!error) {
const result = engine.addDrawDefinition({
modifyEventEntries, // event.entries[{entryStatus}] are modified to match draw.entries[{entryStatus}]
existingDrawCount, // number of draws that exist in the event, used to check that two clients don't attempt to add simultaneously
allowReplacement, // optional - defaults to false
checkEntryStatus, // optional - defualts to false
drawDefinition,
eventId,
flight, // optional - pass flight definition object for integrity check
});
}
addEvent
Add an event object to a tournamentRecord. See examples in Creating Events, Age Validation Examples, Complete Example, Using Categories in Events, newTournamentRecord, and 1 more.
engine.addEvent({
event, // required — event object (eventId auto-generated if absent)
suppressNotifications, // optional boolean — suppress event/matchUp notices
});
The event object may include:
eventId— optional, auto-generated UUID if not providedeventName— display nameeventType— defaults toSINGLES_EVENT; useTEAM_EVENTfor team competitionstieFormat— required for TEAM events (validated), or usetieFormatNameto select a presettieFormatName— optional — selects a built-in tieFormat by name (e.g.'COLLEGE_DEFAULT')startDate,endDate— optional, default to tournament datescategory,gender,matchUpFormat— optional event metadata
When called via the public engine API (not internalUse), event.entries and event.drawDefinitions must be empty or absent — they are rejected with INVALID_VALUES. Use addEventEntries and addDrawDefinition separately.
addFlight
Adds one flight to the event's flight profile, numbered after the highest existing flight, without changing the other flights or their draws.
A participant who is already in another flight, or in a draw (every draw counts as a flight), is still added, but the
result carries a warning: { code: PARTICIPANT_IN_OTHER_FLIGHT, info: { participantIds } } (flightConstants). From
8.0.0 such a call is refused unless force: true is given.
engine.addFlight({
drawEntries, // optional
drawName,
eventId,
drawId, // optional -- if scenario involves client and server side tournamentEngines, provide { drawId: UUID() }
stage,
});
assignSeedPositions
Assign seedNumbers to participantIds within a target draw structure.
- Provides the ability to assign seeding after a structure has been generated
- To be used before participants are positioned
seedNumber is unique while seedValue can be any string representation, e.g "5-8"
engine.assignSeedPositions({
assignments, // [{ seedNumber: 1, seedValue: '1', participantId: 'pid' }];
structureId,
eventId,
drawId,
useExistingSeedLimit, // optional; restrict ability to assign seedNumbers beyond established limit
});
attachFlightProfile
Attaches a flightProfile to the event specified by eventId. A flightProfile is first generated with generateFlightProfile().
engine.attachFlightProfile({ flightProfile, eventId });
categoryCanContain
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to categoryCanContain. Package-export status is a separate decision.
deleteDrawDefinitions
Remove drawDefinitions from an event. An audit timeItem is added to the tournamentRecord whenever this method is called. If autoPublish: true (default behavior) then if a deleted draw was published then the event to which it belongs will be re-published. See examples: Resolving Events from Draw IDs.
engine.deleteDrawDefinitions({
autoPublish, // optional - defaults to true.
eventDataParams, // optional - params to pass to `getEventData` for regeneration of remaining draws
auditData, // object with attributes to be added to drawDeletions extension
drawIds: [drawId],
eventId,
force, // boolean - override error when scores present
});
deleteEvents
engine.deleteEvents({ eventIds });
deleteFlightAndFlightDraw
Removes flight from event flightProfile as well as associated drawDefinition (if generated). See examples: Delete Individual Flight.
engine.deleteFlightAndFlightDraw({
autoPublish, // optional - defaults to true.
auditData, // object with attributes to be added to drawDeletions extension
eventId,
drawId,
force, // boolean - override error when scores present
});
deleteFlightProfileAndFlightDraws
Removes flightProfiles and all associated drawDefinitions from a specified event. See examples: Delete Entire Flight Profile.
engine.deleteFlightProfileAndFlightDraws({
auditData, // object with attributes to be added to drawDeletions extension
eventId,
force, // boolean - override error when scores present
});
getCategoryAgeDetails
Parses ageCategoryCode to determine min/max eligible birthdates and min/max age. Category age/birthdate boundaries can be specified using other attributes.
If attributes are combined will sanity check correspondence and return an array of any encountered errors.
const {
consideredDate, // returns either supplied value or date when invoked
combinedAge, // boolean indicating that ageMax and ageMin are combined values
ageMaxDate,
ageMinDate,
ageMax,
ageMin,
errors,
} = engine.getCategoryAgeDetails({
consideredDate, // optional - date string 'YYYY-MM-DD'; defaults to current date
category: {
ageCategoryCode, // CODES code, e.g. 'U18', '18U', '18O', 'O18', '8O-U18', 'C50-70'
categoryName, // when no ageCategoryCode is provided, an attempt is made to find in categoryName
ageMaxDate, // latest/most recent date acceptable for eligibilty
ageMinDate, // earliest date acceptable for eligibility
ageMax, // maximum age acceptable for eligibility
ageMin, // minimum age acceptable for eligibility
},
});
generateEventsFromTieFormat
Generates multiple events from a tieFormat definition, typically for team competitions.
const { events } = engine.generateEventsFromTieFormat({
tieFormat, // required, or tieFormatName
tieFormatName, // a named tie format from tieFormatConstants, instead of tieFormat
category, // optional
gender, // optional
});
Purpose: Automatically create event structure for team competitions from tieFormat.
A tieFormatName the catalogue does not hold is refused with INVALID_VALUES. Earlier releases accepted any non-empty
name and built the STANDARD tie format for one they did not know.
getEligibleEvents
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to getEligibleEvents. Package-export status is a separate decision.
getEvent
Returns a single event object with optional context and drawDefinition.
const { event, drawDefinition } = engine.getEvent({
eventId, // required
drawId, // optional - also return specific drawDefinition
context, // optional - additional properties to add
});
While deep copy is enabled (the default) event and drawDefinition are deep copies: modifying them does not modify engine state, so make changes through engine methods, by id. With setDeepCopy(false) they are the live objects held in state.
getEventProperties
Returns the scale values (seed, ranking, rating) of each participant entered in an event, and whether any entered participant has one. Scale values are read for the event's eventType and its category's categoryName (or ageCategoryCode).
const { entryScaleAttributes, hasSeededParticipants, hasRankedParticipants, hasRatedParticipants } =
engine.getEventProperties({
eventId, // required
});
// entryScaleAttributes: [{ participantId, participantName, seed, ranking, rating }]
getEventStructures
Returns all structures across all draws in an event.
const { structures } = engine.getEventStructures({ eventId });
getEventTimeItem
Returns time items attached to an event.
const { timeItem } = engine.getEventTimeItem({
eventId, // required
itemType, // required - time item type
});
getEvents
Returns all events from the tournament.
const { events } = engine.getEvents({ context });
getFlightProfile
Returns the event's flight profile (event.flightProfile, or the legacy extension), as a copy whose flights carry any draw already generated from them. See getFlightProfile for the shape.
const { flightProfile } = engine.getFlightProfile({ eventId });
Purpose: Access flight configuration for events split into multiple draws.
getParticipantEligibility
Whether a participant may enter an event — asked, rather than attempted.
const { eligible, indeterminate, rejectionReasons, undeterminedRestrictions } = engine.getParticipantEligibility({
participant,
event,
tournamentRecord, // optional
});
The predicate itself is not new — validateParticipantCategory has evaluated age at both event ends, handled exact-DOB and calendar-year conventions, and expanded ageCategoryCode since it was written. It was reachable only through addEventEntries, so the one way to learn whether someone could enter was to try to enter them. A discovery surface evaluating one person against thousands of events cannot use a mutation.
Read-only: emits no notices and mutates nothing.
indeterminate is not eligible: false. The first says a rule could not be evaluated (an unknown birthDate, an unrecorded rating); the second says a rule was breached. Indeterminate applies only when nothing was actually breached — a participant both over the age limit and missing a rating is ineligible, full stop.
This does not change who gets entered. addEventEntries keeps its behaviour exactly: a participant whose birthDate is unknown is still filtered out of the entry list there, while here the same participant reports indeterminate. "We cannot tell" is correctly a refusal when writing an entry and correctly not a refusal when answering a question.
undeterminedRestrictions carries entryRestrictions the record cannot settle — residency, membership, clearance — so a consumer can say "this event is closed to your section, check with the organiser" instead of a flat no or a misleading yes. See Entry Eligibility.
getScaledEntries
Returns event entries with their scale values (rankings, ratings).
const { scaledEntries } = engine.getScaledEntries({
eventId, // required
scaleAttributes, // optional
stage, // optional
});
modifyEvent
event.modifyEvent({
eventUpdates: {
eventGender, // optional - must validate against current event entries, if any
eventType, // optional - must validate against current event entries, if any
eventName, // optional
startDate, // optional - must fall within tournament dates
category, // optional - must validate against current event entries, if any
endDate, // optional - must fall within tournament dates
entryProfile, // optional - merged into event.entryProfile; null clears it (see below)
},
eventId,
});
entryProfile states how the event accepts entries, and how many — the way a director sets it when
there is no sanctioning step to carry the sizes in. It is merged key by key into the existing
profile, so an edit that names only the sizes keeps what it does not show (selectionProcess,
extensions, ...). A key set to null removes it; entryProfile: null clears the whole profile, as
does removing its last key. The merged profile is validated as stored, and an invalid one is refused
with INVALID_VALUES, leaving the event unchanged.
engine.modifyEvent({
eventId,
eventUpdates: {
entryProfile: {
entriesLimit, // optional - how many entries the event accepts
targetDrawSize, // optional - intended MAIN draw size before a draw exists
qualifyingDrawSize, // optional - the simple case: one qualifying draw of this size
qualifiersCount, // optional - how many qualifiers enter MAIN; must be fewer than qualifyingDrawSize
qualifyingProfiles, // optional - [{ roundTarget, structureProfiles: [{ stageSequence, drawSize, qualifyingPositions }] }]
wildcardCount, // optional - MAIN places held for wildcards
selectionProcess, // optional - SelectionProcessEnum value
selectionScaleName, // optional - which scale orders acceptance
waitlistEnabled, // optional boolean
},
},
});
qualifyingProfilesstates multi-structure qualifying (pre-qualifying withstageSequence1 and 2, or several structures feeding different MAIN rounds) and mirrors the draw generator's input of the same name. It replacesqualifyingDrawSizeandqualifiersCount: a profile carrying both is refused, so switching shapes takes nulling the simple keys in the same call.- Sizes are positive whole numbers (
qualifiersCountandwildcardCountmay be 0); qualifier and wildcard places together may not exceedtargetDrawSize; a structure profile'squalifyingPositionsmust be fewer than itsdrawSize.
modifyEventMatchUpFormatTiming
Overrides the average and/or recovery minutes of a matchUpFormat for one event, stored in the event's
SCHEDULE_TIMING extension.
engine.modifyEventMatchUpFormatTiming({
recoveryMinutes,
averageMinutes,
matchUpFormat,
eventId,
});
The override is keyed by the event's category: category.categoryName, else category.ageCategoryCode, else the
event's own eventId when it has no category. Every reader resolves the same key (getMatchUpFormatTiming,
getEventMatchUpFormatTiming and the auto-schedulers), so an event with no category is scheduled by its override and
other events stay on the policy.
The minutes are stored under the event's type (minutes: { [eventType]: n }). For a TEAM event that is TEAM; its
SINGLES and DOUBLES lines read the TEAM minutes when they state none for their own type, so the override times every
line of the event that plays the format.
modifyPairAssignment
Modifies an individualParticipantId within a PAIR particiapnt entered into an event or draw. Will clean up (delete) any PAIR participants that are not entered into any other draws or events.
engine.modifyPairAssignment({
replacementIndividualParticipantId,
existingIndividualParticipantId,
participantId,
eventId, // optional if drawId is provided
drawId, // optional if eventId is provided; scopes change to specified draw
uuids, // optional array of uuids for use when generating new participant
});
modifyTieFormat
Both modifies the tieFormat on the target event, drawDefinition, structure or matchUp and adds/deletes tieMatchUps as necessary.
engine.modifyTieFormat({
considerations, // optional { collectionName?: boolean; collectionOrder?: boolean };
modifiedTieFormat, // will be compared to existing tieFormat that is targeted and differences calculated
structureId, // required if modifying tieFormat for a structure
matchUpId, // required if modifying tieFormat for a matchUp
eventId, // required if modifying tieFormat for a event
drawId, // required if modifying tieFormat for a drawDefinition or a structure
});
promoteAlternates
Promotes alternates to direct acceptance in the order given, each placed after the accepted entries. See entries governor: promoteAlternates for positions, draws and flights.
engine.promoteAlternates({
participantIds, // in order of acceptance
// either drawId or eventId are REQUIRED
eventId, // optional if drawId provided
drawId, // optional if eventId provided
});
refreshEventDrawOrder
Renumbers the event's display order (drawOrder) to 1..n without gaps, for example after a draw or a flight has been
deleted. Flights come first, each placed by its draw's drawOrder, else its own drawOrder, else its flightNumber;
draws that have no flight follow, by drawOrder. A flight's flightNumber is never changed.
engine.refreshEventDrawOrder({ eventId });
removeEventEntries
Removes event.entries with integrity checks.
Filters participantIds by specified entryStatuses and/or stage. If no participantIds are provided, removes all entries that match both entryStatuses and stage.
engine.removeEventEntries({
autoEntryPositions, // optional - keeps entries ordered by entryStage/entryStatus and auto-increments
participantIds, // optional array of participantIds to remove
entryStatuses, // optional array of entryStatuses to remove
stage, // optional - remove entries for specified stage
eventId,
});
removeEventMatchUpFormatTiming
Removes the event's timing overrides (its SCHEDULE_TIMING extension), returning the event to the scheduling policy.
engine.removeEventMatchUpFormatTiming({ eventId });
removeScaleValues
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to removeScaleValues. Package-export status is a separate decision.
removeSeeding
engine.removeSeeding({
entryStatuses, // optional array of entryStatues to consider
scaleName, // optional - override default scaleName, event.category.categoryName || event.category.ageCategoryCode
drawId, // optional - to scope participants to entries in a specific draw
stage, // optinal - scope participants to entries in a specific stage of draw
eventId,
});
setEventDates
Where startDate and/or endDate are strings 'YYYY-MM-DD'. Can be used to set startDate and endDate independently.
engine.setEventDates({
activeDates, // optional array of dates from startDate to endDate
weekdays, // optional array of [MON, TUE, ...] // use { weekDayConstants }
startDate, // optional
endDate, // optional
eventId, // required
});
Every date is checked before anything is written: a startDate or endDate outside the tournament's dates is refused
with INVALID_DATE (context.dates names them) and the event is left as it was.
An event's range always lies inside the tournament's. A new event takes the tournament's dates, and a later
setTournamentDates carries it along: an event whose range
equals the tournament's follows every tournament change, and a range narrowed with setEventDates is kept, cut to the
new tournament range, or reset to it when none of it is left.
The new dates land even when scheduled matchUps of the event now sit on days it does not play (see
Event playing days): the result carries one EVENT_DATE_INACTIVE warning
per such matchUp, { code, message, matchUpId, eventId, scheduledDate, reason }. modifyEvent returns the same
warnings when its eventUpdates change the event's dates.
setEventEndDate
Sets only the end date for an event. Part of the setEventDates family of methods.
engine.setEventEndDate({
eventId, // required
endDate, // required - 'YYYY-MM-DD'
});
Purpose: Update event end date independently of start date.
setEventStartDate
Sets only the start date for an event. Part of the setEventDates family of methods.
engine.setEventStartDate({
eventId, // required
startDate, // required - 'YYYY-MM-DD'
});
Purpose: Update event start date independently of end date.
setEventDisplay
Defines publish status for attributes of participants and matchUp schedules which are returned by getEventData and competitionScheduleMatchUps.
const displaySettings = {
draws: {
default: {
participantAttributes: { [key]: boolean },
// an array of attribute settings to be applied to specified dates
scheduleDetails: [
{
attributes: { scheduledTime: false },
dates: [], // empty array or undefined specifies that attribute setting apply to all scheduledDates
},
],
},
[drawId]: {},
},
};
engine.setEventDisplay({
displaySettings,
eventId,
});
updateDrawIdsOrder
Updates the display order of the event's draws: the drawOrder of each drawDefinition, and the drawOrder of each
flight in the event's flightProfile, including flights whose draw has not been generated.
A flight's flightNumber is not changed. It is the flight's level, fixed when the flight is made, and ranking points
are awarded by it (the flights values of an award profile), so reordering draws for display never changes the
points a flight earns.
engine.updateDrawIdsOrder({
eventId,
orderedDrawIdsMap: {
'id-Of-draw-1': 1,
'id-of-draw-2': 2,
},
});
validateCategory
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to validateCategory. Package-export status is a separate decision.
getEventData
Returns comprehensive event data including all draws, participants, and matchUps, formatted for public display. This method is documented in full on the Publishing Governor page.
See Publishing Governor for full documentation.
const { eventData, participants } = engine.getEventData({
eventId, // required
usePublishState, // optional boolean
});
addEventExtension
Adds an extension to an event. Extensions are custom metadata objects attached to tournament elements.
engine.addEventExtension({
extension, // required — { name, value } extension object
eventId, // resolved via engine context
creationTime, // optional boolean — stamp creation time on extension
});