Entries 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: getEffectiveRegistrationProfile, getEntryFeeRange, getEventEntryFees, resolveEntryFee. Existing 7.x routes remain available; final decisions and external-integrator confirmations are tracked in the transition index.
import { entriesGovernor } from 'tods-competition-factory';
addDrawEntries
Bulk add an array of participantIds to a specific stage of a draw with a specific entryStatus. Will fail if participantIds are not already present in event.entries. Use addEventEntries to add to both event and drawDefinition at the same time.
engine.addDrawEntries({
suppressDuplicateEntries, // do not throw error on duplicates; instead notify to DATA_ISSUE subscribers
ignoreStageSpace, // optional boolean to disable checking available positions
entryStageSequence, // optional - applies to qualifying
autoEntryPositions, // optional - keeps entries ordered by entryStage/entryStatus and auto-increments
entryStatus: ALTERNATE, // optional
entryStage: MAIN, // optional
participantIds,
eventId,
drawId,
});
Stage space. Once the stage has a structure, entries are refused with
NO_STAGE_SPACE_AVAILABLE_FOR_ENTRY_STATUS when the stage is full, or with
PARTICIPANT_COUNT_EXCEEDS_DRAW_SIZE when there are more participantIds than places left. The
places left to direct entries are the stage's draw positions less the positions its links hold for
qualifiers, and every entry already holding one counts against them: the direct-entry statuses
(DIRECT_ACCEPTANCE, WILDCARD, ORGANISER_ACCEPTANCE, SPECIAL_EXEMPT, JUNIOR_EXEMPT,
CONFIRMED, FEED_IN) and LUCKY_LOSER, which takes a place vacated by a withdrawal. QUALIFIER
entries count against the qualifier positions only, so they never take a direct-acceptance place, and a
QUALIFIER entry is refused once the qualifier positions are full. getEventEntrySpace
counts the same statuses, so the openPlaces it reports is what this method allows. ignoreStageSpace: true
skips every check.
Sanctioning limits. When the tournament's sanctioned event constraints (sanction.constraints, else the legacy
sanctioningConstraints extension) match the event (by
eventType, and eventName / category.categoryName where the constraint states them), its maxWildcards
and maxAlternates bound the stage's WILDCARD and ALTERNATE entries. A WILDCARD beyond maxWildcards
is refused with NO_STAGE_SPACE_AVAILABLE_FOR_ENTRY_STATUS, an ALTERNATE beyond maxAlternates with
ENTRY_STATUS_NOT_ALLOWED_IN_STAGE, and a single call adding more than the limit leaves with
PARTICIPANT_COUNT_EXCEEDS_DRAW_SIZE. The same limits apply to addEventEntries and addEventEntryPairs given a
drawId, where the draw's refusal is returned as info and the event entries are still made. An unsanctioned
event, or one the constraints do not match, is unaffected: WILDCARD entries are limited only by the places left
and ALTERNATE entries not at all. event.entryProfile.wildcardCount is the number of places held for wildcards,
not a cap, and does not limit them. The limits also bound draw generation and addDrawDefinition, which refuse entries
over them before anything is written (see
generateDrawDefinition).
// with sanctioning constraints { events: [{ eventType: 'SINGLES', maxWildcards: 2 }] }
engine.addDrawEntries({ eventId, drawId, entryStatus: 'WILDCARD', participantIds: [p1, p2] }); // success
engine.addDrawEntries({ eventId, drawId, entryStatus: 'WILDCARD', participantIds: [p3] });
// { error: NO_STAGE_SPACE_AVAILABLE_FOR_ENTRY_STATUS }
addEventEntries
Adds participantIds to event.entries; optionally pass drawId to add participantIds to flightProfile.flight[].drawEntries at the same time. See examples in Tournament Entry Filters, Adding Entries, Complete Example.
Supports optional validation of participant eligibility against event category constraints (age ranges, rating requirements).
A call is all-or-nothing: if any of participantIds is refused (wrong participant type, gender, category or role),
the call returns INVALID_PARTICIPANT_IDS and enters no one; the record is unchanged. Resubmit without the refused ids.
Will not throw an error if unable to add entries into specified flightProfile.flight[].drawEntries,
which can occur if a drawDefinition has already been generated and an attempt is made to add
a participant with entryStatus: DIRECT_ACCEPTANCE.
engine.addEventEntries({
suppressDuplicateEntries, // do not throw error on duplicates; instead notify to DATA_ISSUE subscribers
entryStatus: ALTERNATE, // optional; defaults to DIRECT_ACCEPTANCE
entryStage: MAIN, // optional; defaults to MAIN
autoEntryPositions, // optional - keeps entries ordered by entryStage/entryStatus and auto-increments
enforceCategory, // optional - validate against event category (age/rating); defaults to false
enforceGender, // optional - validate gender; defaults to true
participantIds,
eventId,
drawId, // optional - will add participantIds to specified flightProfile.flight[].drawEntries and drawDefinition.entries (if possible)
});
Category Validation
When enforceCategory: true, validates participants against event category constraints:
Age Validation:
- Participant must be valid throughout entire event period (start to end date)
- Requires
person.birthDateorperson.birthYearif age restrictions exist.birthDategives exact age; a year-precisionbirthYearfalls back to the calendar-year convention (age-in-year = year − birthYear), the standard for junior eligibility when only the birth year is known.birthDateis authoritative when both are present. - Combined age categories (e.g.,
C50-70) are automatically skipped for individuals
Rating Validation:
- Participant must have rating matching
category.ratingType - Rating value must fall within
ratingMin/ratingMaxrange - Uses most recent rating from participant's scale items
Rejection Response:
const result = engine.addEventEntries({
participantIds: ['player1', 'player2', 'player3'],
enforceCategory: true,
eventId,
});
if (result.error) {
// result.context.categoryRejections contains detailed rejection information
result.context.categoryRejections.forEach((rejection) => {
console.log(`${rejection.participantName}:`);
rejection.rejectionReasons.forEach((reason) => {
console.log(` - ${reason.reason}`);
console.log(` Details:`, reason.details);
});
});
}
See: Entries - Category Validation for comprehensive documentation and examples.
addEventEntryPairs
Add PAIR participant to an event. Creates new { participantType: PAIR } participants if the combination of individualParticipantIds does not already exist.
engine.addEventEntryPairs({
allowDuplicateParticipantIdPairs, // optional - boolean - allow multiple pair participants with the same individualParticipantIds
uuids, // optional - array of UUIDs to use for newly created pairs
entryStatus: ALTERNATE, // optional
entryStage: QUALIFYING, // optional
participantIdPairs,
eventId,
});
checkValidEntries
Validates entry participant types and event gender constraints. By default, eventId validates the event's
entries; supplying drawId validates that draw's entries instead. consideredEntries overrides either
source, including when it is an empty array. A supplied draw also determines which format-specific
admission rules apply: accepted individuals are eligible only in a configured rotating-partner draw.
const { valid, error, invalidParticipantIds } = engine.checkValidEntries({
eventId, // required unless drawId identifies the event
drawId, // optional - use this draw's entries and admission rules
consideredEntries, // optional - explicit entries to validate instead
enforceGender, // optional - override the applicable gender-enforcement policy
});
destroyPairEntries
Bulk version of destroyPairEntry. Removes multiple PAIR participants from an event and converts them back to individual entries.
const result = engine.destroyPairEntries({
participantIds, // array of PAIR participant IDs to destroy
removeGroupParticipant, // optional boolean - also remove PAIR from tournament participants
eventId, // required
drawId, // optional
});
if (result.error) {
// nothing was destroyed: result.error is the first failure; every failure is in result.context.errors
} else {
console.log(`Destroyed ${result.destroyedCount} pair entries`);
if (result.context?.errors) console.log('Not destroyed:', result.context.errors);
}
Returns:
// at least one pair destroyed
{
success: true;
destroyedCount: number; // Number of pairs successfully destroyed
context?: { errors: ErrorType[] }; // present only when some pairs could not be destroyed
}
// none destroyed
{
error: ErrorType; // the first failure (PARTICIPANT_ENTRY_NOT_FOUND if none was recorded)
context: { errors: ErrorType[] }; // every failure
}
Since 7.5.0 a refusal is a single error rather than an array, and an empty or missing participantIds is refused
with MISSING_PARTICIPANT_IDS.
What it does:
- Removes PAIR participants from event entries
- Adds individual participants back with
entryStatus: UNGROUPED - Optionally removes PAIR participants from tournament entirely
- Processes multiple pairs in one operation
Use Cases:
- Canceling doubles registrations and returning to singles pool
- Breaking up pairs due to withdrawals
- Converting doubles entries to singles entries
- Cleaning up incorrect pair formations
destroyPairEntry
Removes a { participantType: PAIR } entry from an event and adds the individualParticipantIds to entries as entryStatus: UNGROUPED
engine.destroyPairEntry({
participantId, // PAIR participant ID to destroy
removeGroupParticipant, // optional boolean - also remove PAIR from tournament participants
eventId, // required
drawId, // optional
});
Refused before the first write when the event would not take the individuals back (gender, category, role, or an
unknown participant): the PAIR's entry stays, and the record is unchanged. The same holds for each pair in
destroyPairEntries.
What it does:
- Removes PAIR participant from event.entries
- Adds both individual participants to event.entries with
entryStatus: UNGROUPED - If
drawIdprovided, also updates draw entries - Optionally removes PAIR from
tournamentRecord.participants
Use Cases:
- Player partnership dissolution
- Changing doubles teams
- Converting pair entry to individual entries for different event
Notes:
- Individual participants must exist in tournament
- PAIR participant must be in event entries
- Use
removeGroupParticipant: trueto clean up PAIR from entire tournament - See
destroyPairEntriesfor bulk operation
getEffectiveRegistrationProfile
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to getEffectiveRegistrationProfile. Package-export status is a separate decision.
getEntriesAndSeedsCount
Calculates the number of seeds allowed for a draw based on entries count and seeding policy.
const { entries, stageEntries, seedsCount } = engine.getEntriesAndSeedsCount({
policyDefinitions, // optional - seeding policy
drawDefinition, // optional - draw context
drawSize, // optional - override calculated draw size
stage, // required - MAIN or QUALIFYING
event, // required - event context
drawId, // optional
});
console.log(`${stageEntries.length} entries, ${seedsCount} seeds allowed`);
Returns:
{
entries: Entry[]; // All event entries
stageEntries: Entry[]; // Entries for specified stage
seedsCount: number; // Number of seeds allowed by policy
error?: ErrorType;
}
Purpose: Determines how many seeds are allowed based on the number of entries and seeding policy configuration.
Seeding Policy Logic:
- Checks policy definition for seedsCountThresholds
- Matches entries count to threshold ranges
- Returns maximum seeds allowed for that range
- Falls back to standard seeding rules if no policy
Use Cases:
- Calculating seeds before draw generation
- Validating seeding requests against policy
- UI display of available seed positions
- Enforcing tournament seeding rules
Notes:
- Uses elimination draw size calculation (next power of 2)
- Respects seeding policy limits
- Returns stage-specific entries (MAIN vs QUALIFYING)
- Used internally by
generateDrawDefinition
getEntryFeeRange
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to getEntryFeeRange. Package-export status is a separate decision.
getEventEntryFees
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to getEventEntryFees. Package-export status is a separate decision.
getEntryStatusOrdinals
Each entry's place among the entries of its own stage and entryStatus (e.g. WILDCARD #1, #2), derived from the one
accepted entryPosition list described under modifyEntriesStatus. Nothing is stored. Within
each stage and status, entries are ordered by entryPosition (entries without a position follow, in array order) and
numbered 1..n.
const { statusOrdinals } = engine.getEntryStatusOrdinals({
entries, // array of entry objects, e.g. event.entries or a flight's drawEntries
entryStatus, // optional filter - e.g. WILDCARD
stage, // optional filter - e.g. MAIN, QUALIFYING; an entry without entryStage is MAIN
});
// statusOrdinals: [{ participantId, entryStage, entryStatus, entryPosition, statusOrdinal }]
// e.g. accepted list DA 1, WC 2, DA 3, WC 4 -> WILDCARD statusOrdinals 1 (position 2) and 2 (position 4)
getEventEntrySpace
How many MAIN places an event (or one of its draws) has for entries accepted directly — neither qualifiers nor wildcards — and how many of them are still open.
const { basis, drawPositions, qualifierPositions, wildcardPositions, directAcceptancePlaces, openPlaces } =
engine.getEventEntrySpace({
eventId, // required
drawId, // optional - that draw's positions and entries; otherwise the event's
});
Returns:
{
success: true;
basis: 'STRUCTURE' | 'TARGET_DRAW_SIZE' | 'SANCTIONING_CONSTRAINTS' | 'NONE'; // where drawPositions came from
drawPositions: number; // MAIN draw positions
qualifierPositions: number; // MAIN positions held for qualifiers
qualifierPositionsBasis: 'STRUCTURE' | 'ENTRY_PROFILE' | 'NONE';
wildcardPositions: number; // max(entryProfile.wildcardCount, wildcardsAccepted)
wildcardsAccepted: number;
directAcceptedCount: number; // MAIN entries in DIRECT_ENTRY_STATUSES or LUCKY_LOSER, wildcards excluded
acceptedCount: number; // directAcceptedCount + wildcardsAccepted
directAcceptancePlaces?: number; // drawPositions - qualifierPositions - wildcardPositions; undefined when basis is NONE
openPlaces?: number; // directAcceptancePlaces - directAcceptedCount, never below 0; undefined when basis is NONE
}
Where the numbers come from. Once a MAIN structure exists, its positions and the qualifier
positions its links deliver decide — the same breakdown entry into a draw uses. Before that, the event's
entryProfile: targetDrawSize for the positions (then the sanctioning constraints extension's
drawSize), and qualifiersCount, or the final stage of each of qualifyingProfiles, for the qualifier
positions. A qualifyingDrawSize alone holds no MAIN place: a qualifying draw's size does not say how
many it sends on. A LUCKY_LOSER entry takes a place vacated by a withdrawal and counts in
directAcceptedCount; a QUALIFIER entry fills a qualifier position and does not. Without drawId, positions are summed over every draw that has a MAIN structure and
counted against the event's entries; entries with no entryStage count as MAIN.
getMaxEntryPosition
Returns the highest entryPosition value from entries, optionally filtered by stage and/or entryStatus.
const maxPosition = engine.getMaxEntryPosition({
entries, // array of entry objects
entryStatus, // optional filter - e.g., DIRECT_ACCEPTANCE, ALTERNATE
stage, // optional filter - e.g., MAIN, QUALIFYING
});
// Use for assigning next entry position
const nextPosition = maxPosition + 1;
Returns: number - Highest entryPosition found, or 0 if no matches
Use Cases:
- Determining next entry position when adding entries
- Finding last position in acceptance list
- Ordering entries by position
- Managing entry position sequences
Notes:
- Returns 0 if no entries match filters
- Ignores entries without
entryPosition(NaN values) - Can filter by both
stageandentryStatussimultaneously - Used internally when
autoEntryPositions: true
modifyEntriesStatus
Modify the entryStatus of participants already in an event or flight/draw. Does not allow participants assigned positions in structures to have an entryStatus of WITHDRAWN.
const result = engine.modifyEntriesStatus({
autoEntryPositions, // optional - keeps entries ordered by entryStage/entryStatus and auto-increments
participantIds, // ids of participants whose entryStatus will be modified
entryStatus, // new entryStatus
entryStage, // optional - e.g. QUALIFYING
eventSync, // optional - if there is only a single drawDefinition in event, keep event.entries in sync
extension, // optional - { name, value } - add if value; removes if value is undefined
eventId, // id of event where the modification(s) will occur
drawId, // optional - scope to a specific flight/draw
stage, // optional - scope to a specific stage
});
Draw scope. With a drawId that resolves a flight or draw, every participant in participantIds must have an
entry in that flight's drawEntries or the draw's entries. Otherwise the call is refused before anything is written,
with PARTICIPANT_ENTRY_NOT_FOUND and context.participantIds naming the participants that are not in scope; if
only some are out of scope, the whole call is refused. A call that also updates the event's entries (WITHDRAWN, or
eventSync with a single draw) accepts a participant that is in the event's entries but not in the draw.
entryPositions. Positions are numbered within a group, as refreshEntryPositions numbers them. All accepted
statuses (STRUCTURE_SELECTED_STATUSES: DIRECT_ACCEPTANCE, WILDCARD, SPECIAL_EXEMPT, JUNIOR_EXEMPT,
ORGANISER_ACCEPTANCE, CONFIRMED, QUALIFIER, LUCKY_LOSER) form one list per entryStage (MAIN when
absent); every other status (ALTERNATE, WITHDRAWN, ...) has its own list per stage. The same rule applies in the
event's entries, the flight's drawEntries and the draw's entries, with or without autoEntryPositions.
- An entry that changes group goes to the end of its new group (
max + 1of the group's positions), and the entries behind it in its old group close up. AnALTERNATEmoved toDIRECT_ACCEPTANCEtherefore follows the accepted entries and never takes an accepted entry's position; an accepted entry moved toALTERNATEgoes after the alternates, and the accepted entries close up. An alternate moved to any accepted status (WILDCARD,LUCKY_LOSER, ...) takes the next position of the whole accepted list. AWITHDRAWNentry restored and a qualifying alternate moved to the main stage follow the same rule. - Several moved in one call take distinct positions in the order of
participantIds. - An entry already in the requested group keeps its position, including a change between accepted statuses
(e.g.
DIRECT_ACCEPTANCEtoWILDCARD). - When no entry of the new group has a position, the moved entry is left without one: a position would sort it ahead of them.
- No two accepted entries of a stage share a position: a
DIRECT_ACCEPTANCEentry and aWILDCARDentry are numbered in one list. Each status's own order (WILDCARD#1, #2) is derived, not stored: see getEntryStatusOrdinals.promoteAlternatesplaces entries by the same rule.
modifyEventEntries
Modify the entries for an event. For DOUBLES events automatically create PAIR participants if not already present. See examples: Update Entry Status.
engine.modifyEventEntries({
entryStatus = DIRECT_ACCEPTANCE,
unpairedParticipantIds = [],
participantIdPairs = [],
entryStage = MAIN,
eventId,
})
promoteAlternate
Promotes a single alternate participant to direct acceptance status.
const result = engine.promoteAlternate({
participantId, // optional - participant to promote; defaults to the stage's next alternate
stage, // optional - defaults to MAIN
stageSequence, // optional - for qualifying stages
eventId, // required
drawId, // optional - also promote in draw
});
Returns:
{
success: boolean;
error?: ErrorType;
context?: { drawPromotionError, drawId }; // the draw could not promote; the event did
}
Purpose: Changes participant entryStatus from ALTERNATE to DIRECT_ACCEPTANCE. Without a participantId the
stage's alternate with the lowest entryPosition is promoted (with no positioned alternate, the first one entered).
See promoteAlternates for positions, draws and flights.
promoteAlternates
Bulk version of promoteAlternate. Promotes multiple alternates to direct acceptance, in the order given.
const result = engine.promoteAlternates({
participantIds, // required - participant IDs to promote, in order of acceptance
stage, // optional - defaults to MAIN
stageSequence, // optional - for qualifying stages
eventId, // required
drawId, // optional - also promote in draw
});
Purpose: Efficiently promote multiple alternates at once after withdrawals.
- Positions. Each promoted entry takes the next position after the stage's accepted entries (
max + 1), so promoting several in one call gives them distinct positions in the order ofparticipantIds. The alternates behind each promoted entry close up. When no accepted entry in the stage has anentryPosition, the promoted entry is left without one. - Refused before any write. Every id must be an alternate entry of the event in
stage(andstageSequence, when given); otherwise nothing changes. An id that is not an event entry returnsPARTICIPANT_ENTRY_NOT_FOUND. - Draws. With
drawId, the draw's entries are promoted too. With split draws an alternate may not be in the draw's entries: giveneventId, the event is still promoted and the draw's refusal is returned ascontext.drawPromotionError; given onlydrawId, the call is refused. A generated draw's entries are promoted without placing the participant in the structure. - Flights. The same alternates are promoted in the
drawEntriesof the draw's flight and of every flight whose draw is not yet generated, wherever they appear there as alternates.
removeDrawEntries
Removes participant entries from a drawDefinition (but not from the event).
const result = engine.removeDrawEntries({
participantIds, // required - array of participant IDs to remove (from every stage of the draw)
stages, // optional - stages checked for participants already assigned positions, e.g. [MAIN]
autoEntryPositions, // optional - defaults to true; re-numbers the remaining entries' positions
eventId, // required
drawId, // required
});
// refused when any participantId is assigned a draw position (in `stages`, when given)
Purpose: Removes entries from draw only, maintaining event entries.
removeEventEntries
Removes participant entries from an event, and from every flight and draw of that event.
const { participantIdsRemoved } = engine.removeEventEntries({
participantIds, // array of participant IDs to remove
entryStatuses, // optional - only entries with one of these entryStatuses (or, without participantIds, all of them)
stage, // optional - only entries with this entryStage (or, without participantIds, all of them)
autoEntryPositions, // optional - renumber the remaining entries' entryPosition
eventId, // required
});
A participant already placed in a draw cannot be removed: the call is refused with
EXISTING_PARTICIPANT_DRAW_POSITION_ASSIGNMENT and nothing is removed.
resolveEntryFee
8.0.0 engine-removal candidate. This 7.x route remains available pending review. The full reference has moved to resolveEntryFee. Package-export status is a separate decision.
setEntryPosition
Set entry position a single event entry
engine.setEntryPosition({
entryPosition,
participantId,
eventId, // optional if drawId is provided
drawId, // optional if eventId is provided
});
setEntryPositions
Set entry position for multiple event entries.
engine.setEntryPositions({
entryPositions, // array of [{ entryPosition: 1, participantId: 'participantid' }]
eventId, // optional if drawId is provided
drawId, // optional if eventId is provided
});
setEntryQualifyingPath
Sets the path QUALIFYING entries take to MAIN, on entries that already exist (addEventEntries sets the same two
attributes only as entries are added). The topology builder decides both from the structures the director draws.
entryStageSequence— how deep in the qualifying chain the entry starts;1is the deepest (pre-qualifying, then qualifying).roundTarget— the MAIN round its qualifying chain leads to; a stronger field can earn a later entry point.
Without a drawId the event's entries change, with every flight's and draw's copy of them; with a drawId only that
draw's and its flight's. Every participant must have a QUALIFYING entry in scope, or nothing changes:
PARTICIPANT_ENTRY_NOT_FOUND, or INVALID_STAGE for an entry in another stage.
engine.setEntryQualifyingPath({
participantIds, // required - QUALIFYING entries
eventId, // required
drawId, // optional - only this draw's (and its flight's) entries
entryStageSequence, // optional integer >= 1
roundTarget, // optional integer >= 1; at least one of the two
});