Merge pull request #21 from TextureHQ/rcasto/weather-plus-add-cloudiness-some-types-and-maybe-more

Add cloudiness, sunrise + sunset (openweather), also some typing related updates

Author: rcasto

README.md

@@ -89,11 +89,11 @@ console.log(weather);
 
 One of the main benefits of this library is the ability to seamlessly switch between weather providers while maintaining a consistent API. This is particularly useful for:
 
-	•	Fallback Mechanism: Use a free provider by default and fallback to a paid provider if necessary.
-	•	Coverage: Some providers may not support certain locations; having multiple providers ensures broader coverage.
-	•	Cost Optimization: Reduce costs by prioritizing free or cheaper providers.
+- **Fallback Mechanism**: Use a free provider by default and fallback to a paid provider if necessary.
+- **Coverage**: Some providers may not support certain locations; having multiple providers ensures broader coverage.
+- **Cost Optimization**: Reduce costs by prioritizing free or cheaper providers.
 
-Available Providers
+#### Available Providers
 
 - 'nws' - National Weather Service
   - Notes:
@@ -325,10 +325,22 @@ interface IWeatherData {
     unit: string;            // Always "string"
     original: string;        // Original provider condition text
   };
+  cloudiness: {              // Percentage of cloud cover
+    value: number;
+    unit: string;            // Always "percent"
+  };
+  sunrise: {                 // Available for some providers (e.g., OpenWeather)
+    value: string;           // Sunrise time
+    unit: string;            // Always "iso8601"
+  };
+  sunset: {                  // Available for some providers (e.g., OpenWeather)
+    value: string;           // Sunset time
+    unit: string;            // Always "iso8601"
+  };
 }
 ```
 
-Note today the response is fairly basic, but we're working on adding more data all of the time.
+Note that the availability of specific data fields may vary depending on the weather provider being used. The library continues to expand with additional weather data over time.
 
 ### Complete Example
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "weather-plus",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "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",
@@ -16,6 +16,7 @@
     "test": "jest",
     "test:watch": "jest --watch",
     "prebuild": "rimraf ./dist",
+    "prepack": "npm run build",
     "coverage": "jest --coverage"
   },
   "files": [

src/index.test.ts

@@ -96,6 +96,15 @@ describe('WeatherPlus Library', () => {
             qualityControl: 'V',
           },
           textDescription: 'Sunny',
+          cloudLayers: [
+            {
+              base: {
+                unitCode: 'wmoUnit:m',
+                value: 1000,
+              },
+              amount: 'CLR',
+            },
+          ],
         },
       },
     ];
@@ -130,8 +139,13 @@ describe('WeatherPlus Library', () => {
         unit: 'string',
         original: 'Sunny'
       },
+      cloudiness: {
+        value: 0,
+        unit: 'percent',
+      },
       provider: 'nws',
       cached: false,
+      cachedAt: undefined,
     };
     expect(response).toEqual(expectedResponse);
   });
@@ -196,6 +210,7 @@ describe('WeatherPlus Library', () => {
       unit: 'string',
       original: 'light rain' 
     });
+    expect(response.cloudiness).toEqual({ value: 75, unit: 'percent' });
   });
 
   it('should throw an error if all providers fail', async () => {
@@ -265,6 +280,15 @@ describe('WeatherPlus Library', () => {
             qualityControl: 'V',
           },
           textDescription: 'Sunny',
+          cloudLayers: [
+            {
+              base: {
+                unitCode: 'wmoUnit:m',
+                value: 1000,
+              },
+              amount: 'CLR',
+            },
+          ],
         },
       },
     ];
@@ -293,6 +317,7 @@ describe('WeatherPlus Library', () => {
     expect(response1.humidity).toEqual(response2.humidity);
     expect(response1.temperature).toEqual(response2.temperature);
     expect(response1.conditions).toEqual(response2.conditions);
+    expect(response1.cloudiness).toEqual(response2.cloudiness);
   });
 
   it('should export InvalidProviderLocationError', () => {

src/index.ts

@@ -2,6 +2,7 @@ import { WeatherService } from './weatherService';
 import { InvalidProviderLocationError, ProviderNotSupportedError, WeatherProviderError } from './errors';
 import { RedisClientType } from 'redis';
 import { GetWeatherOptions } from './weatherService';
+import { IWeatherData } from './interfaces';
 
 // Define the options interface for WeatherPlus
 interface WeatherPlusOptions {
@@ -27,7 +28,7 @@ class WeatherPlus {
   }
 
   // Public method to get weather data for a given latitude and longitude
-  async getWeather(lat: number, lng: number, options?: GetWeatherOptions) {
+  async getWeather(lat: number, lng: number, options?: GetWeatherOptions): Promise<IWeatherData> {
     return this.weatherService.getWeather(lat, lng, options);
   }
 }

src/interfaces.ts

@@ -3,23 +3,33 @@ export enum IWeatherUnits {
     F = 'F',
     percent = 'percent',
     string = 'string',
+    iso8601 = 'iso8601',
 }
 
 export enum IWeatherKey {
     dewPoint = 'dewPoint',
     humidity = 'humidity',
     temperature = 'temperature',
     conditions = 'conditions',
+    cloudiness = 'cloudiness',
+    // Not available for NWS, but is available for OpenWeather
+    // We could utilize this API: https://sunrise-sunset.org/api
+    // To supply sunrise and sunset times for NWS. It's a free API, would need to add attribution.
+    sunrise = 'sunrise',
+    sunset = 'sunset',
 }
 
-export interface IWeatherProviderWeatherData {
-    [IWeatherKey.dewPoint]: IDewPoint;
-    [IWeatherKey.humidity]: IRelativeHumidity;
-    [IWeatherKey.temperature]: ITemperature;
-    [IWeatherKey.conditions]: IConditions;
+export interface IWeatherProviderWeatherData extends Record<IWeatherKey, IBaseWeatherProperty<any, any>> {
+    dewPoint: IDewPoint;
+    humidity: IRelativeHumidity;
+    temperature: ITemperature;
+    conditions: IConditions;
+    cloudiness: ICloudiness;
+    sunrise: ISunriseSunset;
+    sunset: ISunriseSunset;
 }
 
-export interface IWeatherData extends IWeatherProviderWeatherData {
+export interface IWeatherData extends Partial<IWeatherProviderWeatherData> {
     provider: string;
     cached: boolean;
     cachedAt?: string; // ISO-8601 formatted date string
@@ -35,4 +45,6 @@ export type IDewPoint = IBaseWeatherProperty<number, IWeatherUnits.C | IWeatherU
 export type IConditions = IBaseWeatherProperty<string, IWeatherUnits.string> & {
     original?: string;    // Original provider-specific condition value
 }
-export type ITemperature = IBaseWeatherProperty<number, IWeatherUnits.C | IWeatherUnits.F>;
+export type ITemperature = IBaseWeatherProperty<number, IWeatherUnits.C | IWeatherUnits.F>;
+export type ICloudiness = IBaseWeatherProperty<number, IWeatherUnits.percent>;
+export type ISunriseSunset = IBaseWeatherProperty<string, IWeatherUnits.iso8601>;

src/providers/IWeatherProvider.ts

@@ -2,5 +2,5 @@ import { IWeatherProviderWeatherData } from '../interfaces';
 
 export interface IWeatherProvider {
   name: string;
-  getWeather(lat: number, lng: number): Promise<IWeatherProviderWeatherData>;
+  getWeather(lat: number, lng: number): Promise<Partial<IWeatherProviderWeatherData>>;
 }

src/providers/nws/client.test.ts

@@ -38,6 +38,9 @@ describe('NWSProvider', () => {
       relativeHumidity: { value: 80 },
       temperature: { value: 20, unitCode: 'wmoUnit:degC' },
       textDescription: 'Clear',
+      cloudLayers: [
+        { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'CLR' }
+      ],
     },
   };
 
@@ -69,6 +72,10 @@ describe('NWSProvider', () => {
         unit: 'string',
         original: 'Clear'
       },
+      cloudiness: {
+        value: 0,
+        unit: 'percent'
+      },
     });
   });
 
@@ -140,6 +147,10 @@ describe('NWSProvider', () => {
         unit: 'string',
         original: 'Clear'
       },
+      cloudiness: {
+        value: 0,
+        unit: 'percent'
+      },
     });
   });
 });

src/providers/nws/client.ts

@@ -1,6 +1,6 @@
 import axios from 'axios';
 import debug from 'debug';
-import { IWeatherData, IWeatherKey, IWeatherProviderWeatherData, IWeatherUnits } from '../../interfaces';
+import { IWeatherKey, IWeatherProviderWeatherData, IWeatherUnits } from '../../interfaces';
 import {
   IGridpointsStations,
   IPointsLatLngResponse,
@@ -11,6 +11,7 @@ import { IWeatherProvider } from '../IWeatherProvider';
 import { InvalidProviderLocationError } from '../../errors'; // Import the error class
 import { isLocationInUS } from '../../utils/locationUtils';
 import { standardizeCondition } from './condition';
+import { getCloudinessFromCloudLayers } from './cloudiness';
 
 const log = debug('weather-plus:nws:client');
 
@@ -19,16 +20,16 @@ export const WEATHER_KEYS = Object.values(IWeatherKey);
 export class NWSProvider implements IWeatherProvider {
   name = 'nws';
 
-  public async getWeather(lat: number, lng: number): Promise<IWeatherProviderWeatherData> {
+  public async getWeather(lat: number, lng: number): Promise<Partial<IWeatherProviderWeatherData>> {
     // Check if the location is within the US
     if (!isLocationInUS(lat, lng)) {
       throw new InvalidProviderLocationError(
         'The NWS provider only supports locations within the United States.'
       );
     }
 
-    const data: Partial<IWeatherData> = {};
-    const weatherData: IWeatherProviderWeatherData[] = [];
+    const data: Partial<IWeatherProviderWeatherData> = {};
+    const weatherData: Partial<IWeatherProviderWeatherData>[] = [];
 
     try {
       const observationStations = await fetchObservationStationUrl(lat, lng);
@@ -68,7 +69,7 @@ export class NWSProvider implements IWeatherProvider {
       for (const key of WEATHER_KEYS) {
         const value = weatherData.find((data) => data[key]);
 
-        if (value && value[key]?.value) {
+        if (value && typeof value[key]?.value !== 'undefined') {
           data[key] = value[key] as never;
         }
       }
@@ -77,7 +78,7 @@ export class NWSProvider implements IWeatherProvider {
         throw new Error('Invalid observation data');
       }
 
-      return data as IWeatherData;
+      return data;
     } catch (error) {
       log('Error in getWeather:', error);
       throw error;
@@ -150,23 +151,23 @@ async function fetchLatestObservation(
   }
 }
 
-function convertToWeatherData(observation: any): IWeatherProviderWeatherData {
+function convertToWeatherData(observation: IObservationsLatest): Partial<IWeatherProviderWeatherData> {
   const properties = observation.properties;
-  
+
   return {
     dewPoint: {
-      value: properties.dewpoint.value,
+      value: properties.dewpoint.value!,
       unit:
         properties.dewpoint.unitCode === 'wmoUnit:degC'
           ? IWeatherUnits.C
           : IWeatherUnits.F,
     },
     humidity: {
-      value: properties.relativeHumidity.value,
+      value: properties.relativeHumidity.value!,
       unit: IWeatherUnits.percent,
     },
     temperature: {
-      value: properties.temperature.value,
+      value: properties.temperature.value!,
       unit:
         properties.temperature.unitCode === 'wmoUnit:degC'
           ? IWeatherUnits.C
@@ -177,5 +178,9 @@ function convertToWeatherData(observation: any): IWeatherProviderWeatherData {
       unit: IWeatherUnits.string,
       original: properties.textDescription
     },
+    cloudiness: {
+      value: getCloudinessFromCloudLayers(properties.cloudLayers),
+      unit: IWeatherUnits.percent,
+    },
   };
 }

src/providers/nws/cloudiness.test.ts

@@ -0,0 +1,71 @@
+import { getCloudinessFromCloudLayers } from './cloudiness';
+import { ICloudLayer } from './interfaces';
+
+describe('getCloudinessFromCloudLayers', () => {
+  it('should return 0 for null or empty cloud layers', () => {
+    expect(getCloudinessFromCloudLayers(null as any)).toBe(0);
+    expect(getCloudinessFromCloudLayers([])).toBe(0);
+  });
+
+  it('should correctly calculate cloudiness for a single cloud layer', () => {
+    const testCases: Array<{ cloudLayer: ICloudLayer, expected: number }> = [
+      { 
+        cloudLayer: { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'CLR' }, 
+        expected: 0 
+      },
+      { 
+        cloudLayer: { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'SKC' }, 
+        expected: 0 
+      },
+      { 
+        cloudLayer: { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'FEW' }, 
+        expected: 20 
+      },
+      { 
+        cloudLayer: { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'SCT' }, 
+        expected: 40 
+      },
+      { 
+        cloudLayer: { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'BKN' }, 
+        expected: 75 
+      },
+      { 
+        cloudLayer: { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'OVC' }, 
+        expected: 100 
+      },
+      { 
+        cloudLayer: { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'VV' }, 
+        expected: 100 
+      },
+      { 
+        cloudLayer: { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'UNKNOWN' }, 
+        expected: 0 
+      }
+    ];
+
+    testCases.forEach(({ cloudLayer, expected }) => {
+      expect(getCloudinessFromCloudLayers([cloudLayer])).toBe(expected);
+    });
+  });
+
+  it('should correctly calculate the average cloudiness for multiple cloud layers', () => {
+    const cloudLayers: Array<ICloudLayer> = [
+      { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'FEW' },  // 20%
+      { base: { unitCode: 'wmoUnit:m', value: 2000 }, amount: 'SCT' },  // 40%
+      { base: { unitCode: 'wmoUnit:m', value: 3000 }, amount: 'BKN' }   // 75%
+    ];
+
+    // Average of 20%, 40%, and 75% = 45%
+    expect(getCloudinessFromCloudLayers(cloudLayers)).toBe(45);
+  });
+
+  it('should round the average cloudiness to the nearest integer', () => {
+    const cloudLayers: Array<ICloudLayer> = [
+      { base: { unitCode: 'wmoUnit:m', value: 1000 }, amount: 'FEW' },  // 20%
+      { base: { unitCode: 'wmoUnit:m', value: 2000 }, amount: 'BKN' }   // 75%
+    ];
+
+    // Average of 20% and 75% = 47.5%, which should round to 48%
+    expect(getCloudinessFromCloudLayers(cloudLayers)).toBe(48);
+  });
+});