@angelrove/forecast-utils 1.1.1

package/src/astronomy/moon/MoonCalc.js

@@ -0,0 +1,171 @@
+// @ts-nocheck
+/**
+ * @module MoonCalc
+ * @description
+ * MoonCalc for calculating moon times, positions, and phases.
+ * - import { MoonCalc } from '@angelrov/forecast';
+ */
+
+// @ts-ignore
+import SunCalc from "suncalc3";
+import { dateFormat, getLocalTimeFromTz, timeString } from "../timehelpers.js";
+import { parseBasicData } from "./parseBasicData.js";
+
+/**
+ * IMPORTANTE!!:
+ * ¡Solo proporcionar HORA LOCAL DEL SISTEMA!: 'new Date()'
+ */
+
+/**
+ * Mapa de fases lunares.
+ *
+ * @type {Object.<string, string>}
+ */
+const phasesES = {
+  newMoon: "Luna Nueva",
+  waxingCrescentMoon: "Luna Creciente",
+  firstQuarterMoon: "Cuarto Creciente",
+  waxingGibbousMoon: "Gibosa creciente",
+  fullMoon: "Luna Llena",
+  waningGibbousMoon: "Gibosa menguante",
+  thirdQuarterMoon: "Cuarto Menguante",
+  waningCrescentMoon: "Luna Menguante",
+};
+
+const MoonCalc = {
+  data,
+  dataExt,
+  times,
+  emoji,
+  getUpOrDown,
+};
+export default MoonCalc;
+
+//--------------------------------------------------------------------
+/**
+ * @param {number} latitude
+ * @param {number} longitude
+ * @param {Date} [date=new Date()]
+ * @param {string} [language=es-ES]
+ * @returns {MoonData}
+ */
+function data(latitude, longitude, date = new Date(), language = "es-ES") {
+  // date.setHours(date.getHours() + 0); // debug
+  const data = SunCalc.getMoonData(date, latitude, longitude);
+  // console.log("%cdebug:", "color:yellow", data.illumination.next.newMoon.value);
+
+  return parseBasicData(data, language);
+}
+//--------------------------------------------------------------------
+/**
+ * Información de la luna para una fecha y hora dadas.
+ * La fecha y hora se devolverán en la zona horaria local.
+ *
+ * @param {number} latitude
+ * @param {number} longitude
+ * @param {Date} [date=new Date()]
+ * @param {string} [language=es-ES]
+ * @returns {{ date: string, time: string, illumination: string, phase: string, phaseId: string, emoji: string, parallacticAngle: number, angle: number, position: AstroPosition, next: object }}
+ */
+function dataExt(latitude, longitude, date = new Date(), language = "es-ES") {
+  const data = SunCalc.getMoonData(date, latitude, longitude);
+
+  // Illumination
+  const illumination =
+    Number((data.illumination.fraction * 100).toFixed(1)) + "%";
+
+  // Phase
+  const emoji = data.illumination.phase.emoji;
+  const phaseId = String(data.illumination.phase.id);
+  const phase = phasesES[phaseId];
+
+  // Angle
+  const parallacticAngle = data.parallacticAngleDegrees;
+  const angle =
+    phaseId === "fullMoon" || phaseId === "newMoon" ? 0 : parallacticAngle;
+
+  // Basic data
+  const basicData = parseBasicData(data, language);
+
+  // Return ---
+  return {
+    date: dateFormat(date),
+    time: timeString(date),
+    illumination: illumination,
+    phase: phase,
+    phaseId: phaseId,
+    emoji: emoji,
+    parallacticAngle: parallacticAngle,
+    angle: Math.round(angle),
+    position: basicData.position,
+    next: basicData.next,
+  };
+}
+//--------------------------------------------------------------------
+/**
+ * @param {number} latitude
+ * @param {number} longitude
+ * @param {Date} [date=new Date()]
+ * @returns {string} - Emoji of the moon phase
+ */
+function emoji(latitude, longitude, date = new Date()) {
+  const data = SunCalc.getMoonData(date, latitude, longitude);
+  return data.illumination.phase.emoji;
+}
+//--------------------------------------------------------------------
+/**
+ * @param {number} latitude
+ * @param {number} longitude
+ * @param {string} timezoneId
+ * @param {Date} date
+ * @returns {{rise: string, set: string, highest: string}}
+ */
+function times(latitude, longitude, timezoneId, date = new Date()) {
+  const ret = {
+    rise: "",
+    set: "",
+    highest: "",
+  };
+
+  const times = SunCalc.getMoonTimes(date, latitude, longitude);
+  if (times.alwaysUp) {
+    ret.rise = "always up";
+    ret.set = "always up";
+    ret.highest = "always up";
+    return ret;
+  }
+
+  if (times.alwaysDown) {
+    ret.rise = "always down";
+    ret.set = "always down";
+    ret.highest = "always down";
+    return ret;
+  }
+
+  ret.rise = getLocalTimeFromTz(timezoneId, times.rise);
+  ret.set = getLocalTimeFromTz(timezoneId, times.set);
+  ret.highest = getLocalTimeFromTz(timezoneId, times.highest);
+  return ret;
+}
+//--------------------------------------------------------------------
+/**
+ * @param {number} altitude
+ * @param {Date} highest
+ * @returns {string} - Up or down emoji
+ */
+function getUpOrDown(altitude, highest) {
+  const now = new Date();
+  let upOrDown = ""; // ◓ ◒
+
+  if (altitude > 0) {
+    if (highest.getHours() > now.getHours()) {
+      upOrDown = "🔺";
+    } else {
+      upOrDown = "🔻";
+    }
+  }
+  // console.log(highest.getHours(), now.getHours());
+
+  return upOrDown;
+}
+//--------------------------------------------------------------------

package/src/astronomy/moon/parseBasicData.js

@@ -0,0 +1,38 @@
+import { degreesToCompass } from "../../utils/degreesToCompass.js";
+import { dateFormat } from "../timehelpers.js";
+
+/**
+ * Parse basic data from SunCalc
+ *
+ * @param {any} data
+ * @param {string} language
+ * @returns {MoonData}
+ */
+export function parseBasicData(data, language) {
+  // Position ---
+  const altitude = Number(data.altitudeDegrees.toFixed(1));
+  const azimuth = Math.round(data.azimuthDegrees);
+  const direction = degreesToCompass(data.azimuthDegrees, language);
+
+  // Next moon ---
+  const nextNewMoon = dateFormat(
+    new Date(data.illumination.next.newMoon.value),
+  );
+  const nextFullMoon = dateFormat(
+    new Date(data.illumination.next.fullMoon.value),
+  );
+
+  return {
+    position: {
+      // up_down: null,
+      altitude: altitude,
+      azimuth: azimuth,
+      direction: direction.short,
+      direction_full: direction.full,
+    },
+    next: {
+      newMoon: nextNewMoon,
+      fullMoon: nextFullMoon,
+    },
+  };
+}

package/src/astronomy/sun/SunCalc.js

@@ -0,0 +1,167 @@
+/**
+ * @module SunCalc
+ * @description
+ * SunCalc for calculating solar times, positions, and phases.  
+ * - import { SunCalc } from '@angelrov/forecast';
+ */
+
+// @ts-ignore
+import { default as SunCalc3 } from "suncalc3";
+import { degreesToCompass } from "../../utils/degreesToCompass.js";
+import {
+  dateFormat,
+  getLocalTimeFromTz,
+  nowString,
+  timeString,
+} from "../timehelpers.js";
+
+/**
+ * IMPORTANTE!!:
+ * ¡Solo proporcionar HORA LOCAL DEL SISTEMA!: 'new Date()'
+ * La única excepción es 'getSolarTime()': hay que darle la hora local correspondiente a la localización dada.
+ */
+
+// Export ----
+const SunCalc = {
+  all,
+  times,
+  getSolarTime,
+  position,
+  getIsNight,
+  getPhase,
+};
+
+export default SunCalc;
+
+//-------------------------------------------------------
+/**
+ * @param {Date} date
+ * @param {number} latitude
+ * @param {number} longitude
+ * @param {string} timezoneId
+ * @returns {{ sunTimes: object, sunPosition: object, sunPhase: string }}
+ */
+function all(date, latitude, longitude, timezoneId) {
+  const sunTimes = SunCalc.times(date, latitude, longitude, timezoneId);
+  const sunPosition = SunCalc.position(latitude, longitude, date);
+  const sunPhase = SunCalc.getPhase(sunPosition.altitude, sunTimes.noon);
+
+  return {
+    sunTimes,
+    sunPosition,
+    sunPhase,
+  };
+}
+//-------------------------------------------------------
+// 'timeZone' es necesario para devolver las horas locales
+/**
+ * @param {Date} date
+ * @param {number} latitude
+ * @param {number} longitude
+ * @param {string} timezoneId
+ * @returns {{ date: Date, sunrise: string, sunset: string, noon: string, dawn: string, dusk: string }}
+ */
+function times(date, latitude, longitude, timezoneId) {
+  const times = SunCalc3.getSunTimes(date, latitude, longitude);
+
+  const sunTimes = {
+    date: date,
+    sunrise: getLocalTimeFromTz(timezoneId, times.sunriseStart.value),
+    sunset: getLocalTimeFromTz(timezoneId, times.sunsetStart.value),
+    noon: getLocalTimeFromTz(timezoneId, times.solarNoon.value),
+    dawn: getLocalTimeFromTz(timezoneId, times.civilDawn.value),
+    dusk: getLocalTimeFromTz(timezoneId, times.civilDusk.value),
+  };
+
+  // console.log(sunTimes);
+  return sunTimes;
+}
+//-------------------------------------------------------
+/**
+ * @param {Date} date
+ * @param {number} lng
+ * @param {string} offsetSign - "+" or "-"
+ * @param {number} offset - UTC offset in hours
+ * @returns {string} - Local time in "HH:mm" format
+ */
+function getSolarTime(date, lng, offsetSign, offset) {
+  // Convert offsetSign and offset to a numeric UTC offset (e.g., -3, +2)
+  const utcOffset = (offsetSign === "-" ? -1 : 1) * Math.abs(Number(offset));
+  const solarTime = SunCalc3.getSolarTime(date, lng, utcOffset);
+  return timeString(solarTime);
+}
+//-------------------------------------------------------
+/**
+ * @param {number} latitude
+ * @param {number} longitude
+ * @returns {{date: string, azimuth: number, direction: string, direction_full: string, altitude: number, zenith: number, declination: number}}
+ */
+function position(latitude, longitude, date = new Date(), language = "es-ES") {
+  const position = SunCalc3.getPosition(date, latitude, longitude);
+
+  // Get text
+  const direction = degreesToCompass(position.azimuthDegrees, language);
+
+  return {
+    date: dateFormat(date),
+    azimuth: position.azimuthDegrees,
+    direction: direction.short,
+    direction_full: direction.full,
+    altitude: Math.round(position.altitudeDegrees),
+    zenith: position.zenithDegrees,
+    declination: position.declination,
+  };
+}
+//-------------------------------------------------------
+// Sun phase
+//-------------------------------------------------------
+/**
+ * @param {number} lat
+ * @param {number} lon
+ * @param {string} timezoneId
+ * @param {number | Date} date
+ * @param {string} dateStr
+ * @returns {boolean} - true if it's night, false otherwise
+ */
+function getIsNight(lat, lon, timezoneId, date, dateStr) {
+  const times = SunCalc3.getSunTimes(date, lat, lon);
+
+  // se pueden comparar horas(hh:mm) estando en formato texto
+  // y así no tenemos que tener en cuenta el día, mes.
+  const timeUp = getLocalTimeFromTz(timezoneId, times.sunriseEnd.value);
+  const timeDown = getLocalTimeFromTz(
+    timezoneId,
+    times.goldenHourDuskStart.value,
+  );
+
+  return dateStr < timeUp || dateStr > timeDown;
+}
+//-------------------------------------------------------
+/**
+ * @param {number} altitude
+ * @param {string} noon
+ * @returns {string} - The phase of the sun based on its altitude
+ */
+function getPhase(altitude, noon) {
+  const nowTime = nowString();
+
+  let phase = "day";
+  if (altitude < 4) {
+    phase = nowTime > noon ? "dayEnd" : "dayStart";
+  }
+  if (altitude < 2) {
+    phase = nowTime > noon ? "sunset" : "sunrise";
+  }
+  if (altitude < -5) {
+    phase = nowTime > noon ? "dusk" : "dawn";
+  }
+  if (altitude < -18) {
+    phase = "night";
+  }
+
+  return phase;
+}
+//-------------------------------------------------------
+// function getPhase2(date, sunTimes, timeZone) {
+// }
+//-------------------------------------------------------

package/src/astronomy/timeZoneInfo.js

@@ -0,0 +1,89 @@
+// @ts-nocheck
+/**
+ * @module astronomy/time-date
+ */
+
+import { timeString } from "./timehelpers.js";
+
+//------------------------------------------------------
+/**
+ * Google API: Get local time from any location
+ *
+ * @param {string} apiKey - GoogleMaps API key.
+ * @param {number} lat
+ * @param {number} lng
+ * @returns {Promise<any | LocalTimeData>} - An object containing the local time and timezone information:
+ * @throws {Error} - If the API request fails or returns an error status.
+ */
+export async function getLocalTimeInfo(apiKey, lat, lng) {
+  const timestamp = Math.floor(Date.now() / 1000);
+  const url =
+    "https://maps.googleapis.com/maps/api/timezone/json?" +
+    `location=${lat},${lng}&timestamp=${timestamp}&key=${apiKey}`;
+
+  // Log: hidden apiKey
+  console.info(">> Google (time)", url.replace(/key=[^&]+/, "key=********"));
+
+  // Fetch timezone information ---
+  return fetch(url)
+    .then((response) => response.json())
+    .then((data) => {
+      // Error ---
+      if (data.status !== "OK") {
+        console.error(data);
+        return getLocalTimeDataErr();
+      }
+
+      // Success ---
+      return getLocalTimeData(data);
+    })
+    .catch((error) => {
+      console.error(error);
+    });
+}
+//------------------------------------------------------
+/**
+ * @private
+ * @param {Object} timezoneInfo - The timezone Google API information.
+ * @param {number} timezoneInfo.rawOffset - The raw offset in seconds.
+ * @param {number} timezoneInfo.dstOffset - The DST offset in seconds.
+ * @param {string} timezoneInfo.timeZoneName - The name of the timezone.
+ * @param {string} timezoneInfo.timeZoneId - The ID of the timezone.
+ * @returns {LocalTimeData} - An object containing the local time and timezone information.
+ */
+function getLocalTimeData(timezoneInfo) {
+  // Time
+  const date = new Date();
+  const utc = date.getTime() + date.getTimezoneOffset() * 60000;
+  const localTime =
+    utc + 1000 * timezoneInfo.rawOffset + 1000 * timezoneInfo.dstOffset;
+  const time = new Date(localTime);
+
+  return {
+    time: time,
+    timeStr: timeString(time),
+    timezone: timezoneInfo.timeZoneName,
+    timezoneId: timezoneInfo.timeZoneId,
+    offset: timezoneInfo.rawOffset / 3600,
+    offsetSign: timezoneInfo.rawOffset < 0 ? "" : "+",
+    dstOffset: timezoneInfo.dstOffset / 3600,
+  };
+}
+//------------------------------------------------------
+/**
+ * @private
+ * @returns {LocalTimeData} - An object containing the local time and timezone information when error.
+ */
+function getLocalTimeDataErr() {
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  return {
+    time: new Date(),
+    timeStr: timeString(new Date()),
+    timezone: timezone,
+    timezoneId: timezone,
+    offset: 0,
+    offsetSign: "+",
+    dstOffset: 0,
+  };
+}
+//------------------------------------------------------

package/src/astronomy/timehelpers.js

@@ -0,0 +1,69 @@
+/**
+ * @module astronomy/time-date
+ */
+
+//------------------------------------------------------
+/**
+ * Formatea una fecha a un string legible.
+ *
+ * @param {Date} [date]
+ * @param {boolean} [sec=false]
+ * @returns {string} La fecha formateada.
+ */
+export function timeString(date = new Date(), sec = false) {
+  if (sec) {
+    return date.toLocaleTimeString([], {
+      hour: "2-digit",
+      minute: "2-digit",
+      hour12: false,
+      second: "2-digit",
+    });
+  }
+
+  return date.toLocaleTimeString([], {
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  });
+}
+//------------------------------------------------------
+export function nowString(sec = false) {
+  return timeString(new Date(), sec);
+}
+//------------------------------------------------------
+/**
+ * Formatea una fecha a un string legible.
+ *
+ * @param {Date} [date=new Date()] La fecha a formatear.
+ * @returns {string} La fecha formateada.
+ */
+export function dateFormat(date = new Date()) {
+  const options = {
+    weekday: "long",
+    day: "numeric",
+    month: "short",
+  };
+  // @ts-ignore
+  return date.toLocaleDateString([], options);
+}
+//------------------------------------------------------
+/**
+ * Get local time from timezone
+ *
+ * @param {string} timeZone - The timezone string (e.g., 'America/New_York').
+ * @param {Date | number} [date=new Date()] - The date object to format. Defaults to the current date.
+ * @returns {string} - The formatted local time string.
+ */
+export function getLocalTimeFromTz(timeZone, date = new Date()) {
+  // Timezone example
+  // timeZone = 'America/New_York';
+
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone: timeZone,
+    hour: "numeric",
+    minute: "numeric",
+    hour12: false,
+  });
+  return formatter.format(date);
+}
+//------------------------------------------------------

package/src/astronomy/types.js

@@ -0,0 +1,30 @@
+/**
+ * @module astronomy/types
+ */
+
+/**
+ * @typedef {Object} AstroPosition
+ * @property {number} altitude
+ * @property {number} azimuth
+ * @property {string} direction
+ * @property {string} direction_full
+ */
+
+/**
+ * @typedef {Object} MoonData
+ * @property {AstroPosition} position
+ * @property {Object} next
+ * @property {string} next.newMoon - Date of the next new moon.
+ * @property {string} next.fullMoon - Date of the next full moon.
+ */
+
+/**
+ * @typedef {Object} LocalTimeData
+ * @property {Date} time - The local time.
+ * @property {string} timeStr - The formatted local time string.
+ * @property {string} timezone - The timezone name.
+ * @property {string} timezoneId - The timezone ID.
+ * @property {number} offset - The UTC offset in hours.
+ * @property {string} offsetSign - The sign of the offset ('+' or '-').
+ * @property {number} dstOffset - The DST offset in hours.
+ */

package/src/geolocation/getGeolocation.js

@@ -0,0 +1,49 @@
+/**
+ * @module Geolocation
+ */
+
+import geolocationCapacitor from "./lib/geolocation.js";
+import reverseGeocoding from "./lib/reversegeocoding.js";
+
+/**
+ * Get the current geolocation of the device and reverse
+ * geocode it to get the address.
+ *
+ * @returns {Promise<{latitude: number, longitude: number, formatted_address: string}>}
+ * @throws {Error} If geolocation is not supported or permission is denied.
+ */
+export async function getGeolocation() {
+  let location = null;
+  let address = null;
+
+  // Location ---
+  try {
+    location = await geolocationCapacitor();
+    // location.latitude = '25.90197748117876'; location.longitude = '-65.71650426928204';
+  } catch (error) {
+    throw new Error("Geolocation error: " + error.message);
+  }
+
+  // Address ---
+  try {
+    address = await reverseGeocoding(
+      location.latitude,
+      location.longitude,
+      // @ts-ignore
+      import.meta.env.VITE_googlemaps_api_key,
+    );
+  } catch (error) {
+    console.log("reverseGeocoding - error: ", error.message);
+    address = {
+      formatted_address:
+        "[" + location.latitude + ", " + location.longitude + "]",
+    };
+  }
+
+  // Return data ---
+  return {
+    ...location,
+    ...address,
+  };
+}
+//--------------------------------------------

package/src/geolocation/lib/geolocation.js

@@ -0,0 +1,44 @@
+/**
+ * Get the current geolocation of the device with the browser.
+ *
+ * @returns {Promise<{latitude: number, longitude: number}>}
+ * @throws {Error} If geolocation is not supported or permission is denied.
+ */
+export default async function geolocation() {
+  const geolocOptions = {
+    enableHighAccuracy: true,
+    timeout: 6 * 1000,
+    maximumAge: 0,
+  };
+
+  try {
+    const data = await new Promise((resolve, reject) => {
+      if ("geolocation" in navigator) {
+        navigator.geolocation.getCurrentPosition(
+          resolve,
+          reject,
+          geolocOptions,
+        );
+      } else {
+        reject(new Error("Geolocation is not supported"));
+      }
+    });
+
+    return {
+      latitude: data.coords.latitude,
+      longitude: data.coords.longitude,
+    };
+  } catch (error) {
+    console.error(error);
+    if (error.code === error.PERMISSION_DENIED) {
+      throw new Error("Geolocation: permission denied");
+    }
+    if (error.code === error.POSITION_UNAVAILABLE) {
+      throw new Error("Geolocation: position unavailable");
+    }
+    if (error.code === error.TIMEOUT) {
+      throw new Error("Geolocation: timeout");
+    }
+    throw new Error("Geolocation: unknown error");
+  }
+}

package/src/geolocation/lib/geolocationCapacitor.js

@@ -0,0 +1,21 @@
+import { Geolocation } from "@capacitor/geolocation";
+
+/**
+ * Get the current GPS location of the device with Capacitor.
+ *
+ * @returns {Promise<{latitude: number, longitude: number}>}
+ * @throws {Error} If geolocation is not supported or permission is denied.
+ */
+export default async function geolocationCapacitor() {
+  try {
+    const coordinates = await Geolocation.getCurrentPosition();
+    // console.log('geolocation - coordinates: ', coordinates);
+
+    return {
+      latitude: coordinates.coords.latitude,
+      longitude: coordinates.coords.longitude,
+    };
+  } catch (_error) {
+    throw new Error("Error al obtener la ubicación");
+  }
+}