@angelrove/forecast-utils 1.1.19 → 1.1.21

package/src/astronomy/moon/{MoonCalc.js → MoonCalc.ts}

@@ -6,66 +6,27 @@
  * Importante!:
  * ¡Solo proporcionar HORA LOCAL DEL SISTEMA!: 'new Date()'
  *
- * @module Astronomy/MoonCalc
  */
 
 /* @ts-expect-error */
 import SunCalc from "suncalc3";
-import TimeDateStr from "../../utils/timehelpers.js";
+import { TimeDateStr } from "../../utils/timehelpers.js";
 import { parseBasicData } from "./parseBasicData.js";
+import type { MoonData, MoonDataExt, MoonTimes } from "./types.js";
 
 /**
  * MoonCalc.
  * @ignore
  */
-const MoonCalc = {
-  data,
-  dataExt,
-  times,
-  emoji,
-  getUpOrDown,
+export const MoonCalc = {
+  data, dataExt, times, emoji, getUpOrDown,
 };
-export default MoonCalc;
-
-/**
- * @memberof module:Astronomy
- * @typedef {object} AstroPosition
- * @property {number} altitude
- * @property {number} azimuth
- * @property {string} direction
- * @property {string} direction_full``
- */
-
-/**
- * @memberof module:Astronomy/MoonCalc
- * @typedef {object} MoonDataExt
- * @property {string} date
- * @property {string} time
- * @property {string} illumination
- * @property {string} phase
- * @property {string} phaseId
- * @property {string} emoji
- * @property {number} parallacticAngle
- * @property {number} angle
- * @property {AstroPosition} position
- * @property {object} next
- */
-
-/**
- * @memberof module:Astronomy/MoonCalc
- * @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.
- */
 
 /**
  * Mapa de fases lunares.
  * { phaseId, phaseName }
  *
  * @type {Object.<string, string>}
- * @memberof module:Astronomy/MoonCalc
  */
 const phasesES = {
   newMoon: "Luna Nueva",
@@ -78,16 +39,15 @@ const phasesES = {
   waningCrescentMoon: "Luna Menguante",
 };
 
+type PhaseId = keyof typeof phasesES;
+
 //--------------------------------------------------------------------
-/**
- * @param {number} latitude
- * @param {number} longitude
- * @param {Date} [date=new Date()]
- * @param {string} [language=es-ES]
- * @returns {MoonData} Moon info object
- * @memberof module:Astronomy/MoonCalc
- */
-function data(latitude, longitude, date = new Date(), language = "es-ES") {
+export function data(
+  latitude: number,
+  longitude: number,
+  date: Date = new Date(),
+  language: string = "es-ES"): MoonData
+  {
   // date.setHours(date.getHours() + 0); // debug
   const data = SunCalc.getMoonData(date, latitude, longitude);
   // console.log("%cdebug:", "color:yellow", data.illumination.next.newMoon.value);
@@ -99,14 +59,13 @@ function data(latitude, longitude, date = new Date(), language = "es-ES") {
  * 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 {MoonDataExt} Full information
- * @memberof module:Astronomy/MoonCalc
  */
-function dataExt(latitude, longitude, date = new Date(), language = "es-ES") {
+export function dataExt(
+  latitude: number,
+  longitude: number,
+  date: Date = new Date(),
+  language: string = "es-ES"): MoonDataExt
+  {
   const data = SunCalc.getMoonData(date, latitude, longitude);
 
   // Illumination
@@ -114,8 +73,8 @@ function dataExt(latitude, longitude, date = new Date(), language = "es-ES") {
     Number((data.illumination.fraction * 100).toFixed(1)) + "%";
 
   // Phase
-  const emoji = data.illumination.phase.emoji;
-  const phaseId = String(data.illumination.phase.id);
+  const emojiStr = data.illumination.phase.emoji;
+  const phaseId = String(data.illumination.phase.id) as PhaseId;
   const phase = phasesES[phaseId];
 
   // Angle
@@ -133,7 +92,7 @@ function dataExt(latitude, longitude, date = new Date(), language = "es-ES") {
     illumination: illumination,
     phase: phase,
     phaseId: phaseId,
-    emoji: emoji,
+    emoji: emojiStr,
     parallacticAngle: parallacticAngle,
     angle: Math.round(angle),
     position: basicData.position,
@@ -141,32 +100,22 @@ function dataExt(latitude, longitude, date = new Date(), language = "es-ES") {
   };
 }
 //--------------------------------------------------------------------
-/**
- * @param {number} latitude
- * @param {number} longitude
- * @param {Date} [date=new Date()]
- * @returns {string} Emoji of the moon phase
- * @memberof module:Astronomy/MoonCalc
- */
-function emoji(latitude, longitude, date = new Date()) {
+export function emoji(
+  latitude: number,
+  longitude: number,
+  date: Date = new Date()): string
+  {
   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}} Moon times
- * @memberof module:Astronomy/MoonCalc
- */
-function times(latitude, longitude, timezoneId, date = new Date()) {
-  const ret = {
-    rise: "",
-    set: "",
-    highest: "",
-  };
+export function times(
+  latitude: number,
+  longitude: number,
+  timezoneId: string,
+  date: Date = new Date()): MoonTimes
+  {
+  const ret = {} as MoonTimes;
 
   const times = SunCalc.getMoonTimes(date, latitude, longitude);
   if (times.alwaysUp) {
@@ -189,13 +138,7 @@ function times(latitude, longitude, timezoneId, date = new Date()) {
   return ret;
 }
 //--------------------------------------------------------------------
-/**
- * @param {number} altitude
- * @param {Date} highest
- * @returns {string} - Up or down emoji
- * @memberof module:Astronomy/MoonCalc
- */
-function getUpOrDown(altitude, highest) {
+export function getUpOrDown(altitude: number, highest: Date): string {
   const now = new Date();
   let upOrDown = ""; // ◓ ◒
 

package/src/astronomy/moon/parseBasicData.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
-import { degreesToCompass } from "../../utils/degreesToCompass.js";
-import TimeDateStr from "../../utils/timehelpers.js";
+import { degreesToCompass } from "../../utils/degreesToCompass";
+import { TimeDateStr } from "../../utils/timehelpers";
 
 /**
  * Parse basic data from SunCalc

package/src/astronomy/moon/types.ts

@@ -0,0 +1,36 @@
+export type AstroPosition = {
+  altitude: number;
+  azimuth: number;
+  direction: string;
+  direction_full: string;
+};
+
+export type MoonDataExt = {
+  date: string;
+  time: string;
+  illumination: string;
+  phase: string;
+  phaseId: string;
+  emoji: string;
+  parallacticAngle: number;
+  angle: number;
+  position: AstroPosition;
+  next: {
+    newMoon: string;
+    fullMoon: string;
+  };
+}
+
+export type MoonData = {
+  position: AstroPosition;
+  next: {
+    newMoon: string;
+    fullMoon: string;
+  };
+};
+
+export type MoonTimes = {
+  rise: string;
+  set: string;
+  highest: string;
+};

package/src/astronomy/sun/SunCalc.js

@@ -13,13 +13,13 @@
 /* @ts-expect-error */
 import { default as SunCalc3 } from "suncalc3";
 import { degreesToCompass } from "../../utils/degreesToCompass.js";
-import TimeDateStr from "../../utils/timehelpers.js";
+import { TimeDateStr } from "../../utils/timehelpers.js";
 
 /**
  * SunCalc.
  * @ignore
  */
-const SunCalc = {
+export const SunCalc = {
   all,
   times,
   getSolarTime,
@@ -27,7 +27,6 @@ const SunCalc = {
   getIsNight,
   getPhase,
 };
-export default SunCalc;
 
 //-------------------------------------------------------
 /**
@@ -37,9 +36,8 @@ export default SunCalc;
  * @param {string} timezoneId
  * @returns {{ sunTimes: object, sunPosition: object, sunPhase: string }}
  * { sunTimes: object, sunPosition: object, sunPhase: string }
- * @memberof module:Astronomy/SunCalc
  */
-function all(date, latitude, longitude, timezoneId) {
+export 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);
@@ -59,9 +57,8 @@ function all(date, latitude, longitude, timezoneId) {
  * @param {string} timezoneId
  * @returns {{ date: Date, sunrise: string, sunset: string, noon: string, dawn: string, dusk: string }}
  * { date: Date, sunrise: string, sunset: string, noon: string, dawn: string, dusk: string }
- * @memberof module:Astronomy/SunCalc
  */
-function times(date, latitude, longitude, timezoneId) {
+export function times(date, latitude, longitude, timezoneId) {
   const times = SunCalc3.getSunTimes(date, latitude, longitude);
 
   const sunTimes = {
@@ -86,9 +83,8 @@ function times(date, latitude, longitude, timezoneId) {
  * @param {string} offsetSign "+" or "-"
  * @param {number} offset UTC offset in hours
  * @returns {string} Local time in "HH:mm" format
- * @memberof module:Astronomy/SunCalc
  */
-function getSolarTime(date, lng, offsetSign, offset) {
+export 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);
@@ -100,9 +96,13 @@ function getSolarTime(date, lng, offsetSign, offset) {
  * @param {number} longitude
  * @returns {{date: string, azimuth: number, direction: string, direction_full: string, altitude: number, zenith: number, declination: number}}
  * {date: string, azimuth: number, direction: string, direction_full: string, altitude: number, zenith: number, declination: number}
- * @memberof module:Astronomy/SunCalc
  */
-function position(latitude, longitude, date = new Date(), language = "es-ES") {
+export function position(
+  latitude,
+  longitude,
+  date = new Date(),
+  language = "es-ES",
+) {
   const position = SunCalc3.getPosition(date, latitude, longitude);
 
   // Get text
@@ -128,9 +128,8 @@ function position(latitude, longitude, date = new Date(), language = "es-ES") {
  * @param {number | Date} date
  * @param {string} dateStr
  * @returns {boolean} true if it's night, false otherwise
- * @memberof module:Astronomy/SunCalc
  */
-function getIsNight(lat, lon, timezoneId, date, dateStr) {
+export function getIsNight(lat, lon, timezoneId, date, dateStr) {
   const times = SunCalc3.getSunTimes(date, lat, lon);
 
   // se pueden comparar horas(hh:mm) estando en formato texto
@@ -151,9 +150,8 @@ function getIsNight(lat, lon, timezoneId, date, dateStr) {
  * @param {number} altitude
  * @param {string} noon
  * @returns {string} The phase of the sun based on its altitude
- * @memberof module:Astronomy/SunCalc
  */
-function getPhase(altitude, noon) {
+export function getPhase(altitude, noon) {
   const nowTime = TimeDateStr.nowString();
 
   let phase = "day";

package/src/geolocation/{getGeolocation.js → getGeolocation.ts}

@@ -1,29 +1,16 @@
-import geolocationCapacitor from "./lib/geolocation.js";
-import reverseGeocoding from "./lib/reversegeocoding.js";
-
-/**
- * @memberof module:Geolocation
- * @typedef {object} ResolvedLocation
- * @property {number} latitude
- * @property {number} longitude
- * // Address
- * @property {string} sublocality
- * @property {string} locality
- * @property {string} country
- * @property {string} country_short
- * @property {string} formatted_address
- */
+import geolocationCapacitor from "./lib/geolocation";
+import reverseGeocoding from "./lib/reversegeocoding";
+import type { GeocodingAddress, ResolvedLocation } from "./types";
 
 /**
  * Get the current geolocation of the device and reverse geocode it to get the address.
  *
- * @memberof module:Geolocation
- * @returns {Promise<ResolvedLocation>} Promise
+ * @returns {Promise<ResolvedLocation>} Resolved location object.
  * @throws {Error} If geolocation is not supported or permission is denied.
  */
-export async function getGeolocation() {
-  let location;
-  let address = null;
+export async function getGeolocation(): Promise<ResolvedLocation> {
+  let location: { latitude: number; longitude: number };
+  let address = {} as GeocodingAddress;
 
   // Location ---
   try {
@@ -57,13 +44,9 @@ export async function getGeolocation() {
 
   // Return data ---
   return {
+    ...address,
     latitude: location.latitude,
-    longitude: location.longitude,
-    sublocality: address.sublocality,
-    locality: address.locality,
-    country: address.country,
-    country_short: address.country_short,
-    formatted_address: address.formatted_address,
+    longitude: location.longitude
   };
 }
 //--------------------------------------------

package/src/geolocation/index.ts

@@ -2,5 +2,7 @@
  * @module Geolocation
  */
 
-export { getGeolocation } from "./getGeolocation.js";
-export { timeFromLocation } from "./timeFromLocation.js";
+export { getGeolocation } from "./getGeolocation";
+export { timeFromLocation } from "./timeFromLocation";
+export type { ResolvedLocation } from "./types";
+

package/src/geolocation/lib/{geolocation.js → geolocation.ts}

@@ -4,7 +4,7 @@
  * @returns {Promise<{latitude: number, longitude: number}>}
  * @throws {Error} If geolocation is not supported or permission is denied.
  */
-export default async function geolocation() {
+export default async function geolocation(): Promise<{latitude: number, longitude: number}> {
   const geolocOptions = {
     enableHighAccuracy: true,
     timeout: 6 * 1000,
@@ -12,7 +12,7 @@ export default async function geolocation() {
   };
 
   try {
-    const data = await new Promise((resolve, reject) => {
+    const data = await new Promise<GeolocationPosition>((resolve, reject) => {
       if ("geolocation" in navigator) {
         navigator.geolocation.getCurrentPosition(
           resolve,

package/src/geolocation/lib/{reversegeocoding.js → reversegeocoding.ts}

@@ -1,16 +1,20 @@
+import type { GeocodingAddress } from "../types";
+
 /**
  * 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.
+ * @returns {Promise<GeocodingAddress>} - The address components.
  * @throws {Error} - If the API key is invalid or the request fails.
  */
-export default async function reverseGeocoding(latitude, longitude, api_key) {
+
+export default async function reverseGeocoding(
+  latitude: number,
+  longitude: number,
+  api_key: string): Promise<GeocodingAddress>
+  {
   // Validate --
   if (!api_key) {
     console.error("ReverseGeocoding: invalid api key");
@@ -97,11 +101,7 @@ export default async function reverseGeocoding(latitude, longitude, api_key) {
   };
 }
 
-/**
- * @param {string} title
- * @param {any} url
- */
-function devLog(title, url) {
+function devLog(title: string, url: any) {
   /* @ts-expect-error */
   if (import.meta.env.MODE === "development") {
     console.log(`> fetch [${title}]:`, url);

package/src/geolocation/timeFromLocation.js

@@ -1,8 +1,7 @@
 // @ts-nocheck
-import TimeDateStr from "../utils/timehelpers.js";
+import { TimeDateStr } from "../utils/timehelpers.js";
 
 /**
- * @memberof module:Geolocation
  * @typedef {object} LocalTimeData
  * @property {Date} time - The local time.
  * @property {string} timeStr - The formatted local time string.
@@ -22,7 +21,6 @@ import TimeDateStr from "../utils/timehelpers.js";
  * @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.
- * @memberof module:Geolocation
  */
 export async function timeFromLocation(apiKey, lat, lng) {
   const timestamp = Math.floor(Date.now() / 1000);

package/src/geolocation/types.ts

@@ -0,0 +1,18 @@
+export type GeocodingAddress = {
+  sublocality: string;
+  locality: string;
+  country: string;
+  country_short: string;
+  formatted_address: string;
+};
+
+export type ResolvedLocation = {
+  latitude: number;
+  longitude: number;
+  // Address
+  sublocality: string;
+  locality: string;
+  country: string;
+  country_short: string;
+  formatted_address: string;
+};

package/src/index.ts

@@ -1,8 +1,8 @@
 // Astronomy
-export { default as MoonCalc } from "./astronomy/moon/MoonCalc";
-export { default as SunCalc } from "./astronomy/sun/SunCalc";
+export { MoonCalc } from "./astronomy/moon/MoonCalc";
+export { SunCalc } from "./astronomy/sun/SunCalc";
 export { timeFromLocation } from "./geolocation/timeFromLocation";
-export { default as TimeDateStr } from "./utils/timehelpers";
+export { TimeDateStr } from "./utils/timehelpers";
 
 // Geolocation
 export { getGeolocation } from "./geolocation/getGeolocation";

package/src/utils/degreesToCompass.js

@@ -6,7 +6,6 @@
  * @typedef {object} Compass
  * @property {string} short - Short compass designation
  * @property {string} full - Full compass designation
- * @memberof module:Utils
  */
 
 /**
@@ -15,7 +14,6 @@
  * @constant
  * @property {string} short - Short compass designation
  * @property {string} full - Full compass designation
- * @memberof module:Utils
  */
 const directions = [
   { short: "N", full: "North" },
@@ -34,7 +32,6 @@ const directions = [
  * @constant
  * @property {string} short - Short compass designation
  * @property {string} full - Full compass designation
- * @memberof module:Utils
  */
 const directionsEs = [
   { short: "N", full: "Norte" },
@@ -53,7 +50,6 @@ const directionsEs = [
  * @param {number} degrees
  * @param {string} language - Language code ("en-US", "es-ES", "auto")
  * @returns {{short: string, full: string}} {short: string, full: string}
- * @memberof module:Utils
  */
 export function degreesToCompass(degrees, language = "auto") {
   if (degrees == null) return { short: "?", full: "?" };

package/src/utils/index.ts

@@ -2,9 +2,11 @@
  * @module Utils
  */
 
-export { degreesToCompass } from "./degreesToCompass.js";
-export { default as TimeDateStr } from "./timehelpers.js";
-export { getWarning, getWarningByDays } from "./warning.js";
-export { WindArrow } from "./wind/WindArrow.jsx";
-export { windArrowTx } from "./wind/windArrowTx.js";
-export { getWindLevel } from "./wind/windLevel.js";
+export { degreesToCompass } from "./degreesToCompass";
+export { TimeDateStr } from "./timehelpers";
+export { getWarning, getWarningByDays } from "./warning";
+export { WindArrow } from "./wind/WindArrow";
+export { windArrowTx } from "./wind/windArrowTx";
+export { getWindLevel } from "./wind/windLevel";
+export type { WindLevel } from "./wind/windLevel";
+

package/src/utils/timehelpers.js

@@ -8,13 +8,12 @@
  * TimeDateStr.
  * @ignore
  */
-const TimeDateStr = {
+export const TimeDateStr = {
   dateFormat,
   nowString,
   timeString,
   getLocalTimeFromTz,
 };
-export default TimeDateStr;
 
 //------------------------------------------------------
 /**
@@ -22,7 +21,6 @@ export default TimeDateStr;
  *
  * @param {Date} [date=new Date()] La fecha a formatear.
  * @returns {string} La fecha formateada.
- * @memberof module:Utils/TimeDateStr
  */
 function dateFormat(date = new Date()) {
   const options = {
@@ -40,7 +38,6 @@ function dateFormat(date = new Date()) {
  * @param {Date} [date]
  * @param {boolean} [sec=false]
  * @returns {string} La fecha formateada.
- * @memberof module:Utils/TimeDateStr
  */
 function timeString(date = new Date(), sec = false) {
   if (sec) {
@@ -64,7 +61,6 @@ function timeString(date = new Date(), sec = false) {
  *
  * @param {boolean} sec
  * @returns {String} now time as a formated string
- * @memberof module:Utils/TimeDateStr
  */
 function nowString(sec = false) {
   return timeString(new Date(), sec);
@@ -76,7 +72,6 @@ function nowString(sec = false) {
  * @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.
- * @memberof module:Utils/TimeDateStr
  */
 function getLocalTimeFromTz(timeZone, date = new Date()) {
   // Timezone example

package/src/utils/warning.js

@@ -4,14 +4,12 @@
  * @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.
- * @memberof module:Utils
  */
 
 /**
  * Alert levels for rain and showers
  *
  * @type {AlertLevel[]}
- * @memberof module:Utils
  */
 const ALERT_LEVEL = [
   { levelNum: 3, level: "red", precipitation: 120, showers: 60 },
@@ -28,7 +26,6 @@ const ALERT_LEVEL = [
  * @param {number} showersSumTomorrow
  * @returns {{ levelNum: number, level: string, message: string, day: number } | null}
  * {{ levelNum: number, level: string, message: string, day: number } | null}
- * @memberof module:Utils
  */
 export function getWarningByDays(
   precipitationSumToday,
@@ -60,12 +57,10 @@ export function getWarningByDays(
 /**
  * Get warning by precipitation and showers
  *
- * @export
  * @param {number} precipitation
  * @param {number} showers
  * @returns {{ levelNum: number, level: string, message: string } | null}
  * {{ levelNum: number, level: string, message: string } | null}
- * @memberof module:Utils
  */
 export function getWarning(precipitation, showers) {
   const warningRain = getWarningRain(precipitation);

package/src/utils/wind/WindArrow.jsx

@@ -1,13 +1,11 @@
 /**
  * SVG arrow indicating wind direction.
  *
- * @component JSX
  * @param {object} props - Component props.
  * @param {number} props.deg - Wind direction in degrees (0 = North, 90 = East, etc.).
  * @param {string} [props.size] - Tailwind CSS size class (e.g., 'size-10')
  * @param {number} [props.strokeWidth] - Stroke width of the arrow (range: 1–6).
  * @param {string} [props.className] - Additional CSS classes.
- * @memberof module:Utils
  */
 export function WindArrow({
   deg,

package/src/utils/wind/windArrowTx.js

@@ -3,7 +3,6 @@
  *
  * @param {number} deg - Wind direction in degrees.
  * @returns {string} Arrow representation of the wind direction.
- * @memberof module:Utils
  */
 export function windArrowTx(deg) {
   if (deg == null) {