@angelrove/forecast-utils 1.1.1

package/src/geolocation/lib/reversegeocoding.js

@@ -0,0 +1,109 @@
+/**
+ * Reverse Geocoding with GoogleMaps API
+ *
+ * @see https://developers.google.com/maps/documentation/geocoding/requests-reverse-geocoding?hl=es-419
+ * @see https://maps.googleapis.com/maps/api/geocode/json?latlng=36.7248,-4.541&key=[api_key]&result_type=sublocality
+ *
+ * @param {number} latitude - Latitude of the location.
+ * @param {number} longitude - Longitude of the location.
+ * @param {string} api_key - Google Maps API key.
+ * @returns {Promise<{ sublocality: string; locality: string; country: string; country_short: string; formatted_address: string; }>} - The address components.
+ * @throws {Error} - If the API key is invalid or the request fails.
+ */
+export default async function reverseGeocoding(latitude, longitude, api_key) {
+  // Validate --
+  if (!api_key) {
+    console.error("ReverseGeocoding: invalid api key");
+    throw new Error("ReverseGeocoding: invalid api key");
+  }
+  if (!latitude || !longitude) {
+    console.error("ReverseGeocoding: invalid coordinates");
+    throw new Error("ReverseGeocoding: invalid coordinates");
+  }
+
+  // API URL --
+  const host =
+    "https://maps.googleapis.com/maps/api/geocode/json?key=" +
+    api_key +
+    "&latlng=" +
+    latitude +
+    "," +
+    longitude;
+
+  /*
+   * 'result_type' param:
+   *    street_address,
+   *    colloquial_area,
+   *    locality,
+   *    sublocality,
+   *    administrative_area_level_1,
+   *    administrative_area_level_2
+   */
+  const urlApi = host + "&result_type=sublocality";
+
+  // Fetch data --
+  const response = await fetch(urlApi);
+  devLog("Geocoding", urlApi);
+
+  // Check response --
+  if (!response.ok) {
+    const message =
+      "Failed to Reverse Geocoding: " +
+      response.status +
+      " " +
+      response.statusText;
+    console.error(message);
+    throw new Error(message);
+  }
+  const data = await response.json();
+
+  // No results --
+  if (data.status === "ZERO_RESULTS") {
+    // plus_code: { compound_code: 'G4F9+72P Marbella, Spain', }
+    const country = data.plus_code.compound_code.split(",")[1];
+    const address = data.plus_code.compound_code.split(" ").slice(1).join(" ");
+    // throw new Error('Failed to Reverse Geocoding');
+
+    return {
+      sublocality: "",
+      locality: "",
+      country: country,
+      country_short: country,
+      formatted_address: address,
+    };
+  }
+
+  if (data.status !== "OK") {
+    let message = "Failed to Reverse Geocoding: " + data.status;
+    if (data.error_message) {
+      message += " " + data.error_message;
+    }
+    console.error(message);
+    throw new Error(message);
+  }
+
+  // Formatted address --
+  let formatted_address = data.results[0].formatted_address.split(",");
+  formatted_address.pop();
+  formatted_address = formatted_address.join(",");
+
+  // Return --
+  return {
+    sublocality: data.results[0].address_components[0].long_name,
+    locality: data.results[0].address_components[1].long_name,
+    country: data.results[0].address_components[4].long_name,
+    country_short: data.results[0].address_components[4].short_name,
+    formatted_address: formatted_address,
+  };
+}
+
+/**
+ * @param {string} title
+ * @param {any} url
+ */
+function devLog(title, url) {
+  // @ts-ignore
+  if (import.meta.env.MODE === "development") {
+    console.log(`> fetch [${title}]:`, url);
+  }
+}

package/src/index.js

@@ -0,0 +1,38 @@
+/**
+ * @author: Jose Angel Romero Vegas
+ * @license: MIT
+ * @description:
+ * Several utility libraries for the Tierracolora project:
+ * - Forecast API (OpenWeather)
+ * - Astronomy utilities
+ *
+ * I use public libraries for the following:
+ * - Astronomy calculations: suncalc3
+ */
+
+// Astronomy
+export { default as MoonCalc } from "./astronomy/moon/MoonCalc.js";
+export { default as SunCalc } from "./astronomy/sun/SunCalc.js";
+export {
+  dateFormat,
+  getLocalTimeFromTz,
+  nowString,
+  timeString,
+} from "./astronomy/timehelpers.js";
+export { getLocalTimeInfo as getLocalTime } from "./astronomy/timeZoneInfo.js";
+
+// Geolocation
+export { getGeolocation } from "./geolocation/getGeolocation.js";
+
+// OpenMeteo
+export { useForecastCurrent } from "./OpenMeteo/current/useForecastCurrent.js";
+export { useForecastDaily } from "./OpenMeteo/daily/useForecastDaily.js";
+export { useForecastHourly } from "./OpenMeteo/hourly/useForecastHourly.js";
+export { weatherSymbol } from "./OpenMeteo/weatherSymbol/weatherSymbol.js";
+
+// utils
+export { degreesToCompass } from "./utils/degreesToCompass.js";
+export { getWarning, getWarningByDays } from "./utils/warning.js";
+export { WindArrow } from "./utils/wind/WindArrow.jsx";
+export { windArrowTx } from "./utils/wind/windArrowTx.js";
+export { getWindLevel } from "./utils/wind/windLevel.js";

package/src/utils/degreesToCompass.js

@@ -0,0 +1,51 @@
+/**
+ * @module utils
+ */
+
+const directions = [
+  { short: "N", full: "North" },
+  { short: "NE", full: "Northeast" },
+  { short: "E", full: "East" },
+  { short: "SE", full: "Southeast" },
+  { short: "S", full: "South" },
+  { short: "SW", full: "Southwest" },
+  { short: "W", full: "West" },
+  { short: "NW", full: "Northwest" },
+];
+
+const directionsEs = [
+  { short: "N", full: "Norte" },
+  { short: "NE", full: "Noreste" },
+  { short: "E", full: "Este" },
+  { short: "SE", full: "Sureste" },
+  { short: "S", full: "Sur" },
+  { short: "SO", full: "Suroeste" },
+  { short: "O", full: "Oeste" },
+  { short: "NO", full: "Noroeste" },
+];
+
+/**
+ * Convert degrees to compass designation
+ *
+ * @param {number} degrees
+ * @param {string} language - Language code ("en-US", "es-ES", "auto")
+ * @returns {{short: string, full: string}}
+ */
+export function degreesToCompass(degrees, language = "auto") {
+  if (degrees == null) return { short: "?", full: "?" };
+
+  const index = Math.round(degrees / 45) % 8;
+
+  // auto detect language
+  let lang = language;
+  if (language === "auto") {
+    lang = navigator.language;
+  }
+
+  // Parse the language
+  if (lang.startsWith("es")) {
+    return directionsEs[index];
+  }
+
+  return directions[index];
+}

package/src/utils/warning.js

@@ -0,0 +1,130 @@
+/**
+ * @module utils
+ */
+
+// AEMET (12 horas)
+
+/**
+ * @typedef {Object} AlertLevel
+ * @property {number} levelNum - The alert level number.
+ * @property {string} level - The alert level string (e.g., "red", "orange", "yellow").
+ * @property {number} precipitation - The precipitation threshold for the alert level.
+ * @property {number} showers - The showers threshold for the alert level.
+ */
+
+/**
+ * Alert levels for rain and showers
+ *
+ * @type {AlertLevel[]}
+ */
+const ALERT_LEVEL = [
+  { levelNum: 3, level: "red", precipitation: 120, showers: 60 },
+  { levelNum: 2, level: "orange", precipitation: 80, showers: 30 },
+  { levelNum: 1, level: "yellow", precipitation: 50, showers: 18 },
+];
+
+/**
+ * Get warning by today and tomorrow
+ *
+ * @param {number} precipitationSumToday
+ * @param {number} precipitationSumTomorrow
+ * @param {number} showersSumToday
+ * @param {number} showersSumTomorrow
+ * @returns {{ levelNum: number, level: string, message: string, day: number } | null}
+ */
+export function getWarningByDays(
+  precipitationSumToday,
+  precipitationSumTomorrow,
+  showersSumToday,
+  showersSumTomorrow,
+) {
+  // Today
+  const wToday = getWarning(precipitationSumToday, showersSumToday);
+  if (wToday) {
+    return {
+      ...wToday,
+      day: 0,
+    };
+  }
+
+  // Tomorrow
+  const wTomorrow = getWarning(precipitationSumTomorrow, showersSumTomorrow);
+  if (wTomorrow) {
+    return {
+      ...wTomorrow,
+      day: 1,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Get warning by precipitation and showers
+ *
+ * @export
+ * @param {number} precipitation
+ * @param {number} showers
+ * @returns {{ levelNum: number, level: string, message: string } | null}
+ */
+export function getWarning(precipitation, showers) {
+  const warningRain = getWarningRain(precipitation);
+  const warningShowers = getWarningShowers(showers);
+  // console.log(warningRain);
+  // console.log(warningShowers);
+
+  if (warningRain && warningShowers) {
+    return warningRain.levelNum > warningShowers.levelNum
+      ? warningRain
+      : warningShowers;
+  }
+  if (warningRain) {
+    return warningRain;
+  }
+  if (warningShowers) {
+    return warningShowers;
+  }
+
+  return null;
+}
+
+//----------------------------------------------------------------
+// PRIVATE FUNCTIONS
+//----------------------------------------------------------------
+/**
+ * Get warning by rain
+ *
+ * @param {number} precipitation
+ * @returns {{ levelNum: number, level: string, message: string } | null}
+ */
+function getWarningRain(precipitation) {
+  for (let i = 0; i < ALERT_LEVEL.length; i++) {
+    if (precipitation >= ALERT_LEVEL[i].precipitation) {
+      return {
+        levelNum: ALERT_LEVEL[i].levelNum,
+        level: ALERT_LEVEL[i].level,
+        message: "Por precipitacion acumulada en 24 horas.",
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Get warning by showers
+ *
+ * @param {number} showers
+ * @returns {{ levelNum: number, level: string, message: string } | null}
+ */
+function getWarningShowers(showers) {
+  for (let i = 0; i < ALERT_LEVEL.length; i++) {
+    if (showers >= ALERT_LEVEL[i].showers) {
+      return {
+        levelNum: ALERT_LEVEL[i].levelNum,
+        level: ALERT_LEVEL[i].level,
+        message: "Chubascos intensos.",
+      };
+    }
+  }
+  return null;
+}

package/src/utils/wind/WindArrow.jsx

@@ -0,0 +1,53 @@
+/**
+ * @module utils:WindArrow
+ */
+
+/**
+ * @typedef {Object} WindArrowProps
+ * @property {number} props.deg - Wind direction in degrees
+ * @property {string} [props.size] - Size of the arrow (Tailwind CSS size: 'size-10')
+ * @property {number} [props.strokeWidth] - Stroke width of the arrow (1 to 6)
+ * @property {string} [props.className]
+ */
+
+/**
+ * Wind direction arrow component (svg image).
+ *
+ * @component
+ * @param {WindArrowProps} props
+ */
+export function WindArrow({
+  deg,
+  size = "size-5",
+  strokeWidth = 1.9,
+  className = "",
+}) {
+  if (deg == null) {
+    // console.warn("WindArrow: deg is undefined");
+    /* @ts-ignore */
+    return <div>deg?</div>;
+  }
+
+  // Render arrow ---
+  return (
+    /* @ts-ignore */
+    <svg
+      className={`${size} ${className}`}
+      style={{ transform: `rotate(${deg}deg)` }}
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={strokeWidth}
+      viewBox="0 0 24 24"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
+    >
+      {/* @ts-ignore */}
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        d="M19.5 13.5L12 21m0 0l-7.5-7.5M12 21V3"
+      />
+      {/* @ts-ignore */}
+    </svg>
+  );
+}

package/src/utils/wind/windArrowTx.js

@@ -0,0 +1,24 @@
+/**
+ * @module utils
+ */
+
+/**
+ * Convert wind direction in degrees to an arrow representation.
+ *
+ * @param {number} deg - Wind direction in degrees.
+ */
+export function windArrowTx(deg) {
+  if (deg == null) {
+    console.warn("WindDegToArrow.jsx: deg is undefined");
+    return "deg?";
+  }
+
+  if (deg < 22.5) return "↓";
+  if (deg < 67.5) return "↙";
+  if (deg < 112.5) return "←";
+  if (deg < 157.5) return "↖";
+  if (deg < 202.5) return "↑";
+  if (deg < 247.5) return "↗";
+  if (deg < 292.5) return "→";
+  if (deg < 337.5) return "↘";
+}

package/src/utils/wind/windLevel.js

@@ -0,0 +1,49 @@
+/**
+ * @module utils
+ */
+
+/**
+ * @typedef {Object} WindLevel
+ * @property {number} id - Level ID
+ * @property {number} speed - Minimum wind speed for this level
+ * @property {string} color - Color representing this level
+ * @property {string} tx - Text representing this level
+ * @property {string} txEn - Text representing this level
+ */
+
+/**
+ * Ordered list of wind levels.
+ *
+ * @type {WindLevel[]}
+ */
+const WIND_LEVELS = [
+  { id: 1, speed: 8, color: "green", tx: "Brisa", txEn: "Breeze" },
+  { id: 2, speed: 16, color: "orange", tx: "Ligero", txEn: "Light" },
+  { id: 3, speed: 23, color: "red", tx: "Moderado", txEn: "Moderate" },
+  { id: 4, speed: 30, color: "red", tx: "Fuerte", txEn: "Strong" },
+  { id: 5, speed: 50, color: "fuchsia", tx: "Muy fuerte", txEn: "Very strong" },
+  {
+    id: 6,
+    speed: Number.POSITIVE_INFINITY,
+    color: "fuchsia",
+    tx: "Peligroso",
+    txEn: "Dangerous",
+  },
+];
+
+/**
+ * Return the wind level based on the speed.
+ *
+ * @param {number} speed Wind speed in km/h
+ * @return {WindLevel | null} Wind level object or null if speed is null
+ */
+export function getWindLevel(speed) {
+  if (typeof speed !== "number") return null;
+
+  const theSpeed = Math.round(speed);
+
+  for (const level of WIND_LEVELS) {
+    if (theSpeed < level.speed) return level;
+  }
+  return WIND_LEVELS[WIND_LEVELS.length - 1]; // fallback defensivo
+}