Skip to main content

Event Governor

Governor API transition at 8.0.0

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 provided
  • eventName — display name
  • eventType — defaults to SINGLES_EVENT; use TEAM_EVENT for team competitions
  • tieFormat — required for TEAM events (validated), or use tieFormatName to select a preset
  • tieFormatName — optional — selects a built-in tieFormat by name (e.g. 'COLLEGE_DEFAULT')
  • startDate, endDate — optional, default to tournament dates
  • category, gender, matchUpFormat — optional event metadata
note

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.

note

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
},
},
});
  • qualifyingProfiles states multi-structure qualifying (pre-qualifying with stageSequence 1 and 2, or several structures feeding different MAIN rounds) and mirrors the draw generator's input of the same name. It replaces qualifyingDrawSize and qualifiersCount: a profile carrying both is refused, so switching shapes takes nulling the simple keys in the same call.
  • Sizes are positive whole numbers (qualifiersCount and wildcardCount may be 0); qualifier and wildcard places together may not exceed targetDrawSize; a structure profile's qualifyingPositions must be fewer than its drawSize.

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
});