Utilities API

Utility functions for coordinates, data processing, colors, and scales.

Coordinate Utilities

nhlToSVG()

Converts NHL coordinates (center-origin) to SVG coordinates (top-left origin).

function nhlToSVG(
  coord: NHLCoordinate,
  dimensions: RenderDimensions,
): SVGCoordinate;

svgToNHL()

Converts SVG coordinates back to NHL coordinates.

function svgToNHL(
  coord: SVGCoordinate,
  dimensions: RenderDimensions,
): NHLCoordinate;

flipCoordinatesByPeriod()

Flips coordinates based on period (teams switch ends).

function flipCoordinatesByPeriod(
  coord: NHLCoordinate,
  period: number,
  flipOddPeriods?: boolean,
): NHLCoordinate;

normalizeCoordinate()

Clamps coordinates to valid rink bounds.

function normalizeCoordinate(coord: NHLCoordinate): NHLCoordinate;

normalizeToOffensiveZone()

Ensures x is positive (offensive perspective).

function normalizeToOffensiveZone(coord: NHLCoordinate): NHLCoordinate;

normalizeToDefensiveZone()

Ensures x is negative (goalie perspective).

function normalizeToDefensiveZone(coord: NHLCoordinate): NHLCoordinate;

calculateScale()

Calculates feet-to-pixels conversion factor.

function calculateScale(
  width: number,
  height: number,
  padding: number,
  halfRink?: boolean,
  vertical?: boolean,
): RenderDimensions;

getDistance()

Euclidean distance between two coordinates (in feet).

function getDistance(coord1: NHLCoordinate, coord2: NHLCoordinate): number;

getZone()

Determines rink zone for a coordinate.

function getZone(
  coord: NHLCoordinate,
  offensiveZonePositive?: boolean,
): "offensive" | "neutral" | "defensive";

Zone boundaries: offensive (x > 25), neutral (-25 ≤ x ≤ 25), defensive (x < -25).

---

NHL Data Parsing

parseNHLPlayByPlay()

Parses NHL API play-by-play response into HockeyEvent array.

function parseNHLPlayByPlay(response: NHLPlayByPlayResponse): HockeyEvent[];

parseNHLEvents()

Parses array of NHL events, filtering to those with location data.

function parseNHLEvents(events: NHLEvent[]): HockeyEvent[];

parseNHLEventsWithFilter()

Parses with filtering options.

function parseNHLEventsWithFilter(
  events: NHLEvent[],
  options?: ParseOptions,
): HockeyEvent[];

parseNHLEventsByTeam()

Parses events for a specific team.

function parseNHLEventsByTeam(
  events: NHLEvent[],
  teamId: number,
): HockeyEvent[];

nhlEventToHockeyEvent()

Converts single NHL event to HockeyEvent format.

function nhlEventToHockeyEvent(event: NHLEventWithLocation): HockeyEvent;

---

Data Utilities

hasValidCoordinates()

Returns true if ALL events in the array have valid x/y coordinate numbers.

function hasValidCoordinates(data: HockeyEvent[]): boolean;

validateCoordinates()

Filters events to only those with valid coordinates (removes events with missing, null, or NaN coordinate values).

function validateCoordinates(data: HockeyEvent[]): HockeyEvent[];

filterByZone()

function filterByZone(
  events: HockeyEvent[],
  zone: "offensive" | "defensive" | "neutral",
): HockeyEvent[];

filterByTeam()

function filterByTeam(events: HockeyEvent[], team: string): HockeyEvent[];

filterByPeriod()

function filterByPeriod(events: HockeyEvent[], period: number): HockeyEvent[];

groupBy()

function groupBy<T extends Record<string, unknown>>(
  data: T[],
  key: keyof T,
): Map<string | number, T[]>;

calculateStats()

Returns basic statistics for a numeric property.

function calculateStats(
  data: HockeyEvent[],
  getValue: (d: HockeyEvent) => number,
): {
  count: number;
  sum: number;
  mean: number;
  min: number;
  max: number;
};

---

Color Utilities

NHL_TEAM_COLORS

Object with all 32 NHL team color palettes.

const NHL_TEAM_COLORS: Record<string, TeamColors>;

// TeamColors: { primary: string; secondary: string; accent: string }

getTeamColors()

function getTeamColors(teamAbbrev: string): TeamColors | undefined;

getTeamPrimaryColor()

function getTeamPrimaryColor(teamAbbrev: string): string;

HOCKEY_COLOR_SCALES

Built-in color scales for visualizations.

HOCKEY_COLOR_SCALES.heatmap; // Blue → yellow → red
HOCKEY_COLOR_SCALES.ice; // Cool blues
HOCKEY_COLOR_SCALES.fire; // Warm oranges/reds
HOCKEY_COLOR_SCALES.diverging; // Blue → white → red

createColorScale()

Creates a D3 sequential color scale.

function createColorScale(
  domain: [number, number],
  colors?: string[],
): d3.ScaleSequential<string>;

colorByTeam()

Creates accessor that returns team color.

function colorByTeam(
  teamAccessor: keyof T | ((d: T) => string),
  options?: { colorType?: "primary" | "secondary" | "accent" },
): Accessor<T, string>;

colorByProperty()

Maps property values to colors.

function colorByProperty<T>(
  property: keyof T | ((d: T) => number),
  colors: string[],
  domain?: [number, number],
): Accessor<T, string>;

colorByCategory()

Maps categories to colors.

function colorByCategory<T>(
  property: keyof T | ((d: T) => string),
  colorMap: Record<string, string>,
  defaultColor?: string,
): Accessor<T, string>;

colorByCondition()

Returns color based on first matching condition.

function colorByCondition<T>(
  conditions: Array<[(d: T) => boolean, string]>,
  defaultColor: string,
): Accessor<T, string>;

getOpacity()

Returns an opacity value for a data point.

function getOpacity<T>(
  d: T,
  opacity: number | Accessor<T, number>,
  index: number,
): number;

colorGradient()

Creates an accessor that maps numeric values to a color gradient between two colors.

function colorGradient<T>(
  property: keyof T | ((d: T) => number),
  options: {
    from: string;
    to: string;
    domain?: [number, number];
    fallback?: string;
  },
): Accessor<T, string>;

getShotResultColor()

Returns standard color for shot results.

function getShotResultColor(result: "GOAL" | "SAVE" | "MISS" | "BLOCK"): string;

---

Scale Utilities

scaleRadiusByProperty()

Creates radius accessor scaled by property value.

function scaleRadiusByProperty<T>(
  property: keyof T | ((d: T) => number),
  options?: { min?: number; max?: number; domain?: [number, number] },
): Accessor<T, number>;

scaleOpacityByProperty()

Creates opacity accessor (0-1 range).

function scaleOpacityByProperty<T>(
  property: keyof T | ((d: T) => number),
  options?: { min?: number; max?: number; domain?: [number, number] },
): Accessor<T, number>;

scaleByProperty()

Linear scaling.

function scaleByProperty<T>(
  property: keyof T | ((d: T) => number),
  options?: ScaleOptions,
): Accessor<T, number>;

scaleSqrtByProperty()

Square root scaling (good for area-based sizing).

function scaleSqrtByProperty<T>(
  property: keyof T | ((d: T) => number),
  options?: ScaleOptions,
): Accessor<T, number>;

scaleLogByProperty()

Logarithmic scaling (good for wide-ranging values).

function scaleLogByProperty<T>(
  property: keyof T | ((d: T) => number),
  options?: ScaleOptions,
): Accessor<T, number>;

scaleByThresholds()

Discrete threshold-based scaling.

function scaleByThresholds<T>(
  property: keyof T | ((d: T) => number),
  thresholds: Array<[number, number]>, // [threshold, output]
): Accessor<T, number>;

---

See Also

• Types — Type definitions
• NHLDataManager — Higher-level data management