openskidata-format 0.15.0 → 2.0.0

package/dist/SkiArea.d.ts

@@ -1,39 +1,76 @@
-import { Activity } from './Activity';
 import { FeatureType } from './FeatureType';
 import { LiftType } from './Lift';
 import { Location } from './Location';
-import { RunConvention, RunDifficulty } from './Run';
-import Source from './Source';
+import { RunDifficulty, RunDifficultyConvention } from './Run';
+import { Source } from './Source';
 import { Status } from './Status';
+/**
+ * A ski area feature is derived from several sources:
+ * - OpenStreetMap site=piste relations
+ * - OpenStreetMap landuse=winter_sports areas that contains ski runs
+ * - Skimap.org ski areas
+ *
+ * The processor attempts to merge the data of all sources to create a single ski area feature.
+ *
+ * In some cases merging may fail and duplicate ski areas will be produced. This is likely due to ambiguous data.
+ * Check:
+ * - that a site=piste relation contains all the lifts/runs. If many lifts/runs are missing, merging will fail.
+ * - that if there are multiple landuse=winter_sports areas representing a single ski area. In this case a multipolygon relation should be used.
+ * - that if there are multiple Skimap.org ski areas representing a single ski area.
+ *
+ * General recommendation for ski area tagging in OpenStreetMap:
+ * - start with a landuse=winter_sports area as it's easy to set up and maintain.
+ * - if that's not explicit enough, add a site=piste relation as well.
+ *
+ * Note: if runs are present but there is no associated ski area source, a ski area feature is generated with no name and no source.
+ */
 export type SkiAreaFeature = GeoJSON.Feature<SkiAreaGeometry, SkiAreaProperties>;
 export type SkiAreaGeometry = GeoJSON.Point | GeoJSON.Polygon | GeoJSON.MultiPolygon;
-export interface SkiAreaProperties {
-    type: FeatureType.SkiArea;
-    id: string;
-    name: string | null;
+export type SkiAreaSummaryFeature = GeoJSON.Feature<SkiAreaGeometry, SkiAreaSummaryProperties>;
+/**
+ * @property {string} id - Unique identifier for the ski area. The ID is just a hash of the feature, so will change if the feature changes in any way. If a stable identifier is needed, use the wikidata_id property, or a source id.
+ * @property {string | null} name - Name of the ski area.
+ * @property {Source[]} sources - Data sources.
+ * @property {SkiAreaActivity[]} activities - Activities available at this ski area, derived from presence of ski runs and Skimap.org data.
+ * @property {SkiAreaStatistics} statistics - Statistics generated from associated runs / lifts.
+ * @property {Status | null} status - Operational status. Derived from OpenStreetMap lifecycle tags and Skimap.org data.
+ * @property {RunColorConvention} runConvention - Color convention used for runs at this ski area.
+ * @property {string[]} websites - Official website(s) of the ski area. Derived from the OpenStreetMap website tag and Skimap.org data.
+ * @property {string | null} wikidata_id - Wikidata identifier. Derived from the OpenStreetMap wikidata tag.
+ * @property {Location | null} location - Reverse geocoded country / region information.
+ */
+export type SkiAreaProperties = SkiAreaSummaryProperties & {
     sources: Source[];
-    activities: Activity[];
-    generated: boolean;
     statistics?: SkiAreaStatistics;
-    status: Status | null;
-    runConvention: RunConvention;
+    runConvention: RunDifficultyConvention;
     websites: string[];
     wikidata_id: string | null;
+};
+export type SkiAreaSummaryProperties = {
+    type: FeatureType.SkiArea;
+    id: string;
+    name: string | null;
+    activities: SkiAreaActivity[];
+    status: Status | null;
     location: Location | null;
+};
+export declare enum SkiAreaActivity {
+    Downhill = "downhill",
+    Nordic = "nordic"
 }
-export interface SkiAreaStatistics {
+export type SkiAreaStatistics = {
     runs: RunStatistics;
     lifts: LiftStatistics;
     minElevation?: number;
     maxElevation?: number;
-}
-export interface RunStatistics {
+};
+export type RunStatistics = {
     minElevation?: number;
     maxElevation?: number;
     byActivity: RunStatisticsByActivityAndDifficulty;
-}
+};
 export type RunStatisticsByActivityAndDifficulty = {
-    [key in Activity | 'other']?: {
+    [key in SkiAreaActivity | 'other']?: {
         byDifficulty: RunStatisticsByDifficulty;
     };
 };
@@ -43,11 +80,11 @@ export type RunStatisticsByDifficulty = {
         lengthInKm: number;
     };
 };
-export interface LiftStatistics {
+export type LiftStatistics = {
     minElevation?: number;
     maxElevation?: number;
     byType: LiftStatisticsByType;
-}
+};
 export type LiftStatisticsByTypeKey = LiftType | 'other';
 export type LiftStatisticsByType = {
     [key in LiftStatisticsByTypeKey]?: {
@@ -55,10 +92,3 @@ export type LiftStatisticsByType = {
         lengthInKm: number;
     };
 };
-export interface MapObjectStatistics {
-    count: number;
-    lengthInKm: number;
-    minElevation?: number;
-    maxElevation?: number;
-    combinedElevationChange?: number;
-}

package/dist/SkiArea.js

@@ -1,3 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkiAreaActivity = void 0;
+var SkiAreaActivity;
+(function (SkiAreaActivity) {
+    SkiAreaActivity["Downhill"] = "downhill";
+    SkiAreaActivity["Nordic"] = "nordic";
+})(SkiAreaActivity || (exports.SkiAreaActivity = SkiAreaActivity = {}));
 //# sourceMappingURL=SkiArea.js.map

package/dist/SkiArea.js.map

@@ -1 +1 @@
-{"version":3,"file":"SkiArea.js","sourceRoot":"","sources":["../src/SkiArea.ts"],"names":[],"mappings":""}
+{"version":3,"file":"SkiArea.js","sourceRoot":"","sources":["../src/SkiArea.ts"],"names":[],"mappings":";;;AAoEA,IAAY,eAGX;AAHD,WAAY,eAAe;IACzB,wCAAqB,CAAA;IACrB,oCAAiB,CAAA;AACnB,CAAC,EAHW,eAAe,+BAAf,eAAe,QAG1B"}

package/dist/Source.d.ts

@@ -2,7 +2,7 @@ export declare enum SourceType {
     SKIMAP_ORG = "skimap.org",
     OPENSTREETMAP = "openstreetmap"
 }
-export default interface Source {
+export type Source = {
     type: SourceType;
     id: string;
-}
+};

package/dist/Status.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Status of a feature.
+ *
+ * Note that this is not real-time status but indicates whether a feature is in operation when conditions permit or is abandoned, etc.
+ *
+ * Primarily derived from OpenStreetMap tags.
+ * Additionally, Skimap.org data provides status information for ski area features only.
+ *
+ * Tagging schemes supported are:
+ * - lifecycle prefixes (preferred) https://wiki.openstreetmap.org/wiki/Lifecycle_prefix
+ * - separate lifecycle tags ("proposed=yes", etc)
+ */
 export declare enum Status {
     Operating = "operating",
     Disused = "disused",

package/dist/Status.js

@@ -1,6 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Status = void 0;
+/**
+ * Status of a feature.
+ *
+ * Note that this is not real-time status but indicates whether a feature is in operation when conditions permit or is abandoned, etc.
+ *
+ * Primarily derived from OpenStreetMap tags.
+ * Additionally, Skimap.org data provides status information for ski area features only.
+ *
+ * Tagging schemes supported are:
+ * - lifecycle prefixes (preferred) https://wiki.openstreetmap.org/wiki/Lifecycle_prefix
+ * - separate lifecycle tags ("proposed=yes", etc)
+ */
 var Status;
 (function (Status) {
     Status["Operating"] = "operating";

package/dist/Status.js.map

@@ -1 +1 @@
-{"version":3,"file":"Status.js","sourceRoot":"","sources":["../src/Status.ts"],"names":[],"mappings":";;;AAAA,IAAY,MAOX;AAPD,WAAY,MAAM;IAChB,iCAAuB,CAAA;IACvB,6BAAmB,CAAA;IACnB,iCAAuB,CAAA;IACvB,+BAAqB,CAAA;IACrB,6BAAmB,CAAA;IACnB,uCAA6B,CAAA;AAC/B,CAAC,EAPW,MAAM,sBAAN,MAAM,QAOjB"}
+{"version":3,"file":"Status.js","sourceRoot":"","sources":["../src/Status.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACH,IAAY,MAOX;AAPD,WAAY,MAAM;IAChB,iCAAuB,CAAA;IACvB,6BAAmB,CAAA;IACnB,iCAAuB,CAAA;IACvB,+BAAqB,CAAA;IACrB,6BAAmB,CAAA;IACnB,uCAA6B,CAAA;AAC/B,CAAC,EAPW,MAAM,sBAAN,MAAM,QAOjB"}

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-export * from './Activity';
 export * from './ElevationProfile';
 export * from './FeatureType';
 export * from './Lift';

package/dist/index.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./Activity"), exports);
 tslib_1.__exportStar(require("./ElevationProfile"), exports);
 tslib_1.__exportStar(require("./FeatureType"), exports);
 tslib_1.__exportStar(require("./Lift"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qDAA0B;AAC1B,6DAAkC;AAClC,wDAA6B;AAC7B,iDAAsB;AACtB,8DAAmC;AACnC,qDAA0B;AAC1B,gDAAqB;AACrB,oDAAyB;AACzB,mDAAwB;AACxB,mDAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAAkC;AAClC,wDAA6B;AAC7B,iDAAsB;AACtB,8DAAmC;AACnC,qDAA0B;AAC1B,gDAAqB;AACrB,oDAAyB;AACzB,mDAAwB;AACxB,mDAAwB"}

package/dist/util/exhaustiveMatchingGuard.d.ts

@@ -0,0 +1 @@
+export declare const exhaustiveMatchingGuard: (value: never) => never;

package/dist/util/exhaustiveMatchingGuard.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exhaustiveMatchingGuard = void 0;
+const exhaustiveMatchingGuard = (value) => {
+    throw new Error(`Unhandled case: ${value}`);
+};
+exports.exhaustiveMatchingGuard = exhaustiveMatchingGuard;
+//# sourceMappingURL=exhaustiveMatchingGuard.js.map

package/dist/util/exhaustiveMatchingGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exhaustiveMatchingGuard.js","sourceRoot":"","sources":["../../src/util/exhaustiveMatchingGuard.ts"],"names":[],"mappings":";;;AAAO,MAAM,uBAAuB,GAAG,CAAC,KAAY,EAAS,EAAE;IAC7D,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,EAAE,CAAC,CAAA;AAC7C,CAAC,CAAA;AAFY,QAAA,uBAAuB,2BAEnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openskidata-format",
-  "version": "0.15.0",
+  "version": "2.0.0",
   "description": "Data format for OpenSkiMap.org",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/ElevationProfile.ts

@@ -1,8 +1,12 @@
-export interface ElevationProfile {
-  // Heights are evenly distributed along the LineString with a frequency based on the resolution below.
-  // The final height corresponds to the end of the LineString and will not be the same space between the previous point as the rest.
-  // The corresponding coordinates can be computed from the original geometry using Turf.js: `turf.lineChunk(geometry, resolution, {units: 'meters'});`
+/**
+ * Represents an elevation profile with evenly distributed height measurements along a LineString.
+ *
+ * @property {number[]} heights - Array of height measurements in meters. These heights are sampled at regular intervals along the LineString,
+ * except for the final height which corresponds to the LineString endpoint and may have a different spacing.
+ * Height values can be mapped to geographical coordinates using Turf.js: `turf.lineChunk(geometry, resolution, {units: 'meters'})`.
+ * @property {number} resolution - The horizontal sampling distance in meters between consecutive height measurements.
+ */
+export type ElevationProfile = {
   heights: number[]
-  // Horizontal resolution in meters of the profile
   resolution: number
 }

package/src/Lift.ts

@@ -1,7 +1,8 @@
-import { Location, SkiAreaFeature } from '.'
 import { FeatureType } from './FeatureType'
-import Source from './Source'
+import { SkiAreaSummaryFeature } from './SkiArea'
+import { Source } from './Source'
 import { Status } from './Status'
+import { exhaustiveMatchingGuard } from './util/exhaustiveMatchingGuard'
 
 export type LiftFeature = GeoJSON.Feature<LiftGeometry, LiftProperties>
 
@@ -13,12 +14,41 @@ export type LiftGeometry =
   | GeoJSON.Polygon
   | GeoJSON.MultiPolygon
 
+/**
+ * A feature representing a ski lift.
+ *
+ * Lifts are derived from OpenStreetMap aerialway/railway features that are commonly used for winter sports.
+ *
+ * Note:
+ * - Private lifts are not included in this dataset.
+ * - Rack railways are included only if they are part of a site=piste relation.
+ * - Some lifts included in the dataset may be for other purposes (amusement parks, etc).
+ *
+ * Properties:
+ * @property {FeatureType.Lift} type - The feature type, which is always 'Lift'.
+ * @property {string} id - Unique identifier for the lift. The ID is just a hash of the feature, so will change if the feature changes in any way.
+ * @property {LiftType} liftType - Type of lift (e.g. chair_lift, gondola). Derived from OpenStreetMap aerialway/railway tags.
+ * @property {Status} status - Operational status of the lift. Derived from OpenStreetMap lifecycle tags.
+ * @property {string | null} name - Name of the lift. Derived from the OpenStreetMap name tag.
+ * @property {string | null} ref - Reference code/number for the lift. Derived from the OpenStreetMap ref tag.
+ * @property {string | null} description - Description of the lift. Derived from the OpenStreetMap description tag.
+ * @property {boolean | null} oneway - Whether the lift allows riding only in one direction. Derived from the OpenStreetMap oneway tag.
+ * @property {number | null} occupancy - Number of people each carrier can transport. Derived from the OpenStreetMap aerialway:occupancy tag.
+ * @property {number | null} capacity - Transport capacity in persons/hour. Derived from the OpenStreetMap aerialway:capacity tag.
+ * @property {number | null} duration - Duration of lift ride in seconds. Derived from the OpenStreetMap aerialway:duration tag.
+ * @property {boolean | null} detachable - Whether the lift has detachable grips. Derived from the OpenStreetMap aerialway:detachable tag.
+ * @property {boolean | null} bubble - Whether the lift has bubbles/covers to protect from weather. Derived from the OpenStreetMap aerialway:bubble tag.
+ * @property {boolean | null} heating - Whether the lift has heated carriers/seats. Derived from the OpenStreetMap aerialway:heating tag.
+ * @property {SkiAreaSummaryFeature[]} skiAreas - Ski areas this lift is a part of.
+ * @property {Source[]} sources - Data sources for the feature.
+ * @property {string[]} websites - Websites associated with this lift. Derived from the OpenStreetMap website tag.
+ * @property {string | null} wikidata_id - Wikidata identifier. Derived from the OpenStreetMap wikidata tag.
+ */
 export type LiftProperties = {
   type: FeatureType.Lift
   id: string
   liftType: LiftType
   status: Status
-  color: string
   name: string | null
   ref: string | null
   description: string | null
@@ -26,11 +56,11 @@ export type LiftProperties = {
   occupancy: number | null
   capacity: number | null
   duration: number | null
+  detachable: boolean | null
   bubble: boolean | null
   heating: boolean | null
-  skiAreas: SkiAreaFeature[]
+  skiAreas: SkiAreaSummaryFeature[]
   sources: Source[]
-  location: Location | null
   websites: string[]
   wikidata_id: string | null
 }
@@ -76,5 +106,25 @@ export function getFormattedLiftType(liftType: LiftType): string {
       return 'Funicular'
     case LiftType.RackRailway:
       return 'Rack Railway'
+    default:
+      return exhaustiveMatchingGuard(liftType)
+  }
+}
+
+export function getLiftColor(status: Status): string {
+  const BRIGHT_RED_COLOR = 'hsl(0, 82%, 42%)'
+  const DIM_RED_COLOR = 'hsl(0, 53%, 42%)'
+
+  switch (status) {
+    case Status.Disused:
+    case Status.Abandoned:
+      return DIM_RED_COLOR
+    case Status.Proposed:
+    case Status.Planned:
+    case Status.Construction:
+    case Status.Operating:
+      return BRIGHT_RED_COLOR
+    default:
+      return exhaustiveMatchingGuard(status)
   }
 }

package/src/LiftNameFormatter.ts

@@ -1,5 +1,4 @@
-import { LiftProperties, LiftType } from '.'
-import { getFormattedLiftType } from './Lift'
+import { LiftProperties, LiftType, getFormattedLiftType } from './Lift'
 
 export function getLiftNameAndType(properties: LiftProperties) {
   const name = properties.name
@@ -7,7 +6,7 @@ export function getLiftNameAndType(properties: LiftProperties) {
   const liftType = getAugmentedLiftType(properties)
 
   if (name && liftType) {
-    return name + ' (' + liftType + ')'
+    return `${name} (${liftType})`
   } else if (name) {
     return name
   } else {
@@ -54,15 +53,11 @@ function getAugmentedLiftType(properties: LiftProperties): string | null {
 }
 
 function formattedDuration(duration: number): string {
-  let minutes: string | number = Math.floor(duration / 60)
-  let seconds: string | number = duration - minutes * 60
-  if (minutes < 10) {
-    minutes = '0' + minutes
-  }
-  if (seconds < 10) {
-    seconds = '0' + seconds
-  }
-  return minutes + ':' + seconds
+  const minutes = Math.floor(duration / 60)
+    .toString()
+    .padStart(2, '0')
+  const seconds = (duration % 60).toString().padStart(2, '0')
+  return `${minutes}:${seconds}`
 }
 
 function implicitOccupancyLiftType(properties: LiftProperties): string | null {
@@ -130,9 +125,7 @@ function containsAny(input: string | null, lowerCaseSearchList: string[]) {
   }
 
   const lowerCaseInput = input.toLowerCase()
-  return (
-    lowerCaseSearchList.findIndex((searchItem) => {
-      return lowerCaseInput.includes(searchItem)
-    }) !== -1
-  )
+  return lowerCaseSearchList.some((searchItem) => {
+    return lowerCaseInput.includes(searchItem)
+  })
 }

package/src/Run.ts

@@ -1,15 +1,55 @@
 import * as GeoJSON from 'geojson'
 import { ElevationProfile } from './ElevationProfile'
 import { FeatureType } from './FeatureType'
-import { Location } from './Location'
-import { SkiAreaFeature } from './SkiArea'
-import Source from './Source'
+import { SkiAreaSummaryFeature } from './SkiArea'
+import { Source } from './Source'
 import { Status } from './Status'
+import { exhaustiveMatchingGuard } from './util/exhaustiveMatchingGuard'
 
 export type RunGeometry = GeoJSON.LineString | GeoJSON.Polygon
 
+/**
+ * Represents a segment of a ski run/trail.
+ *
+ * Runs are derived from OpenStreetMap pistes, which are defined as all ways/areas/relations containing a "piste:type" tag.
+ * Piste relations support is limited, it is only used to enhance the data of its member ways. There is no way to access the relation itself in the output data.
+ *
+ * A single run as marked on the mountain may be broken up into several run features, especially if the run has branches, or changes in tags (e.g. difficulty, use).
+ *
+ * In the future, there might be a "Route" entity introduced to represent a whole run, which would be composed of multiple run features.
+ *
+ * Note: winter hiking trails and trails of other winter sports disciplines are also included in this dataset.
+ *
+ * In postprocessing:
+ * - overlapping ways are merged into a single run feature with multiple uses.
+ * - connected run segments with the same properties are merged into a single run feature.
+ */
 export type RunFeature = GeoJSON.Feature<RunGeometry, RunProperties>
 
+/**
+ * Represents the properties of a ski run.
+ *
+ * Properties:
+ * @property {FeatureType.Run} type - The feature type, which is always 'Run'.
+ * @property {RunUse[]} uses - Use types for the run (e.g. downhill, nordic), derived from OpenStreetMap "piste:type" tags.
+ * @property {string} id - Unique identifier for the run. The ID is just a hash of the feature, so will change if the feature changes in any way.
+ * @property {string | null} name - Name of the run, if available
+ * @property {string | null} ref - Reference code/number for the run. Derived from the OpenStreetMap piste:ref and ref tags.
+ * @property {Status} status - Operational status. Note: as only operational runs are included in this dataset, this will always be 'operating'.
+ * @property {string | null} description - Description of the run, derived from the OpenStreetMap "piste:description" or "description" tag.
+ * @property {RunDifficulty | null} difficulty - Difficulty rating of the run, derived from the OpenStreetMap "piste:difficulty" tag
+ * @property {RunDifficultyConvention} difficultyConvention - Regional convention used for representing run difficulty. Derived from location.
+ * @property {boolean | null} oneway - Whether the run is one-way only, derived from the OpenStreetMap "piste:oneway" or "oneway" tag, in addition to defaults based on run use.
+ * @property {boolean | null} lit - Whether the run has lighting for night skiing, derived from the OpenStreetMap "piste:lit" or "lit" tag.
+ * @property {boolean | null} gladed - Whether the run is through gladed/tree terrain, derived from the OpenStreetMap "piste:gladed" or "gladed" tag.
+ * @property {boolean | null} patrolled - Whether the run is patrolled by ski patrol, derived from the OpenStreetMap "piste:patrolled" or "patrolled" tag.
+ * @property {RunGrooming | null} grooming - Grooming status/type of the run, derived from the OpenStreetMap "piste:grooming" tag. If not specified explicitly, for difficulties "expert", "freeride", and "extreme", grooming is assumed to be "backcountry".
+ * @property {SkiAreaSummaryFeature[]} skiAreas - Ski areas this run belongs to. Derived from the OpenStreetMap site=piste relation or landuse=winter_sports area and proximity to ski area features. Runs with "backcountry" grooming are not associated with ski areas unless they have a "piste:patrolled=yes" or "patrolled=yes" OpenStreetMap tag, or are part of a "site=piste" ski area relation.
+ * @property {ElevationProfile | null} elevationProfile - Elevation profile of the run, only available for runs with LineString geometry.
+ * @property {Source[]} sources - Data sources for this run's information
+ * @property {string[]} websites - Websites associated with this run, derived from the OpenStreetMap website tag
+ * @property {string | null} wikidata_id - Wikidata identifier, if available, derived from the OpenStreetMap wikidata tag
+ */
 export type RunProperties = {
   type: FeatureType.Run
   uses: RunUse[]
@@ -19,18 +59,15 @@ export type RunProperties = {
   status: Status
   description: string | null
   difficulty: RunDifficulty | null
-  convention: RunConvention
+  difficultyConvention: RunDifficultyConvention
   oneway: boolean | null
   lit: boolean | null
   gladed: boolean | null
   patrolled: boolean | null
-  color: string
-  colorName: ColorName
   grooming: RunGrooming | null
-  skiAreas: SkiAreaFeature[]
+  skiAreas: SkiAreaSummaryFeature[]
   elevationProfile: ElevationProfile | null
   sources: Source[]
-  location: Location | null
   websites: string[]
   wikidata_id: string | null
 }
@@ -68,7 +105,7 @@ export enum RunDifficulty {
   EXTREME = 'extreme',
 }
 
-export enum ColorName {
+export enum RunColorName {
   GREEN = 'green',
   BLUE = 'blue',
   RED = 'red',
@@ -77,92 +114,130 @@ export enum ColorName {
   GREY = 'grey',
 }
 
-export enum RunConvention {
+export enum RunColorValue {
+  GREEN = 'hsl(125, 100%, 33%)',
+  BLUE = 'hsl(208, 100%, 33%)',
+  RED = 'hsl(359, 94%, 53%)',
+  BLACK = 'hsl(0, 0%, 0%)',
+  ORANGE = 'hsl(34, 100%, 50%)',
+  GREY = 'hsl(0, 0%, 35%)',
+}
+
+/**
+ * Run difficulty colors vary by region. This enum defines the color convention used for runs at a ski area.
+ * @enum {string}
+ */
+export enum RunDifficultyConvention {
+  /**
+   * European color convention:
+   * - Green: Novice
+   * - Blue: Easy
+   * - Red: Intermediate
+   * - Black: Advanced/Expert
+   * - Orange: Freeride/Extreme
+   */
   EUROPE = 'europe',
+
+  /**
+   * Japanese color convention:
+   * - Green: Novice/Easy
+   * - Red: Intermediate
+   * - Black: Advanced/Expert
+   * - Orange: Freeride/Extreme
+   */
   JAPAN = 'japan',
+
+  /**
+   * North American color convention:
+   * - Green: Novice/Easy
+   * - Blue: Intermediate
+   * - Black: Advanced/Expert
+   * - Orange: Freeride/Extreme
+   */
   NORTH_AMERICA = 'north_america',
 }
 
-// When adding a new color, add a supplemental oneway icon on the map style
-const GREEN_COLOR = 'hsl(125, 100%, 33%)'
-const BLUE_COLOR = 'hsl(208, 100%, 33%)'
-const RED_COLOR = 'hsl(359, 94%, 53%)'
-const BLACK_COLOR = 'hsl(0, 0%, 0%)'
-const ORANGE_COLOR = 'hsl(34, 100%, 50%)'
-const GREY_COLOR = 'hsl(0, 0%, 35%)'
+export function getRunColor(
+  convention: RunDifficultyConvention,
+  difficulty: RunDifficulty | null,
+): RunColorValue {
+  return runColorNameToValue(getRunColorName(convention, difficulty))
+}
 
-export function getColorName(color: string): ColorName {
+export function runColorNameToValue(color: RunColorName): RunColorValue {
   switch (color) {
-    case GREEN_COLOR:
-      return ColorName.GREEN
-    case BLUE_COLOR:
-      return ColorName.BLUE
-    case RED_COLOR:
-      return ColorName.RED
-    case BLACK_COLOR:
-      return ColorName.BLACK
-    case ORANGE_COLOR:
-      return ColorName.ORANGE
-    case GREY_COLOR:
-      return ColorName.GREY
+    case RunColorName.GREEN:
+      return RunColorValue.GREEN
+    case RunColorName.BLUE:
+      return RunColorValue.BLUE
+    case RunColorName.RED:
+      return RunColorValue.RED
+    case RunColorName.BLACK:
+      return RunColorValue.BLACK
+    case RunColorName.ORANGE:
+      return RunColorValue.ORANGE
+    case RunColorName.GREY:
+      return RunColorValue.GREY
     default:
-      throw 'missing color'
+      throw 'invalid color'
   }
 }
 
-export function getRunColor(
-  convention: RunConvention,
+export function getRunColorName(
+  convention: RunDifficultyConvention,
   difficulty: RunDifficulty | null,
-): string {
+): RunColorName {
   switch (convention) {
-    case RunConvention.EUROPE:
+    case RunDifficultyConvention.EUROPE:
       switch (difficulty) {
         case RunDifficulty.NOVICE:
-          return GREEN_COLOR
+          return RunColorName.GREEN
         case RunDifficulty.EASY:
-          return BLUE_COLOR
+          return RunColorName.BLUE
         case RunDifficulty.INTERMEDIATE:
-          return RED_COLOR
+          return RunColorName.RED
         case RunDifficulty.ADVANCED:
         case RunDifficulty.EXPERT:
-          return BLACK_COLOR
+          return RunColorName.BLACK
         case RunDifficulty.FREERIDE:
         case RunDifficulty.EXTREME:
-          return ORANGE_COLOR
+          return RunColorName.ORANGE
         default:
-          return GREY_COLOR
+          return RunColorName.GREY
       }
-    case RunConvention.JAPAN:
+    case RunDifficultyConvention.JAPAN:
       switch (difficulty) {
         case RunDifficulty.NOVICE:
         case RunDifficulty.EASY:
-          return GREEN_COLOR
+          return RunColorName.GREEN
         case RunDifficulty.INTERMEDIATE:
-          return RED_COLOR
+          return RunColorName.RED
         case RunDifficulty.ADVANCED:
         case RunDifficulty.EXPERT:
-          return BLACK_COLOR
+          return RunColorName.BLACK
         case RunDifficulty.FREERIDE:
         case RunDifficulty.EXTREME:
-          return ORANGE_COLOR
+          return RunColorName.ORANGE
         default:
-          return GREY_COLOR
+          return RunColorName.GREY
       }
-    case RunConvention.NORTH_AMERICA:
+    case RunDifficultyConvention.NORTH_AMERICA:
       switch (difficulty) {
         case RunDifficulty.NOVICE:
         case RunDifficulty.EASY:
-          return GREEN_COLOR
+          return RunColorName.GREEN
         case RunDifficulty.INTERMEDIATE:
-          return BLUE_COLOR
+          return RunColorName.BLUE
         case RunDifficulty.ADVANCED:
         case RunDifficulty.EXPERT:
-          return BLACK_COLOR
+          return RunColorName.BLACK
         case RunDifficulty.FREERIDE:
         case RunDifficulty.EXTREME:
-          return ORANGE_COLOR
+          return RunColorName.ORANGE
         default:
-          return GREY_COLOR
+          return RunColorName.GREY
       }
+    default:
+      return exhaustiveMatchingGuard(convention)
   }
 }