@angelrove/forecast-utils 1.1.18 → 1.1.20

package/dist/types/utils/wind/windLevel.d.ts

@@ -1,30 +1,14 @@
-/**
- * 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
- * @memberof module:Utils
- */
-export function getWindLevel(speed: number): WindLevel | null;
 export type WindLevel = {
-    /**
-     * - Level ID
-     */
     id: number;
-    /**
-     * - Minimum wind speed for this level
-     */
     speed: number;
-    /**
-     * - Color representing this level
-     */
     color: string;
-    /**
-     * - Text representing this level
-     */
     tx: string;
-    /**
-     * - Text representing this level
-     */
     txEn: string;
 };
+/**
+ * Return the wind level based on the speed.
+ *
+ * @param speed Wind speed in km/h
+ * @return Wind level object or null if speed is null
+ */
+export declare function getWindLevel(speed: number): WindLevel | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "Jose Angel Romero Vegas",
   "name": "@angelrove/forecast-utils",
-  "version": "1.1.18",
+  "version": "1.1.20",
   "description": "Utilities for obtaining weather and astronomy forecast data.",
   "license": "MIT",
   "publishConfig": {
@@ -10,7 +10,7 @@
   "homepage": "https://github.com/angelrove/forecast-utils",
   "type": "module",
   "scripts": {
-    "docs:md": "bunx jsdoc2md --separators $(cat jsdoc-files.txt) > README.md ; cat README_HEAD.md README.md > temp && mv temp README.md; echo Remember add new files to - jsdoc-files.txt -!!!"
+    "docs": "typedoc"
   },
   "types": "dist/types/index.d.ts",
   "exports": {
@@ -32,17 +32,19 @@
     "JavaScript"
   ],
   "peerDependencies": {
+    "@capacitor/geolocation": "^7.1.2",
     "react": "^19.1.0",
     "suncalc3": "^2.0.5",
-    "swr": "^2.3.3",
-    "@capacitor/geolocation": "^7.1.2"
+    "swr": "^2.3.3"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.4",
     "@types/react": "^19.1.12",
     "@types/react-dom": "^19.1.9",
-    "jsdoc-to-markdown": "^9.1.2",
     "typescript": "^5.9.2"
   },
-  "dependencies": {}
+  "dependencies": {
+    "typedoc": "^0.28.12",
+    "typedoc-plugin-markdown": "^4.8.1"
+  }
 }

package/src/OpenMeteo/conf.js

@@ -39,7 +39,7 @@ export function getPath(lat, lon, path) {
  * @param {string} url
  */
 function devLog(title, url) {
-  // @ts-ignore
+  /* @ts-expect-error */
   if (import.meta.env.MODE === "development") {
     // console.log('%c> fetch [' + title + ']:', 'color:#9e9', url);
     console.log("> fetch [" + title + "]:", url);

package/src/OpenMeteo/current/transformer.js

@@ -2,7 +2,7 @@
  * 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.
+ * @returns {object|null} - The transformed data object or null if the input is invalid.
  */
 export default function transformer(data) {
   if (!data) return null;

package/src/OpenMeteo/current/{useForecastCurrent.js → useForecastCurrent.ts}

@@ -1,23 +1,23 @@
-// @ts-nocheck
 import useSWR from "swr";
 import { fetcher, getPath } from "../conf.js";
+import type { ForecastData } from "../types";
 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 {ForecastData} {data, isLoading, isError, apiUrl}
- * @memberof module:OpenMeteo
  */
-export function useForecastCurrent(lat, lon, refreshIntervalMin = 0) {
-  if (!lat || !lon) {
+export function useForecastCurrent(
+  lat: number | undefined,
+  lon: number | undefined,
+  refreshIntervalMin: number = 0): ForecastData
+  {
+  // Validate --
+  if (lat == null || lon == null) {
     throw new Error("useForecastCurrent: invalid coordinates");
   }
 
+  // Fetch ---
   const apiUrl = getPath(lat, lon, fetchParams);
   const { data, error, isLoading } = useSWR(apiUrl, fetcher, {
     refreshInterval: refreshIntervalMin * 60 * 1000,

package/src/OpenMeteo/daily/transformer.js

@@ -2,7 +2,7 @@
  * 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.
+ * @returns {object|null} - The transformed data object or null if the input is invalid.
  */
 export default function transformer(data) {
   if (!data) return null;

package/src/OpenMeteo/daily/{useForecastDaily.js → useForecastDaily.ts}

@@ -1,23 +1,20 @@
-// @ts-nocheck
 import useSWR from "swr";
 import { fetcher, getPath } from "../conf.js";
+import type { ForecastData } from "../types";
 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 {ForecastData} {data, isLoading, isError, apiUrl}
- * @memberof module:OpenMeteo
  */
-export function useForecastDaily(lat, lon, refreshIntervalMin = 0) {
+export function useForecastDaily(
+  lat: number | undefined,
+  lon: number | undefined,
+  refreshIntervalMin: number = 0): ForecastData
+  {
   // Validate --
-  if (!lat || !lon) {
+  if (lat == null || lon == null) {
     throw new Error("useForecastDaily: invalid coordinates");
   }
 

package/src/OpenMeteo/hourly/{useForecastHourly.js → useForecastHourly.ts}

@@ -1,20 +1,21 @@
-// @ts-nocheck
 import useSWR from "swr";
 import { fetcher, getPath } from "../conf.js";
 import { getDatesFromNumDays } from "../helpers.js";
+import type { ForecastData } from "../types";
 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 {ForecastData} {data, isLoading, isError, apiUrl}
- * @memberof module:OpenMeteo
  */
-export function useForecastHourly(location, dayNum) {
-  if (!location.latitude || !location.longitude) {
-    throw new Error("useForecastHourly: invalid coordinates");
+export function useForecastHourly(
+  lat: number,
+  lon: number,
+  dayNum: number): ForecastData
+  {
+
+  // Validate --
+  if (lat == null || lon == null) {
+    throw new Error("useForecastHourly: invalid coordinates: ["+lon+"]["+lat+"]");
   }
 
   // Fetch ---
@@ -28,7 +29,7 @@ export function useForecastHourly(location, dayNum) {
     dates.endDate +
     "&" +
     fetchParams;
-  apiUrl = getPath(location.latitude, location.longitude, apiUrl);
+  apiUrl = getPath(lat, lon, apiUrl);
 
   const { data, error, isLoading } = useSWR(apiUrl, fetcher);
 

package/src/OpenMeteo/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Use the OpenWeather forecast API
+ * @module OpenMeteo
+ *
+ */
+
+export { useForecastCurrent } from "./current/useForecastCurrent";
+export { useForecastDaily } from "./daily/useForecastDaily";
+export { useForecastHourly } from "./hourly/useForecastHourly";
+export type { ForecastData, WeatherSymbol } from "./types";
+export { weatherSymbol } from "./weatherSymbol/weatherSymbol";
+

package/src/OpenMeteo/types.ts

@@ -0,0 +1,14 @@
+/**
+ */
+
+export type ForecastData = {
+  data: any; // 👈 Cambiar al tipo real que devuelve `transformer`
+  apiUrl: string;
+  isLoading: boolean;
+  isError: unknown;
+};
+
+export type WeatherSymbol = {
+  icon: string;
+  description: string;
+};

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

@@ -21,7 +21,7 @@
  */
 
 /**
- * @typedef {Object} WeatherCodeEntry
+ * @typedef {object} WeatherCodeEntry
  * @property {number} code - WMO Weather interpretation codes (WW).
  * @property {string} icon - Icon name.
  * @property {string} description - Description.

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

@@ -21,7 +21,7 @@
  */
 
 /**
- * @typedef {Object} WeatherCodeEntry
+ * @typedef {object} WeatherCodeEntry
  * @property {number} code - WMO Weather interpretation codes (WW).
  * @property {string} icon - Icon name.
  * @property {string} description - Description.

package/src/OpenMeteo/weatherSymbol/{weatherSymbol.js → weatherSymbol.ts}

@@ -1,22 +1,16 @@
+import type { WeatherSymbol } from "../types";
 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 }}
- * { icon: string, description: string }
- * @memberof module:OpenMeteo
  */
 export function weatherSymbol(
-  code,
-  precipitation = undefined,
-  night = false,
-  dark = false,
-) {
+  code: any,
+  precipitation: number | undefined = undefined,
+  night: boolean = false,
+  dark: boolean = false,
+): WeatherSymbol
+{
   // Parse code ---
   let msgPlus = "";
   let theCode = code;

package/src/astronomy/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @module Astronomy
+ *
+ */
+
+export { MoonCalc } from "./moon/MoonCalc";
+export type { AstroPosition, MoonData, MoonDataExt, MoonTimes } from "./moon/types";
+export { SunCalc } from "./sun/SunCalc";
+

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-ignore
+/* @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

@@ -10,16 +10,16 @@
  * @module Astronomy/SunCalc
  */
 
-// @ts-ignore
+/* @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;
 
 //-------------------------------------------------------
 /**
@@ -35,11 +34,10 @@ export default SunCalc;
  * @param {number} latitude
  * @param {number} longitude
  * @param {string} timezoneId
- * @returns {{ sunTimes: Object, sunPosition: Object, sunPhase: string }}
- * { sunTimes: Object, sunPosition: Object, sunPhase: string }
- * @memberof module:Astronomy/SunCalc
+ * @returns {{ sunTimes: object, sunPosition: object, sunPhase: string }}
+ * { sunTimes: object, sunPosition: object, sunPhase: string }
  */
-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";