Skip to main content

Draws Governor

import { drawsGovernor } from 'tods-competition-factory';

addAdHocMatchUps​

Adds matchUps generated by generateAdHocMatchUps to specified structure within an AD_HOC drawDefinition.

engine.addAdHocMatchUps({
  structureId, // optional if there is only one structure in drawDefinition
  matchUps,
  drawId,
});

adHocPositionSwap​

Swaps participant assignments in two unscored matchUps that are part of the same roundNumber in and AD_HOC structure. This method and one of the two participantIds are returned in validActions by positionActions which calls adHocMatchUpActions, meaning this method is not normally called directly.

engine.adHocPositionSwap({
  participantIds,
  structureId,
  roundNumber,
  drawId,
});

addPlayoffStructures​

Adds playoff structures to an existing drawDefinition.

engine.addPlayoffStructures({
  drawId,
  structureId,
  roundNumbers: [3], // required if no playoffPositions - source roundNumbers which will feed target structures, e.g. [1, 2]
  roundProfiles, // optional - source roundNumbers as Object.keys with depth as Object.values, e.g. [{ 1: 2}, {2: 1}]
  playoffPositions: [3, 4], // required if not provided roundNumbers
  playoffAttributes, // optional - mapping of either exitProfile or finishingPositionRange to structure names, e.g. 0-1-1 for South
  exitProfileLimit, // limit playoff rounds generated by the attributes present in playoffAttributes
  playoffStructureNameBase, // optional - base word for default playoff naming, e.g. 'Playoff'
});

// example use of playoffAttributes - will generated playoff structure from 2nd round with structureName: 'BRONZE'
const playoffAttributes = {
  '0-2': { name: 'BRONZE', abbreviation: 'B' },
};

addQualifyingStructure​

engine.addQualifyingStructure({
  targetStructureId, // required: structure for which participants will qualify
  qualifyingPositions, // optional: specify the # of qualifyingPositions
  qualifyingRoundNumber, // optional: determine qualifyingPositions by # of matchUps in specified round; does not apply to ROUND_ROBIN
  structureOptions, // optional: specific to ROUND_ROBIN generation
  structureName, // optional
  drawSize,
  drawType, // optional: defaults to SINGLE_ELIMINATION
  drawId, // required: draw within which target structure appears
});

addVoluntaryConsolationStage​

Modifies the entryProfile for a draw to allow { entryStage: VOLUNTARY_CONSOLATION }

engine.addVoluntaryConsolationStage({
  drawSize,
  drawId,
});

addVoluntaryConsolationStructure​

Generates a new structure within a drawDefinition if any draw entries are present for { entryStage: VOLUNTARY_CONSOLATION }.

engine.addVoluntaryConsolationStructure({
  structureAbbreviation, // optional
  structureName, // optional - defaults to 'VOLUNTARY_CONSOLATION'
  drawId,
});

alternateDrawPositionAssignment​

Replaces an existing drawPosition assignment with an alternateParticipantId. This method is included in validActions for positionActions

engine.alternateDrawPositionAssignment({
  alternateParticipantId,
  drawPosition,
  structureId,
  drawId,
});

assignDrawPosition​

Low level function normally called by higher order convenience functions.

engine.assignDrawPosition({
  participantId, // optional - if assigning position to a participant
  drawPosition,
  structureId,
  qualifier, // optional boolean, if assigning a space for a qualifier
  drawId,
  bye, // optional boolean, if assigning a bye
});

assignDrawPositionBye​

engine.assignDrawPositionBye({
  structureId,
  drawId,
});

attachPlayoffStructures​

Attaches the results of generateAndPopulatePlayoffStructures to a drawDefinition.

note

engine.addPlayoffStructures() calls both generateAndPopulatePlayoffStructures and attachPlayoffStructures.

engine.attachPlayoffStructures({
  matchUpModifications, // optional - pass any modifications external to the structure that are relevant to structure generation
  structures,
  drawId,
  links,
});

attachQualifyingStructure​

engine.attachQualifyingStructure({
  structure, // required: structure object; see `generateQualifyingStructure`
  drawId, // required: id of drawDedfinition to which structure will be attached
  link, // required
});

attachStructures​

Use to attach structures and links which are generated by generateVoluntaryConsolation.

engine.attachStructures({
  matchUpModifications, // optional - pass any modifications external to the structure that are relevant to structure generation
  structures,
  drawId,
  links,
});

automatedPlayoffPositioning​

For Round Robin structures, uses Round Robin Tallies to position participants in playoff structure(s).

engine.automatedPlayoffPositioning({
  structureId: mainStructure.structureId,
  provisionalPositioning, // optional boolean, defaults to false; when true will honor provisionalOrder if no groupOrder is found in tallyResults
  applyPositioning, // optional boolean, defaults to true; when false will return positioning but not apply it to playoff structures
  drawId,
});

automatedPositioning​

Positions participants in a draw structure.

See Policies.

engine.automatedPositioning({ drawId, structureId });

autoSeeding​

note

Only generates seeding. To apply engine.setParticipantScaleItems({ scaleItemsWithParticipantIds }.

const { scaleItemsWithParticipantIds } = engine.autoSeeding({
  policyDefinitions, // seeding policyDefinition determines the # of seeds for given participantsCount/drawSize
  scaleAttributes, // { scaleType, scaleName, eventType, accessor }
  scaleName, // Optional - defaults to scaleAttributes.scaleName
  drawSize, // Optional - defaults to calculation based on # of entries
  eventId, // required - necessary for resolving entries
  drawId, // Optional - will use flight.drawEntries or drawDefinition.entries rather than event.entries
  stage, // Optional - filters entries by specified stage

  scaleSortMethod, // Optional - user defined sorting method
  sortDescending, // Optional - defaults to false
});

engine.setParticipantScaleItems({
  scaleItemsWithParticipantIds,
});

deleteAdHocMatchUps​

const result = engine.deleteAdHocMatchUps({
  structureId, // optional optimization - structureId of structure from which matchUps are being deleted
  matchUpIds, // array of matchUpIds identifying matchUps to be deleted
  drawId, // required - drawId of drawDefinition in which target structure is found
});

luckyLoserDrawPositionAssignment​

Replaces an existing drawPosition assignment with a luckyLoserParticipantId. This method is included in validActions for positionActions

engine.luckyLoserDrawPositionAssignment({
  luckyLoserParticipantId,
  drawPosition,
  structureId,
  drawId,
});

modifyDrawDefinition​

engine.modifyDrawDefinition({
  drawUpdates: { policyDefinitions: { ...policies } },
  drawName: 'League Play',
  drawId,
});

modifySeedAssignment​

Change the display representation of a seedNumber for a specified participantId. This method is included in validActions for positionActions.

The rationale for seedValue is to be able to, for instance, represent the fifth through the eighth seed as 5-8, or simply as 5. When there are no restrictions on seed positioning seedValue allows assigning seeding to arbitrary participants.

engine.modifySeedAssignment({
  participantId,
  structureId,
  seedValue, // display representation such as '5-8'
  drawId,
});

qualifierDrawPositionAssignment​

Replaces an existing drawPosition assignment with a qualifierParticipantId. This method is included in validActions for positionActions

engine.qualifierDrawPositionAssignment({
  qualifierParticipantId,
  drawPosition,
  structureId,
  drawId,
});

removeDrawDefinitionExtension​

engine.removeDrawDefintionExtension({ eventId, drawId, name });

removeDrawPositionAssignment​

Clear draw position and optionally replace with a BYE, change entryStatus, or decompose a PAIR participant into UNGROUPED participants (DOUBLES only).

engine.removeDrawPositionAssignment({
  drawDefinition,
  structureId,
  drawPosition,
  replaceWithBye, // optional
  entryStatus, // optional - change the entryStatus of the removed participant
  destroyPair, // optional - decompose PAIR participant into UNGROUPED participants
});

removeDrawEntries​

Removes participantIds from drawDefinition.entries (if generated) as well as any relevent flightProfile.flights.

engine.removeDrawEntries({
  autoEntryPositions, // optional - keeps entries ordered by entryStage/entryStatus and auto-increments
  participantIds
  eventId,
  stages, // optional array of stages to consider, e.g. [VOLUNTARY_CONSOLATION]
  drawId,
  });

removeRoundMatchUps​

const {
  deltedMatchUpsCount, // number
  roundRemoved, // boolean
  success, // boolean
  error, // if any
} = engine.removeRoundMatchUps({
  removeCompletedMatchUps, // optional boolean - whether to remove completed matchUps
  roundNumber, // required - roundNumber to remove
  structureId, // required
  drawId, // required
});

removeStructure​

Removes targeted drawDefinition.structure and all other child structures along with all associated drawDefinition.links.

const { removedMatchUpIds } = engine.removeStructure({
  structureId,
  drawId,
});

renameStructures​

engine.renameStructures({
  structureDetails: [{ structureId, structureName }],
  drawId,
});

resetDrawDefinition​

engine.resetDrawDefinition({ drawId });

resetQualifyingStructure​

engine.resetQualifyingStructure({ structureId, drawId });

--

resetVoluntaryConsolationStructure​

engine.resetVoluntaryConsolationStructure({
  resetEntries, // optional - remove all { entryStage: VOLUNTARY_CONSOLATION }
  drawId,
});

resetQualifyingStructure​

engine.resetQualifyingStructure({
  drawId,
  structureId,
});

setDrawParticipantRepresentativeIds​

Set the participantIds of participants in the draw who are representing players by observing the creation of the draw.

engine.setDrawParticipantRepresentativeIds({
  representativeParticipantIds,
  drawId,
});

setPositionAssignments​

Intended to be used in conjunction with automatedPlayoffPositioning in deployments where a client instance gets the positioning which is then set on both the client and the server, to ensure that both client and server are identical. If automatedPlayoffPositioning is invoked on both client and server independently then it is likely that the positioning on client and server will be different.

// executed only on the client
const { structurePositionAssignments } = engine.automatedPlayoffPositioning({
  applyPositioning: false, // instructs factory engine to only return values, not apply them
  structureId,
  drawId,
});

// executed on both client and server
result = engine.setPositionAssignments({
  structurePositionAssignments,
  drawId,
});

setSubOrder​

Used to order ROUND_ROBIN participants when finishingPosition ties cannot be broken algorithmically. Assigns a subOrder value to a participant within a structure by drawPosition.

engine.setSubOrder({
  drawPosition: 1,
  subOrder: 2,
  structureId,
  drawId,
});

shiftAdHocRounds​

Move roundNumber to targetRoundNumber.

tournamentEngine.shiftAdHocRounds({
  targetRoundNumber,
  roundNumber,
  structureId,
  drawId,
});

swapAdHocRounds​

Swap roundNumbers. Must provide an array of two valid roundNumbers.

tournamentEngine.swapAdHocRounds({
  roundNumbers: [2, 4],
  structureId,
  drawId,
});

swapDrawPositionAssignments​

Swaps the participantIds of two drawPositions.

engine.swapDrawPositionAssignments({
  drawPositions,
  structureId,
  drawId,
});

updateTeamLineUp​

See validateLineUp

engine.updateTeamLineUp({
  participantId, // id of the team for which lineUp is being updated
  tieFormat, // valid tieFormat - used to validate collectionIds
  lineUp, // valid lineUp array
  drawId, // required as latest lineUp modification is stored in an extension on drawDefinition
});

withdrawParticipantAtDrawPosition​

Thin wrapper around removeDrawPositionAssignment. This method is included in validActions for positionActions.

engine.withdrawParticipantAtDrawPosition({
  entryStatus = WITHDRAWN,
  replaceWithBye, // optional
  drawDefinition,
  drawPosition,
  structureId,
  destroyPair, // optional - decompose PAIR participant into UNPAIRED participants
});