Skip to main content

Core API Reference

Complete method reference for the ScaleEngine. The ScaleEngine exposes all methods from the Ranking Governor plus rating functions, accessible through the stateful engine pattern.

info

The ScaleEngine shares the syncEngine singleton. Call scaleEngine.setState(tournamentRecord) before invoking methods, or pass policyDefinitions explicitly when tournament policies aren't attached.

Ranking Points Methods​

getTournamentPoints​

getTournamentPoints(params?: {
  policyDefinitions?: PolicyDefinitions;
  participantFilters?: ParticipantFilters;
  level?: number;
}): {
  success: boolean;
  personPoints: Record<string, PointAward[]>;
  pairPoints: Record<string, PointAward[]>;
  teamPoints: Record<string, PointAward[]>;
  participantsWithOutcomes: Participant[];
}

Computes ranking points for all participants in the loaded tournament. This is the core computation method.

scaleEngine.setState(tournamentRecord);
const result = scaleEngine.getTournamentPoints({
  policyDefinitions: rankingPolicy,
  level: 3,
});

// Iterate personPoints
for (const [personId, awards] of Object.entries(result.personPoints)) {
  const total = awards.reduce((sum, a) => sum + (a.points || 0) + (a.qualityWinPoints || 0), 0);
  console.log(`${personId}: ${total} points`);
}

Parameters:

ParameterTypeDescription
policyDefinitionsPolicyDefinitionsRanking policy. Falls back to tournament-attached policy if not provided
participantFiltersParticipantFiltersFilter which participants to process
levelnumberTournament level (used for level-keyed point values)

Returns: personPoints keyed by personId, pairPoints keyed by pair participantId, teamPoints keyed by team participantId. Each value is an array of PointAward objects.

See Ranking Points Pipeline for how points are computed.

applyTournamentRankingPoints​

applyTournamentRankingPoints(params: {
  policyDefinitions?: PolicyDefinitions;
  participantFilters?: ParticipantFilters;
  scaleName?: string;      // default: 'RANKING_POINTS'
  level?: number;
  removePriorValues?: boolean;
}): {
  success: boolean;
  personPoints: Record<string, PointAward[]>;
  pairPoints: Record<string, PointAward[]>;
  teamPoints: Record<string, PointAward[]>;
  modificationsApplied: number;
}

Computes ranking points and persists them as scale items on participant records. This enables multi-tournament workflows where one tournament's points are available for quality win lookups in subsequent tournaments.

scaleEngine.setState(tournamentRecord);

const result = scaleEngine.applyTournamentRankingPoints({
  policyDefinitions: rankingPolicy,
  scaleName: 'USTA_JUNIOR',
  level: 2,
  removePriorValues: true,
});

// Points are now persisted and retrievable
const { scaleItem } = scaleEngine.getParticipantScaleItem({
  participantId: 'player-123',
  scaleAttributes: {
    scaleType: 'RANKING',
    scaleName: 'USTA_JUNIOR',
    eventType: 'SINGLES',
  },
});
// scaleItem.scaleValue = { points: 500, awards: [...] }

Parameters:

ParameterTypeDescription
policyDefinitionsPolicyDefinitionsRanking policy
participantFiltersParticipantFiltersFilter which participants to process
scaleNamestringName for the scale item (default: 'RANKING_POINTS')
levelnumberTournament level
removePriorValuesbooleanRemove existing scale items with the same scaleName before writing

Scale item structure: Each participant receives one scale item per eventType, with scaleValue: { points, awards } where points is the total and awards is the full PointAward[] breakdown.

getAwardProfile​

getAwardProfile(params: {
  awardProfiles: AwardProfile[];
  participation: StructureParticipation;
  eventType?: string;
  drawType?: string;
  drawSize?: number;
  category?: Category;
  gender?: string;
  wheelchairClass?: string;
  level?: number;
  startDate?: string;
  endDate?: string;
}): { awardProfile?: AwardProfile }

Selects the best-matching award profile using specificity scoring. Generally called internally by getTournamentPoints, but available for inspection and debugging.

getAwardPoints​

getAwardPoints(params: {
  valueObj: PositionValue;
  level?: number;
  drawSize?: number;
  flightNumber?: number;
  flights?: FlightConfig;
  participantWon?: boolean;
}): { awardPoints: number; requireWin?: boolean }

Resolves a position value object into numeric points. Handles level-keyed values, draw size thresholds, flight lookups, and won/lost accessors.

Aggregation Methods​

generateRankingList​

generateRankingList(params: {
  pointAwards: PointAward[];
  aggregationRules?: AggregationRules;
  categoryFilter?: CategoryFilter;
  asOfDate?: string;
}): RankingListEntry[]

Aggregates point awards from multiple tournaments into a sorted ranking list. This is a pure computation function — it does not access tournament state.

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

const rankingList = generateRankingList({
  pointAwards: allAwards, // collected from multiple getTournamentPoints calls
  aggregationRules: {
    countingBuckets: [
      { bucketName: 'Singles', eventTypes: ['SINGLES'], pointComponents: ['positionPoints', 'perWinPoints', 'bonusPoints'], bestOfCount: 6 },
      { bucketName: 'Doubles', eventTypes: ['DOUBLES'], pointComponents: ['positionPoints', 'perWinPoints', 'bonusPoints'], bestOfCount: 2 },
      { bucketName: 'Quality Wins', pointComponents: ['qualityWinPoints'], bestOfCount: 0 },
    ],
    rollingPeriodDays: 365,
    minCountableResults: 3,
    tiebreakCriteria: ['highestSingleResult', 'mostWins'],
  },
  asOfDate: '2025-12-31',
});

for (const entry of rankingList) {
  console.log(`#${entry.rank} ${entry.personId}: ${entry.totalPoints}pts (${entry.countingResults.length} counting)`);
}

See Multi-Tournament Aggregation for detailed documentation.

getParticipantPoints​

getParticipantPoints(params: {
  pointAwards: PointAward[];
  personId: string;
  aggregationRules?: AggregationRules;
}): {
  buckets: BucketBreakdown[];
  totalPoints: number;
}

Returns a per-participant breakdown showing which results count and which are dropped, organized by bucket.

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

const { buckets, totalPoints } = getParticipantPoints({
  pointAwards: allAwards,
  personId: 'player-abc',
  aggregationRules: {
    countingBuckets: [
      { bucketName: 'Singles', eventTypes: ['SINGLES'], pointComponents: ['positionPoints', 'perWinPoints'], bestOfCount: 6 },
    ],
  },
});

for (const bucket of buckets) {
  console.log(`${bucket.bucketName}: ${bucket.bucketTotal}pts (${bucket.countingResults.length} counting, ${bucket.droppedResults.length} dropped)`);
}

Quality Win Methods​

getQualityWinPoints​

getQualityWinPoints(params: {
  qualityWinProfiles: QualityWinProfile[];
  wonMatchUpIds: string[];
  mappedMatchUps: Record<string, MatchUp>;
  participantSideMap: Record<string, number>;
  tournamentParticipants: Participant[];
  tournamentStartDate?: string;
  participantId?: string;
  level?: number;
}): {
  qualityWinPoints: number;
  qualityWins: QualityWin[];
}

Computes quality win bonus points for a participant's won matchUps. Generally called internally by getTournamentPoints.

See Quality Win Points for detailed documentation.

Rating Methods​

generateDynamicRatings​

Generates dynamic ratings for all participants based on match outcomes using configurable algorithms.

calculateNewRatings​

Calculates updated ratings for two participants based on a match outcome.