Merge pull request #20 from TextureHQ/ENG-3658-v-0-standardize-conditions-in-weather-plus-project

Standardize weather conditions across providers

Author: 3meeb

README.md

@@ -12,6 +12,7 @@ An awesome TypeScript weather client for fetching weather data from various weat
   - [Tomorrow.io](https://www.tomorrow.io/) (coming soon!)
   - [WeatherKit](https://developer.apple.com/weatherkit/) (coming soon!)
 - **Clean and Standardized API**: Fetch weather data using a consistent interface, regardless of the underlying provider.
+  - Standardized weather conditions across providers
 - **Built-in Caching**: Supports in-memory and Redis caching to optimize API usage and reduce latency.
 - **TypeScript Support**: Enjoy a type-safe API out of the box for better development experience.
 
@@ -231,6 +232,73 @@ try {
 }
 ```
 
+### Standardized Weather Conditions
+
+One of the key features of this library is the standardization of weather conditions across different providers. 
+This ensures that your application receives consistent condition values regardless of which provider is used. 
+
+For OpenWeather, the library uses the Weather Condition ID codes provided by the API to derive standardized conditions.
+For NWS, the library uses the textDescription field for standardization.
+
+#### Available Standardized Conditions
+
+The following standardized condition values are available:
+
+- `Blizzard` - Blizzard conditions
+- `Breezy` - Breezy conditions
+- `Clear` - Clear, sunny conditions
+- `Cloudy` - Cloudy conditions
+- `Cold` - Cold conditions
+- `Drizzle` - Light rain or drizzle
+- `Dust` - Dusty conditions
+- `Fair` - Fair weather
+- `Flurries` - Snow flurries
+- `Fog` - Foggy conditions
+- `FreezingDrizzle` - Freezing drizzle
+- `FreezingRain` - Freezing rain
+- `Hail` - Hail precipitation
+- `Haze` - Hazy conditions
+- `HeavyRain` - Heavy rain
+- `HeavySnow` - Heavy snow
+- `Hot` - Hot conditions
+- `Hurricane` - Hurricane conditions
+- `IsolatedThunderstorms` - Isolated thunderstorms
+- `LightRain` - Light rain
+- `LightSnow` - Light snow
+- `Mist` - Misty conditions
+- `Mixed` - Mixed precipitation (rain and snow)
+- `MostlyClear` - Mostly clear conditions
+- `MostlyCloudy` - Mostly cloudy conditions
+- `Overcast` - Overcast conditions
+- `PartlyCloudy` - Partly cloudy conditions
+- `Rain` - Rain (moderate)
+- `Sandstorm` - Sandstorm conditions
+- `Showers` - Rain showers
+- `Sleet` - Sleet
+- `Smoke` - Smoky conditions
+- `Snow` - Snow (moderate)
+- `Storm` - Stormy conditions
+- `Thunderstorms` - Thunderstorms
+- `Tornado` - Tornado conditions
+- `TropicalStorm` - Tropical storm conditions
+- `Windy` - Windy conditions
+- `Unknown` - Condition that couldn't be mapped to a standard value
+
+#### Accessing Standardized Conditions
+
+The weather data returned includes both the original provider-specific condition text and the standardized condition:
+
+```ts
+const weather = await weatherPlus.getWeather(40.748817, -73.985428);
+
+console.log(weather.conditions.value);     // Standardized value (e.g., "Clear")
+console.log(weather.conditions.original);  // Original provider text (e.g., "clear sky")
+```
+
+For OpenWeather, the standardization is based on the API's Weather Condition ID codes as documented at [OpenWeather Weather Conditions](https://openweathermap.org/weather-conditions).
+
+This allows you to display either the original detailed condition from the provider or use the standardized value for consistent UI elements or logic across your application.
+
 ### TypeScript Support
 
 This library is built with TypeScript and includes type-safe interfaces for weather data and errors.
@@ -253,8 +321,9 @@ interface IWeatherData {
     unit: string;
   };
   conditions: {
-    value: string;
-    unit: string;
+    value: string;           // Standardized condition across providers
+    unit: string;            // Always "string"
+    original: string;        // Original provider condition text
   };
 }
 ```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "weather-plus",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Weather Plus is a powerful wrapper around various Weather APIs that simplifies adding weather data to your application",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",

src/index.test.ts

@@ -126,8 +126,9 @@ describe('WeatherPlus Library', () => {
         unit: 'C',
       },
       conditions: {
-        value: 'Sunny',
+        value: 'Clear',
         unit: 'string',
+        original: 'Sunny'
       },
       provider: 'nws',
       cached: false,
@@ -190,7 +191,11 @@ describe('WeatherPlus Library', () => {
     expect(response).toBeDefined();
     expect(response.temperature).toEqual({ value: 15, unit: 'C' });
     expect(response.humidity).toEqual({ value: 82, unit: 'percent' });
-    expect(response.conditions).toEqual({ value: 'light rain', unit: 'string' });
+    expect(response.conditions).toEqual({ 
+      value: 'Light Rain', 
+      unit: 'string',
+      original: 'light rain' 
+    });
   });
 
   it('should throw an error if all providers fail', async () => {

src/interfaces.ts

@@ -32,5 +32,7 @@ export type IBaseWeatherProperty<T, U extends IWeatherUnits> = {
 
 export type IRelativeHumidity = IBaseWeatherProperty<number, IWeatherUnits.percent>;
 export type IDewPoint = IBaseWeatherProperty<number, IWeatherUnits.C | IWeatherUnits.F>;
-export type IConditions = IBaseWeatherProperty<string, IWeatherUnits.string>;
+export type IConditions = IBaseWeatherProperty<string, IWeatherUnits.string> & {
+    original?: string;    // Original provider-specific condition value
+}
 export type ITemperature = IBaseWeatherProperty<number, IWeatherUnits.C | IWeatherUnits.F>;

src/providers/nws/client.test.ts

@@ -64,7 +64,11 @@ describe('NWSProvider', () => {
       dewPoint: { value: 10, unit: 'C' },
       humidity: { value: 80, unit: 'percent' },
       temperature: { value: 20, unit: 'C' },
-      conditions: { value: 'Clear', unit: 'string' },
+      conditions: { 
+        value: 'Clear', 
+        unit: 'string',
+        original: 'Clear'
+      },
     });
   });
 
@@ -131,7 +135,11 @@ describe('NWSProvider', () => {
       dewPoint: { value: 10, unit: 'C' },
       humidity: { value: 80, unit: 'percent' },
       temperature: { value: 20, unit: 'C' },
-      conditions: { value: 'Clear', unit: 'string' },
+      conditions: { 
+        value: 'Clear', 
+        unit: 'string',
+        original: 'Clear'
+      },
     });
   });
 });

src/providers/nws/client.ts

@@ -10,6 +10,7 @@ import {
 import { IWeatherProvider } from '../IWeatherProvider';
 import { InvalidProviderLocationError } from '../../errors'; // Import the error class
 import { isLocationInUS } from '../../utils/locationUtils';
+import { standardizeCondition } from './condition';
 
 const log = debug('weather-plus:nws:client');
 
@@ -151,6 +152,7 @@ async function fetchLatestObservation(
 
 function convertToWeatherData(observation: any): IWeatherProviderWeatherData {
   const properties = observation.properties;
+  
   return {
     dewPoint: {
       value: properties.dewpoint.value,
@@ -171,8 +173,9 @@ function convertToWeatherData(observation: any): IWeatherProviderWeatherData {
           : IWeatherUnits.F,
     },
     conditions: {
-      value: properties.textDescription,
+      value: standardizeCondition(properties.textDescription),
       unit: IWeatherUnits.string,
+      original: properties.textDescription
     },
   };
 }

src/providers/nws/condition.test.ts

@@ -0,0 +1,28 @@
+import { standardizeCondition } from './condition';
+import { StandardWeatherCondition } from '../../weatherCondition';
+
+describe('NWS Conditions', () => {
+  it('should standardize NWS conditions correctly', () => {
+    // Test a sample of NWS conditions
+    expect(standardizeCondition('Clear')).toEqual(StandardWeatherCondition.Clear);
+    expect(standardizeCondition('Sunny')).toEqual(StandardWeatherCondition.Clear);
+    expect(standardizeCondition('Mostly Clear')).toEqual(StandardWeatherCondition.MostlyClear);
+    expect(standardizeCondition('Partly Cloudy')).toEqual(StandardWeatherCondition.PartlyCloudy);
+    expect(standardizeCondition('Mostly Cloudy')).toEqual(StandardWeatherCondition.MostlyCloudy);
+    expect(standardizeCondition('Overcast')).toEqual(StandardWeatherCondition.Overcast);
+    expect(standardizeCondition('Light Rain')).toEqual(StandardWeatherCondition.LightRain);
+    expect(standardizeCondition('Heavy Rain')).toEqual(StandardWeatherCondition.HeavyRain);
+    expect(standardizeCondition('Fog')).toEqual(StandardWeatherCondition.Fog);
+    expect(standardizeCondition('Mist')).toEqual(StandardWeatherCondition.Mist);
+    expect(standardizeCondition('Haze')).toEqual(StandardWeatherCondition.Haze);
+    expect(standardizeCondition('Thunderstorm')).toEqual(StandardWeatherCondition.Thunderstorms);
+    expect(standardizeCondition('Hail')).toEqual(StandardWeatherCondition.Hail);
+    expect(standardizeCondition('Mixed Precipitation')).toEqual(StandardWeatherCondition.Mixed);
+    expect(standardizeCondition('Hail')).toEqual(StandardWeatherCondition.Hail);
+    expect(standardizeCondition('Mixed Precipitation')).toEqual(StandardWeatherCondition.Mixed);
+  });
+
+  it('should return unknown for unrecognized conditions', () => {
+    expect(standardizeCondition('SomeUnknownCondition')).toEqual(StandardWeatherCondition.Unknown);
+  });
+});

src/providers/nws/condition.ts

@@ -0,0 +1,52 @@
+import debug from 'debug';
+import { StandardWeatherCondition } from '../../weatherCondition';
+
+const log = debug('weather-plus:nws:conditions');
+
+// Mapping table for NWS condition texts
+const nwsConditionsMap: Record<string, StandardWeatherCondition> = {
+  'Clear': StandardWeatherCondition.Clear,
+  'Sunny': StandardWeatherCondition.Clear,
+  'Mostly Clear': StandardWeatherCondition.MostlyClear,
+  'Mostly Sunny': StandardWeatherCondition.MostlyClear,
+  'Partly Cloudy': StandardWeatherCondition.PartlyCloudy,
+  'Partly Sunny': StandardWeatherCondition.PartlyCloudy,
+  'Mostly Cloudy': StandardWeatherCondition.MostlyCloudy,
+  'Cloudy': StandardWeatherCondition.Cloudy,
+  'Overcast': StandardWeatherCondition.Overcast,
+  'Light Rain': StandardWeatherCondition.LightRain,
+  'Rain': StandardWeatherCondition.Rain,
+  'Heavy Rain': StandardWeatherCondition.HeavyRain,
+  'Light Snow': StandardWeatherCondition.LightSnow,
+  'Snow': StandardWeatherCondition.Snow,
+  'Heavy Snow': StandardWeatherCondition.HeavySnow,
+  'Fog': StandardWeatherCondition.Fog,
+  'Haze': StandardWeatherCondition.Haze,
+  'Mist': StandardWeatherCondition.Mist,
+  'Thunderstorm': StandardWeatherCondition.Thunderstorms,
+  'Thunderstorms': StandardWeatherCondition.Thunderstorms,
+  'Windy': StandardWeatherCondition.Windy,
+  'Breezy': StandardWeatherCondition.Breezy,
+  'Sleet': StandardWeatherCondition.Sleet,
+  'Freezing Rain': StandardWeatherCondition.FreezingRain,
+  'Hail': StandardWeatherCondition.Hail,
+  'Rain/Snow': StandardWeatherCondition.Mixed,
+  'Mixed Precipitation': StandardWeatherCondition.Mixed,
+  'Tornado': StandardWeatherCondition.Tornado,
+  'Hurricane': StandardWeatherCondition.Hurricane,
+  'Tropical Storm': StandardWeatherCondition.TropicalStorm,
+};
+
+/**
+ * Standardizes an NWS condition string to a StandardWeatherCondition
+ * @param condition The raw condition from NWS
+ * @returns Standardized weather condition string
+ */
+export function standardizeCondition(condition: string): string {
+  if (condition in nwsConditionsMap) {
+    return nwsConditionsMap[condition];
+  } else {
+    log(`Unknown NWS condition: "${condition}". Returning Unknown condition.`);
+    return StandardWeatherCondition.Unknown;
+  }
+}

src/providers/openweather/client.test.ts

@@ -26,7 +26,10 @@ describe('OpenWeatherProvider', () => {
         temp: 20,
         weather: [
           {
+            id: 800,
+            main: 'Clear',
             description: 'clear sky',
+            icon: '01d',
           },
         ],
       },
@@ -49,7 +52,11 @@ describe('OpenWeatherProvider', () => {
       dewPoint: { value: 10, unit: 'C' },
       humidity: { value: 80, unit: 'percent' },
       temperature: { value: 20, unit: 'C' },
-      conditions: { value: 'clear sky', unit: 'string' },
+      conditions: { 
+        value: 'Clear', 
+        unit: 'string', 
+        original: 'clear sky'
+      },
     });
   });
 

src/providers/openweather/client.ts

@@ -3,6 +3,7 @@ import debug from 'debug';
 import { IWeatherUnits, IWeatherProviderWeatherData } from '../../interfaces';
 import { IOpenWeatherResponse } from './interfaces';
 import { IWeatherProvider } from '../IWeatherProvider';
+import { standardizeCondition} from './condition';
 
 const log = debug('weather-plus:openweather:client');
 
@@ -40,6 +41,8 @@ export class OpenWeatherProvider implements IWeatherProvider {
 }
 
 function convertToWeatherData(data: IOpenWeatherResponse): IWeatherProviderWeatherData {
+  const weatherData = data.current.weather[0];
+  
   return {
     dewPoint: {
       value: data.current.dew_point,
@@ -54,8 +57,9 @@ function convertToWeatherData(data: IOpenWeatherResponse): IWeatherProviderWeath
       unit: IWeatherUnits.C,
     },
     conditions: {
-      value: data.current.weather[0].description,
+      value: standardizeCondition(weatherData.id),
       unit: IWeatherUnits.string,
+      original: weatherData.description,
     },
   };
 }