@angelrove/forecast-utils 1.1.1

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@angelrove/forecast-utils",
+  "version": "1.1.1",
+  "author": "Jose Angel Romero Vegas",
+  "license": "MIT",
+  "description": "Utilidades para obtener datos de previsión meteorológica (Open-Meteo API) y de astronomía (SunCalc API).",
+  "homepage": "https://github.com/angelrove/OpenMeteoForecast",
+  "type": "module",
+  "scripts": {
+    "docs:md": "bunx jsdoc2md $(cat doc-files.txt) > README.md"
+  },
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.js"
+    }
+  },
+  "files": ["src", "dist"],
+  "keywords": [
+    "forecast",
+    "weather",
+    "open-meteo",
+    "astronomy",
+    "react",
+    "hooks",
+    "JavaScript"
+  ],
+  "peerDependencies": {
+    "react": "^19.1.0",
+    "suncalc3": "^2.0.5",
+    "swr": "^2.3.3",
+    "@capacitor/geolocation": "^7.1.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "jsdoc-to-markdown": "^9.1.1"
+  },
+  "dependencies": {}
+}

package/src/OpenMeteo/conf.js

@@ -0,0 +1,47 @@
+const ApiInfo = {
+  host: "https://api.open-meteo.com/v1",
+  pathMain: "/forecast?timezone=auto&",
+};
+
+/**
+ * @param {string} url
+ */
+export async function fetcher(url) {
+  devLog("OpemMeteo", url);
+  return fetch(url).then((res) => res.json());
+}
+
+/**
+ * Get path for OpenMeteo API
+ *
+ * @param {number} lat
+ * @param {number} lon
+ * @param {string} path
+ * @returns {string}
+ */
+export function getPath(lat, lon, path) {
+  return (
+    ApiInfo.host +
+    ApiInfo.pathMain +
+    "latitude=" +
+    lat +
+    "&longitude=" +
+    lon +
+    "&" +
+    path
+  );
+}
+
+/**
+ * Console log for development
+ *
+ * @param {string} title
+ * @param {string} url
+ */
+function devLog(title, url) {
+  // @ts-ignore
+  if (import.meta.env.MODE === "development") {
+    // console.log('%c> fetch [' + title + ']:', 'color:#9e9', url);
+    console.log("> fetch [" + title + "]:", url);
+  }
+}

package/src/OpenMeteo/current/fetchParams.js

@@ -0,0 +1,21 @@
+// hourlyParams
+
+import { fetchParams as hourlyParams } from "../hourly/fetchParams.js";
+
+export const fetchParams =
+  "current=" +
+  "temperature_2m," +
+  "apparent_temperature," +
+  "relative_humidity_2m," +
+  "weather_code," +
+  "wind_speed_10m," +
+  "wind_direction_10m," +
+  "precipitation&" +
+  "&forecast_days=2" +
+  "&daily=" +
+  "temperature_2m_max," +
+  "temperature_2m_min," +
+  "precipitation_sum," +
+  "showers_sum" +
+  "&" +
+  hourlyParams;

package/src/OpenMeteo/current/transformer.js

@@ -0,0 +1,37 @@
+/**
+ * Transforms the OpenMeteo API data into a more usable format.
+ *
+ * @param {{current: any, daily: any, hourly: any, latitude: number, longitude: number}} data - The data object to transform.
+ * @returns {Object|null} - The transformed data object or null if the input is invalid.
+ */
+export default function transformer(data) {
+  if (!data) return null;
+
+  const current = data.current;
+  const daily = data.daily;
+
+  return {
+    city: null,
+    country: null,
+    time: new Date().toTimeString(),
+    latitude: data.latitude,
+    longitude: data.longitude,
+    weather: {
+      weathercode: current.weather_code,
+      precipitation: current.precipitation,
+      temperature: current.temperature_2m,
+      feels_like: current.apparent_temperature,
+      humidity: current.relative_humidity_2m,
+      wind: {
+        speed: Math.round(current.wind_speed_10m),
+        deg: current.wind_direction_10m,
+        // gust: ,
+      },
+      tem_max: daily.temperature_2m_max[0],
+      tem_min: daily.temperature_2m_min[0],
+      precipitation_sum: daily.precipitation_sum,
+      showers_sum: daily.showers_sum,
+      hourly: data.hourly,
+    },
+  };
+}

package/src/OpenMeteo/current/useForecastCurrent.js

@@ -0,0 +1,34 @@
+/**
+ * @module OpenMeteo:current
+ */
+
+import useSWR from "swr";
+import { fetcher, getPath } from "../conf.js";
+import { fetchParams } from "./fetchParams.js";
+import transformer from "./transformer.js";
+
+/**
+ * Custom hook to fetch current weather data from OpenMeteo API.
+ *
+ * @param {number} lat
+ * @param {number} lon
+ * @param {number} refreshIntervalMin
+ * @returns {{ data: any, apiUrl: string, isLoading: boolean, isError: any }}
+ */
+export function useForecastCurrent(lat, lon, refreshIntervalMin = 0) {
+  if (!lat || !lon) {
+    throw new Error("useForecastCurrent: invalid coordinates");
+  }
+
+  const apiUrl = getPath(lat, lon, fetchParams);
+  const { data, error, isLoading } = useSWR(apiUrl, fetcher, {
+    refreshInterval: refreshIntervalMin * 60 * 1000,
+  });
+
+  return {
+    data: data ? transformer(data) : null,
+    apiUrl: apiUrl,
+    isLoading,
+    isError: error,
+  };
+}

package/src/OpenMeteo/daily/fetchParams.js

@@ -0,0 +1,9 @@
+export const fetchParams =
+  "forecast_days=10&" +
+  "daily=" +
+  "weather_code," +
+  "temperature_2m_max," +
+  "temperature_2m_min," +
+  "precipitation_sum," +
+  "windspeed_10m_max," +
+  "winddirection_10m_dominant";

package/src/OpenMeteo/daily/transformer.js

@@ -0,0 +1,21 @@
+/**
+ * Transforms the OpenMeteo API data into a more usable format.
+ *
+ * @param {{daily: any}} data - The data object to transform.
+ * @returns {Object|null} - The transformed data object or null if the input is invalid.
+ */
+export default function transformer(data) {
+  if (!data) return null;
+
+  const newData = {
+    time: data.daily.time,
+    weathercode: data.daily.weather_code,
+    tempMax: data.daily.temperature_2m_max,
+    tempMin: data.daily.temperature_2m_min,
+    windDirection: data.daily.winddirection_10m_dominant,
+    windSpeed: data.daily.windspeed_10m_max,
+    precipitation_sum: data.daily.precipitation_sum,
+  };
+
+  return newData;
+}

package/src/OpenMeteo/daily/useForecastDaily.js

@@ -0,0 +1,38 @@
+/**
+ * @module OpenMeteo:daily
+ */
+
+import useSWR from "swr";
+import { fetcher, getPath } from "../conf.js";
+import { fetchParams } from "./fetchParams.js";
+import transformer from "./transformer.js";
+
+/**
+ * Custom hook to fetch daily forecast (10 days) data from OpenMeteo API.
+ * https://api.open-meteo.com/v1/forecast?timezone=auto&latitude=36.6644363&longitude=-4.5108962&forecast_days=10&daily=weathercode
+ *
+ * @param {number} lat
+ * @param {number} lon
+ * @param {number} refreshIntervalMin
+ * @returns {{ data: any, isLoading: boolean, isError: any }}
+ */
+export function useForecastDaily(lat, lon, refreshIntervalMin = 0) {
+  // Validate --
+  if (!lat || !lon) {
+    throw new Error("useForecastDaily: invalid coordinates");
+  }
+
+  // Fetch --
+  const apiUrl = getPath(lat, lon, fetchParams);
+  // console.log(apiUrl);
+  const { data, error, isLoading } = useSWR(apiUrl, fetcher, {
+    refreshInterval: refreshIntervalMin * 60 * 1000,
+  });
+
+  // Return --
+  return {
+    data: data ? transformer(data) : null,
+    isLoading,
+    isError: error,
+  };
+}

package/src/OpenMeteo/helpers.js

@@ -0,0 +1,19 @@
+/**
+ * Get the start and end dates based on the number of days from today.
+ *
+ * @param {number} numDay
+ * @returns {{startDate: string, endDate: string}} - An object containing the start and end dates in YYYY-MM-DD format.
+ */
+export function getDatesFromNumDays(numDay) {
+  // Dates: Today / End ---
+  const startDate = new Date();
+  startDate.setDate(startDate.getDate() + numDay);
+
+  const endDate = new Date();
+  endDate.setDate(endDate.getDate() + numDay + 1);
+
+  return {
+    startDate: startDate.toISOString().split("T")[0],
+    endDate: endDate.toISOString().split("T")[0],
+  };
+}

package/src/OpenMeteo/hourly/fetchParams.js

@@ -0,0 +1,12 @@
+export const fetchParams =
+  "hourly=" +
+  "weathercode," +
+  "temperature_2m," +
+  "windspeed_10m," +
+  "winddirection_10m," +
+  "relativehumidity_2m," +
+  "apparent_temperature," +
+  "precipitation," +
+  "freezing_level_height," +
+  "is_day";
+// 'cloudcover,' +

package/src/OpenMeteo/hourly/useForecastHourly.js

@@ -0,0 +1,42 @@
+/**
+ * @module OpenMeteo:hourly
+ */
+
+import useSWR from "swr";
+import { fetcher, getPath } from "../conf.js";
+import { getDatesFromNumDays } from "../helpers.js";
+import { fetchParams } from "./fetchParams.js";
+
+/**
+ * Custom hook to fetch hourly forecast data for a given location and number of days from OpenMeteo API.
+ *
+ * @param {{ latitude: number, longitude: number }} location
+ * @param {number} dayNum - Number of days from today: -1 = 24 hours, 0 = today, 1 = tomorrow, ...
+ * @returns {{ data: any, isLoading: boolean, isError: any }}
+ */
+export function useForecastHourly(location, dayNum) {
+  if (!location.latitude || !location.longitude) {
+    throw new Error("useForecastHourly: invalid coordinates");
+  }
+
+  // Fetch ---
+  const dates = getDatesFromNumDays(dayNum);
+
+  let apiUrl =
+    "start_date=" +
+    dates.startDate +
+    "&" +
+    "end_date=" +
+    dates.endDate +
+    "&" +
+    fetchParams;
+  apiUrl = getPath(location.latitude, location.longitude, apiUrl);
+
+  const { data, error, isLoading } = useSWR(apiUrl, fetcher);
+
+  return {
+    data: data,
+    isLoading,
+    isError: error,
+  };
+}

package/src/OpenMeteo/weatherSymbol/lib/WeatherCodesEn.js

@@ -0,0 +1,89 @@
+/**
+ * WMO Weather interpretation codes (WW)
+ *
+ * @link https://open-meteo.com/en/docs?hourly=temperature_2m,weather_code&daily=weather_code#weather_variable_documentation
+ * @link https://www.meteomatics.com/en/api/available-parameters/derived-weather-and-convenience-parameters/general-weather-state/
+ *
+ * Code	      Description
+ * 0          Clear sky
+ * 1, 2, 3    Mainly clear, partly cloudy, and overcast
+ * 45, 48	    Fog and depositing rime fog
+ * 51, 53, 55	Drizzle: Light, moderate, and dense intensity
+ * 56, 57	    Freezing Drizzle: Light and dense intensity
+ * 61, 63, 65	Rain: Slight, moderate and heavy intensity
+ * 66, 67	    Freezing Rain: Light and heavy intensity
+ * 71, 73, 75	Snow fall: Slight, moderate, and heavy intensity
+ * 77	        Snow grains
+ * 80, 81, 82	Rain showers: Slight, moderate, and violent
+ * 85, 86	    Snow showers slight and heavy
+ * 95 *	      Thunderstorm: Slight or moderate
+ * 96, 99 *	  Thunderstorm with slight and heavy hail
+ */
+
+/**
+ * @typedef {Object} WeatherCodeEntry
+ * @property {number} code - WMO Weather interpretation codes (WW).
+ * @property {string} icon - Icon name.
+ * @property {string} description - Description.
+ */
+
+/** @type {WeatherCodeEntry[]} */
+export const weatherCodes = [
+  { code: 0, icon: "0", description: "Clear sky" },
+  { code: 1, icon: "0", description: "Mainly clear" },
+
+  { code: 2, icon: "2", description: "Partly cloudy" },
+  { code: 3, icon: "3", description: "Overcast" },
+
+  // Niebla
+  { code: 45, icon: "45", description: "Fog" },
+  { code: 48, icon: "48", description: "Fog and depositing rime fog" },
+
+  // Llovizna
+  { code: 51, icon: "51", description: "Drizzle: Light" },
+  { code: 53, icon: "51", description: "Drizzle: moderate" },
+  { code: 55, icon: "51", description: "Drizzle: dense intensity" },
+
+  // Llovizna congelante
+  { code: 56, icon: "51", description: "Freezing Drizzle: Light" },
+  { code: 57, icon: "51", description: "Freezing Drizzle: dense intensity" },
+
+  // Lluvia
+  { code: 61, icon: "51", description: "Rain: Slight" },
+  { code: 63, icon: "63", description: "Rain: moderate and heavy intensity" },
+  { code: 65, icon: "65", description: "Rain: heavy intensity" },
+
+  // Lluvia helada
+  { code: 66, icon: "63", description: "Freezing Rain: Light" },
+  { code: 67, icon: "65", description: "Freezing Rain: Heavy intensity" },
+
+  // Chubascos de lluvia
+  { code: 80, icon: "80", description: "Snow fall: slight" },
+  { code: 81, icon: "81", description: "Snow fall: moderate" },
+  { code: 82, icon: "82", description: "Snow fall: heavy intensity" },
+
+  // Tormenta
+  { code: 95, icon: "95", description: "Snow grains" },
+  { code: 96, icon: "95", description: "Rain showers: slight" },
+  { code: 99, icon: "99", description: "Rain showers: moderate" },
+
+  // Nieve
+  { code: 71, icon: "71", description: "Rain showers: violent" },
+  { code: 73, icon: "71", description: "Snow showers slight" },
+  { code: 75, icon: "75", description: "Snow showers heavy" },
+
+  // Chubascos de nieve
+  { code: 85, icon: "85", description: "Thunderstorm: Slight or moderate" },
+  {
+    code: 86,
+    icon: "86",
+    description: "Thunderstorm with slight and heavy hail",
+  },
+
+  // Granizo
+  {
+    code: 77,
+    icon: "77",
+    description: "Thunderstorm with slight and heavy hail",
+  },
+];

package/src/OpenMeteo/weatherSymbol/lib/WeatherCodesEs.js

@@ -0,0 +1,81 @@
+/**
+ * WMO Weather interpretation codes (WW)
+ *
+ * @link https://open-meteo.com/en/docs?hourly=temperature_2m,weather_code&daily=weather_code#weather_variable_documentation
+ * @link https://www.meteomatics.com/en/api/available-parameters/derived-weather-and-convenience-parameters/general-weather-state/
+ *
+ * Code	      Description
+ * 0          Clear sky
+ * 1, 2, 3    Mainly clear, partly cloudy, and overcast
+ * 45, 48	    Fog and depositing rime fog
+ * 51, 53, 55	Drizzle: Light, moderate, and dense intensity
+ * 56, 57	    Freezing Drizzle: Light and dense intensity
+ * 61, 63, 65	Rain: Slight, moderate and heavy intensity
+ * 66, 67	    Freezing Rain: Light and heavy intensity
+ * 71, 73, 75	Snow fall: Slight, moderate, and heavy intensity
+ * 77	        Snow grains
+ * 80, 81, 82	Rain showers: Slight, moderate, and violent
+ * 85, 86	    Snow showers slight and heavy
+ * 95 *	      Thunderstorm: Slight or moderate
+ * 96, 99 *	  Thunderstorm with slight and heavy hail
+ */
+
+/**
+ * @typedef {Object} WeatherCodeEntry
+ * @property {number} code - WMO Weather interpretation codes (WW).
+ * @property {string} icon - Icon name.
+ * @property {string} description - Description.
+ */
+
+/** @type {WeatherCodeEntry[]} */
+export const weatherCodes = [
+  { code: 0, icon: "0", description: "Cielo despejado" },
+  { code: 1, icon: "0", description: "Principalmente despejado" },
+
+  { code: 2, icon: "2", description: "Parcialmente nublado" },
+  { code: 3, icon: "3", description: "Cubierto" },
+
+  // Niebla
+  { code: 45, icon: "45", description: "Niebla" },
+  { code: 48, icon: "48", description: "Niebla ligera con escarcha" },
+
+  // Llovizna
+  { code: 51, icon: "51", description: "Llovizna débil" },
+  { code: 53, icon: "51", description: "Llovizna moderada" },
+  { code: 55, icon: "51", description: "Llovizna densa" },
+
+  // Llovizna congelante
+  { code: 56, icon: "51", description: "Llovizna débil, congelándose" },
+  { code: 57, icon: "51", description: "Llovizna densa, congelándose" },
+
+  // Lluvia
+  { code: 61, icon: "51", description: "Lluvia ligera" },
+  { code: 63, icon: "63", description: "Lluvia moderada o fuerte" },
+  { code: 65, icon: "65", description: "Lluvia fuerte" },
+
+  // Lluvia helada
+  { code: 66, icon: "63", description: "Lluvia helada ligera" },
+  { code: 67, icon: "65", description: "Lluvia moderada o fuerte" },
+
+  // Chubascos de lluvia
+  { code: 80, icon: "80", description: "Chubascos débiles" },
+  { code: 81, icon: "81", description: "Chubascos moderados" },
+  { code: 82, icon: "82", description: "Chubascos fuertes" },
+
+  // Tormenta
+  { code: 95, icon: "95", description: "Tormenta" },
+  { code: 96, icon: "95", description: "Tormenta con algo de granizo" },
+  { code: 99, icon: "99", description: "Tormenta fuerte, con granizo" },
+
+  // Nieve
+  { code: 71, icon: "71", description: "Nieve ligera" },
+  { code: 73, icon: "71", description: "Nevada moderada" },
+  { code: 75, icon: "75", description: "Fuertes nevadas" },
+
+  // Chubascos de nieve
+  { code: 85, icon: "85", description: "Chubascos de nieve débil" },
+  { code: 86, icon: "86", description: "Chubascos de nieve fuertes" },
+
+  // Granizo
+  { code: 77, icon: "77", description: "Granizo" },
+];

package/src/OpenMeteo/weatherSymbol/lib/getWeatherCodeEntry.js

@@ -0,0 +1,12 @@
+// @ts-nocheck
+import { weatherCodes } from "./WeatherCodesEs.js";
+
+/**
+ * Returns weather code info o undefined if not found.
+ *
+ * @param {number} code - WMO Weather interpretation code.
+ * @returns {WeatherCodeEntry | undefined}
+ */
+export function getWeatherCodeEntry(code) {
+  return weatherCodes.find((entry) => entry.code === code);
+}

package/src/OpenMeteo/weatherSymbol/weatherSymbol.js

@@ -0,0 +1,60 @@
+/**
+ * @module OpenMeteo:weatherSymbol
+ */
+
+import { getWeatherCodeEntry } from "./lib/getWeatherCodeEntry.js";
+
+/**
+ * Get weather symbol and description based on the weather code.
+ *
+ * @param {any} code
+ * @param {number} [precipitation]
+ * @param {boolean} night
+ * @param {boolean} dark
+ * @returns {{ icon: string, description: string }}
+ */
+export function weatherSymbol(
+  code,
+  precipitation = undefined,
+  night = false,
+  dark = false,
+) {
+  // Parse code ---
+  let msgPlus = "";
+  let theCode = code;
+  if (precipitation && precipitation > 0.8) {
+    if (theCode === 63) theCode = 65;
+    if (theCode === 95) msgPlus = " y lluvia fuerte";
+  }
+
+  // Get weather entry ---
+  const weatherCodeEntry = getWeatherCodeEntry(theCode);
+  if (!weatherCodeEntry) {
+    return {
+      icon: "ws/icon_error.webp",
+      description: "???",
+    };
+  }
+
+  // Icon file ---
+  const iconKey = weatherCodeEntry.icon;
+  let iconFile = "icon_" + iconKey;
+
+  // Night
+  const nightIcons = ["0", "2", "48", "80", "85"];
+  if (night && nightIcons.includes(iconKey)) {
+    iconFile = iconFile + "_night";
+  }
+
+  // Light / Dark
+  if (dark) {
+    iconFile = "dark/" + iconFile;
+  }
+
+  // Return ---
+  const ext = ".webp";
+  return {
+    icon: "ws/" + iconFile + ext,
+    description: weatherCodeEntry.description + msgPlus,
+  };
+}