use-weather-forecast 0.1.166 → 0.1.167

package/README.md

@@ -68,18 +68,37 @@ the package does when an upstream misbehaves.
 
 ### `Weather request failed: 400 Bad Request`
 
-Open-Meteo answers `400` for a query it cannot parse, and the usual way to
-build one is not a typo in your props: an IP geolocation upstream answers
-`200` with no coordinates in the body, `Number(undefined)` becomes `NaN`,
-`latitude=NaN` goes out on the wire. Everything that goes into a request is
-validated first now:
+Two different things produced this, and both are fixed.
+
+**A malformed URL.** Requests go through
+[`grab-url`](https://www.npmjs.com/package/grab-url), which turns every option
+it does not recognise into the GET query string and concatenates it onto the
+path. Passing it a URL that already had a query gave the request *two* `?`, and
+the last real parameter value absorbed the leftover option:
+
+```text
+...&daily=temperature_2m_max%2Cwind_speed_10m_max?retryAttempts=0
+```
+
+Open-Meteo read that as an unknown `daily` variable and answered `400`. It hit
+every weather provider on every call, since all four build a query -- while the
+geolocation lookups kept working, because their URLs carry no query of their own
+for the stray `?` to collide with. The query is now handed over as grab-url's
+own parameters, so grab-url writes the single `?` itself and there is no query
+string of ours left to corrupt.
+
+**A malformed query.** Open-Meteo also answers `400` for a query it cannot
+parse, and the usual way to build one is not a typo in your props: an IP
+geolocation upstream answers `200` with no coordinates in the body,
+`Number(undefined)` becomes `NaN`, `latitude=NaN` goes out on the wire.
+Everything that goes into a request is validated first:
 
 | Input | What happens to it |
 | --- | --- |
-| `latitude` / `longitude` | Must be finite and on the globe, and are rounded to 4 decimals. A geolocation response without them counts as a failed lookup, so the next provider gets a turn. Unusable props fall back to IP geolocation. |
-| `location.timezone` | Canonicalized (`US/Pacific` becomes `America/Los_Angeles`); a zone the runtime cannot resolve is dropped rather than sent, and Open-Meteo resolves the zone from the coordinates instead. |
+| `latitude` / `longitude` | Must be finite and on the globe, and are rounded to 4 decimals. A geolocation response without them counts as a failed lookup, so the next provider gets a turn. Unusable props fall back to IP geolocation. Coordinates on `location` are honoured like top-level ones, without an IP lookup. |
+| `location.timezone` | Canonicalized (`US/Pacific` becomes `America/Los_Angeles`); a zone the runtime cannot resolve is dropped rather than sent. With no zone given, the one IP geolocation reported is used, and Open-Meteo resolves it from the coordinates if there is none. |
 | `forecastDays` / `forecastHours` | Clamped to the 1-16 days and 1-384 hours the API accepts. |
-| Variable list | A `400` from an endpoint that refused one of the optional variables is retried once with the minimal set the widget needs. |
+| Variable list | A `400` from an endpoint that refused part of the query is asked again in a smaller shape: first only the variables every model supports, then that without `forecast_hours` and with `timezone=auto`. The units are never dropped -- a Celsius body read as Fahrenheit would render a plausible, wrong temperature. |
 
 ### Retries
 
@@ -104,9 +123,20 @@ upstream's rate limit.
 The fallbacks normalize their own condition codes, units and timestamps into
 the same shape Open-Meteo returns, so a failover is invisible in the rendered
 widget (wttr.in is 3-hourly rather than hourly). If every provider fails, a
-cached forecast up to a day old is served instead of throwing; only if there is
-no cache either does an error reach the widget, listing what each provider
-said.
+cached forecast up to a day old is served instead of throwing.
+
+### Reloading
+
+If even that produces nothing, the component reloads the whole forecast
+`reloadAttempts` more times (2 by default) with a growing pause -- 3s, then 6s.
+A failure that reaches this point means every provider failed at once, which is
+usually something that clears on its own: a flaky network on first paint, or
+every free upstream rate-limited in the same second. The component stays in its
+loading state while a reload is pending, so it renders nothing for a few
+seconds rather than flashing an error it is about to recover from.
+
+Only once the reloads are spent does an error reach the widget, listing what
+each provider said. `reloadAttempts={0}` shows it immediately instead.
 
 ```tsx
 <WeatherForecast
@@ -115,6 +145,8 @@ said.
   retryAttempts={3}
   retryDelay={400}
   timeout={15}
+  reloadAttempts={2}
+  reloadDelay={3000}
   fallbackLocation={{ city: 'Austin', latitude: 30.27, longitude: -97.74 }}
   allowStaleCache
   onProviderError={({ provider, stage, error }) => console.warn(stage, provider, error.message)}

package/dist/api/forecast.d.ts

@@ -4,12 +4,20 @@ import { type ForecastRequest } from './providers';
  * Everything that goes on the wire is validated first, then the providers are
  * tried in order until one answers.
  *
- * The `400 Bad Request` this used to render came from an unvalidated request:
- * a geolocation upstream answering 200 with no coordinates put `latitude=NaN`
- * in the URL, and an unknown timezone string or an out-of-range `forecastDays`
- * did the same. Those are caught in {@link buildForecastRequest} now, before a
- * request is sent, and anything that still fails falls through to the next
- * provider and finally to a stale cache entry.
+ * Two different things produced the `400 Bad Request` this used to render, and
+ * both are handled, in different places:
+ *
+ * - The **request** could be malformed. A geolocation upstream answering 200
+ *   with no coordinates put `latitude=NaN` in the URL; an unknown timezone
+ *   string or an out-of-range `forecastDays` did the same. Those are caught in
+ *   {@link buildForecastRequest}, before a request is sent.
+ * - The **URL** could be malformed after it left here, by the transport rather
+ *   than by anything in this file -- see `splitUrl` in `./http`. That one broke
+ *   every provider on every call, which is why the fallbacks below could not
+ *   rescue it.
+ *
+ * Anything that still fails falls through to the next provider and finally to a
+ * stale cache entry.
  */
 /** Cache key for a request, so a fallback provider's answer is reused like the primary one's. */
 export declare function forecastCacheKey(request: ForecastRequest): string;

package/dist/api/http.d.ts

@@ -10,7 +10,8 @@
  *
  * On top of that this module adds what the upstreams actually need to stay up:
  * a classified retry loop (repeat what can recover, give up immediately on a
- * request the server called invalid) with exponential backoff.
+ * request the server called invalid) with exponential backoff, and it hands
+ * grab-url a query string it cannot corrupt -- see {@link splitUrl}.
  */
 export type GrabJsonOptions = {
     headers?: Record<string, string>;
@@ -21,9 +22,15 @@ export type GrabJsonOptions = {
     /** default=15 Seconds before a single try is aborted. */
     timeout?: number;
     /**
-     * default=0 Times grab-url itself repeats a try that failed at the transport
-     * level, inside each of our `attempts`. Left at 0 so the backoff and the
-     * status classification below stay in charge of every repeat.
+     * default=0 Extra tries inside each of our `attempts`, run back-to-back with
+     * no backoff between them.
+     *
+     * This used to be forwarded to grab-url's own option of the same name. It no
+     * longer is -- grab-url turns any option it does not recognise into a query
+     * parameter, and `retryAttempts` is one it does not recognise, so forwarding
+     * it appended `?retryAttempts=0` to every URL (see {@link splitUrl}). The
+     * repeat is done here instead, which keeps the same try count without
+     * touching the URL.
      */
     retryAttempts?: number;
     /**
@@ -44,6 +51,35 @@ export declare class HttpRequestError extends Error {
 }
 /** No status at all means the request never reached the server -- worth a repeat. */
 export declare function isRetryableStatus(status?: number): boolean;
+/**
+ * Split a full URL into the path grab-url should request and the query it
+ * should build, because grab-url will not leave a query string we wrote alone.
+ *
+ * grab-url destructures the options it knows, then turns **every remaining
+ * option** into the GET query string and concatenates it onto the path. So a
+ * URL that already carries a `?` comes out with two of them, and the last real
+ * value silently absorbs the leftover option:
+ *
+ * ```text
+ * ...&daily=temperature_2m_max%2Cwind_speed_10m_max?retryAttempts=0
+ * ```
+ *
+ * Open-Meteo reads that trailing segment as part of the last `daily` variable,
+ * does not recognise it, and answers `400 Bad Request` -- which is exactly the
+ * `Weather request failed: 400 Bad Request` the widget used to render, on every
+ * weather provider (they all build a query), while the geolocation lookups kept
+ * working because their URLs have no query of their own for the stray `?` to
+ * collide with.
+ *
+ * Handing the query over as grab-url's own params instead means grab-url writes
+ * the single `?` itself, so there is no query string of ours left to corrupt --
+ * and an option it fails to recognise lands as one more harmless parameter
+ * rather than inside the value of a real one.
+ */
+export declare function splitUrl(url: string): {
+    path: string;
+    params: Record<string, string>;
+};
 /**
  * Request a JSON body, repeating what can recover and throwing a labelled
  * {@link HttpRequestError} once it cannot.

package/dist/api/providers/open-meteo.d.ts

@@ -6,7 +6,20 @@ declare const FULL_VARIABLES: {
     daily: string[];
 };
 type Variables = typeof FULL_VARIABLES;
-export declare function buildOpenMeteoUrl(endpoint: string, request: ForecastRequest, variables?: Variables): string;
+export type OpenMeteoQuery = {
+    /** default=FULL_VARIABLES Which variables to ask for. */
+    variables?: Variables;
+    /**
+     * default=false Leave out the range and zone parameters an endpoint can
+     * refuse on their own: `forecast_hours`, and a `timezone` other than `auto`.
+     *
+     * Only parameters that cannot change what the numbers *mean* are dropped --
+     * the units stay, since a Celsius body read as Fahrenheit would render a
+     * plausible, wrong temperature rather than an error.
+     */
+    omitOptional?: boolean;
+};
+export declare function buildOpenMeteoUrl(endpoint: string, request: ForecastRequest, query?: OpenMeteoQuery | Variables): string;
 /**
  * Open-Meteo, the package's primary source.
  *

package/dist/hooks/useWeatherForecast.d.ts

@@ -4,7 +4,11 @@ import type { WeatherForecastData, WeatherForecastOptions } from '../types';
  *
  * The last good forecast is kept while a refetch is in flight *and* if that
  * refetch fails, so a rate-limited upstream leaves the widget showing the
- * previous data rather than replacing it with an error.
+ * previous data rather than replacing it with an error. A first load that
+ * fails outright is retried `reloadAttempts` times with a growing pause, and
+ * stays in the loading state while a retry is pending -- the widget renders
+ * nothing for a few seconds rather than flashing an error it is about to
+ * recover from.
  */
 export declare function useWeatherForecast(options?: WeatherForecastOptions): {
     data: WeatherForecastData | null;

package/dist/index.cjs

@@ -165,11 +165,63 @@ function unwrapBody(payload) {
   }
   return payload;
 }
+function splitUrl(url) {
+  const separator = url.indexOf("?");
+  if (separator === -1) return { path: url, params: {} };
+  const params = {};
+  for (const [key, value] of new URLSearchParams(url.slice(separator + 1))) params[key] = value;
+  return { path: url.slice(0, separator), params };
+}
+var GRAB_RESERVED_OPTIONS = /* @__PURE__ */ new Set([
+  "headers",
+  "response",
+  "method",
+  "cache",
+  "timeout",
+  "baseURL",
+  "cancelOngoingIfNew",
+  "cancelNewIfOngoing",
+  "rateLimit",
+  "debug",
+  "infiniteScroll",
+  "logger",
+  "onRequest",
+  "onResponse",
+  "onError",
+  "onStream",
+  "unzip",
+  "dom",
+  "body",
+  "post",
+  "put",
+  "patch",
+  "debounce",
+  "repeat",
+  "repeatEvery",
+  "setDefaults",
+  "regrabOnStale",
+  "regrabOnFocus",
+  "regrabOnNetwork",
+  "cacheForTime",
+  "retryAttempts"
+]);
 async function grabJsonOnce(url, label, options) {
-  const { headers, retryAttempts = 0, timeout = 15 } = options;
-  const data = await (0, import_grab_url.default)(url, {
+  const { headers, timeout = 15 } = options;
+  const { path, params } = splitUrl(url);
+  const reserved = Object.keys(params).filter((key) => GRAB_RESERVED_OPTIONS.has(key));
+  if (reserved.length > 0) {
+    throw new HttpRequestError(
+      `${label} failed: ${reserved.join(", ")} cannot be sent as a query parameter`,
+      { retryable: false }
+    );
+  }
+  const data = await (0, import_grab_url.default)(path, {
+    // grab-url builds the query from the options it does not recognise, so the
+    // request's own parameters are passed as exactly that -- never as a query
+    // string on `path`. Anything added here has to be an option grab-url knows,
+    // or it goes out on the wire as a parameter.
+    ...params,
     headers,
-    retryAttempts,
     timeout,
     // Several widgets (or several locations in one widget) hit the same path
     // at once, and grab-url aborts the earlier call of a duplicate path by
@@ -196,16 +248,21 @@ async function grabJsonOnce(url, label, options) {
 async function grabJson(url, label, options = {}) {
   const attempts = Math.max(1, Math.trunc(options.attempts ?? 3));
   const retryDelay = Math.max(0, options.retryDelay ?? 400);
+  const immediate = Math.max(0, Math.trunc(options.retryAttempts ?? 0));
   let lastError;
   for (let attempt = 1; attempt <= attempts; attempt++) {
-    try {
-      return await grabJsonOnce(url, label, options);
-    } catch (error) {
-      lastError = error;
-      const retryable = !(error instanceof HttpRequestError) || error.retryable || options.retryClientErrors === true;
-      if (!retryable || attempt === attempts) break;
-      if (retryDelay > 0) await wait(retryDelay * 2 ** (attempt - 1));
+    let failure;
+    for (let immediateTry = 0; immediateTry <= immediate; immediateTry++) {
+      try {
+        return await grabJsonOnce(url, label, options);
+      } catch (error) {
+        failure = error;
+      }
     }
+    lastError = failure;
+    const retryable = !(failure instanceof HttpRequestError) || failure.retryable || options.retryClientErrors === true;
+    if (!retryable || attempt === attempts) break;
+    if (retryDelay > 0) await wait(retryDelay * 2 ** (attempt - 1));
   }
   throw lastError instanceof Error ? lastError : new HttpRequestError(String(lastError));
 }
@@ -440,15 +497,16 @@ var MINIMAL_VARIABLES = {
   hourly: ["temperature_2m", "weather_code"],
   daily: ["temperature_2m_max", "temperature_2m_min", "weather_code"]
 };
-function buildOpenMeteoUrl(endpoint, request, variables = FULL_VARIABLES) {
+function buildOpenMeteoUrl(endpoint, request, query = {}) {
+  const { variables = FULL_VARIABLES, omitOptional = false } = "current" in query ? { variables: query } : query;
   const params = new URLSearchParams({
     latitude: String(request.location.latitude),
     longitude: String(request.location.longitude),
-    timezone: request.timezone || "auto",
+    timezone: omitOptional ? "auto" : request.timezone || "auto",
     temperature_unit: request.temperatureUnit,
     wind_speed_unit: request.windSpeedUnit,
     forecast_days: String(request.forecastDays),
-    forecast_hours: String(request.forecastHours),
+    ...omitOptional ? {} : { forecast_hours: String(request.forecastHours) },
     current: variables.current.join(","),
     hourly: variables.hourly.join(","),
     daily: variables.daily.join(",")
@@ -505,24 +563,28 @@ function createOpenMeteoProvider(id, label, endpoint) {
     id,
     label,
     async fetchForecast(request) {
-      try {
-        const data = await grabJson(
-          buildOpenMeteoUrl(endpoint, request),
-          "Weather request",
-          request.transport
-        );
-        return parse(data, request);
-      } catch (error) {
-        if (!(error instanceof HttpRequestError)) throw error;
-        const invalidQuery = error.status === 400 || /cannot initialize|invalid|not supported/i.test(error.message);
-        if (!invalidQuery) throw error;
-        const data = await grabJson(
-          buildOpenMeteoUrl(endpoint, request, MINIMAL_VARIABLES),
-          "Weather request",
-          request.transport
-        );
-        return parse(data, request);
+      const shapes = [
+        {},
+        { variables: MINIMAL_VARIABLES },
+        { variables: MINIMAL_VARIABLES, omitOptional: true }
+      ];
+      let lastError;
+      for (const [index, shape] of shapes.entries()) {
+        try {
+          const data = await grabJson(
+            buildOpenMeteoUrl(endpoint, request, shape),
+            "Weather request",
+            request.transport
+          );
+          return parse(data, request);
+        } catch (error) {
+          lastError = error;
+          if (!(error instanceof HttpRequestError)) throw error;
+          const invalidQuery = error.status === 400 || /cannot initialize|invalid|not supported/i.test(error.message);
+          if (!invalidQuery || index === shapes.length - 1) throw error;
+        }
       }
+      throw lastError;
     }
   };
 }
@@ -838,7 +900,7 @@ function forecastCacheKey(request) {
   ].join("|");
 }
 async function resolveLocation(options) {
-  const explicit = normalizeCoordinates(options.latitude, options.longitude);
+  const explicit = normalizeCoordinates(options.latitude, options.longitude) ?? normalizeCoordinates(options.location?.latitude, options.location?.longitude);
   if (explicit) {
     return {
       ...options.location,
@@ -870,7 +932,10 @@ async function buildForecastRequest(options = {}) {
     // `undefined` means "let the provider resolve the zone from the
     // coordinates" (Open-Meteo's `timezone=auto`); an unrecognised zone string
     // is dropped here rather than sent, since Open-Meteo answers 400 for one.
-    timezone: normalizeTimezone(options.location?.timezone),
+    // A zone the caller gave wins over the one geolocation reported, but the
+    // geolocated zone is still used rather than discarded -- it is what makes
+    // the clock read in the location's own time on the first render.
+    timezone: normalizeTimezone(options.location?.timezone) ?? location.timezone,
     transport
   };
 }
@@ -901,31 +966,18 @@ async function getWeatherForecast(options = {}) {
 
 // src/hooks/useWeatherForecast.ts
 var import_react = require("react");
+var DEFAULT_RELOAD_ATTEMPTS = 2;
+var DEFAULT_RELOAD_DELAY_MS = 3e3;
 function providerKey(options) {
   const ids = (list) => (list ?? []).map((provider) => typeof provider === "string" ? provider : provider.id).join(",");
   return `${ids(options.weatherProviders)}|${ids(options.geoProviders)}`;
 }
-function useWeatherForecast(options = {}) {
-  const [data, setData] = (0, import_react.useState)(null);
-  const [error, setError] = (0, import_react.useState)(null);
-  const [loading, setLoading] = (0, import_react.useState)(true);
-  (0, import_react.useEffect)(() => {
-    let active = true;
-    setLoading(true);
-    setError(null);
-    getWeatherForecast(options).then((result) => {
-      if (active) setData(result);
-    }).catch((err) => {
-      if (active) setError(err instanceof Error ? err : new Error("Unknown error"));
-    }).finally(() => {
-      if (active) setLoading(false);
-    });
-    return () => {
-      active = false;
-    };
-  }, [
+function requestKey(options) {
+  return [
     options.latitude,
     options.longitude,
+    options.location?.latitude,
+    options.location?.longitude,
     options.geoEndpoint,
     options.ip,
     options.forecastDays,
@@ -937,10 +989,48 @@ function useWeatherForecast(options = {}) {
     options.retryDelay,
     options.timeout,
     options.allowStaleCache,
+    options.reloadAttempts,
+    options.reloadDelay,
     options.fallbackLocation?.latitude,
     options.fallbackLocation?.longitude,
     providerKey(options)
-  ]);
+  ].join("|");
+}
+function useWeatherForecast(options = {}) {
+  const [data, setData] = (0, import_react.useState)(null);
+  const [error, setError] = (0, import_react.useState)(null);
+  const [loading, setLoading] = (0, import_react.useState)(true);
+  const reloadAttempts = Math.max(0, Math.trunc(options.reloadAttempts ?? DEFAULT_RELOAD_ATTEMPTS));
+  const reloadDelay = Math.max(0, options.reloadDelay ?? DEFAULT_RELOAD_DELAY_MS);
+  const key = requestKey(options);
+  const [reload, setReload] = (0, import_react.useState)({ key, count: 0 });
+  if (reload.key !== key) setReload({ key, count: 0 });
+  (0, import_react.useEffect)(() => {
+    let active = true;
+    let timer;
+    setLoading(true);
+    setError(null);
+    getWeatherForecast(options).then((result) => {
+      if (!active) return;
+      setData(result);
+      setLoading(false);
+    }).catch((err) => {
+      if (!active) return;
+      setError(err instanceof Error ? err : new Error("Unknown error"));
+      if (reload.count >= reloadAttempts) {
+        setLoading(false);
+        return;
+      }
+      timer = setTimeout(
+        () => setReload((current) => ({ key: current.key, count: current.count + 1 })),
+        reloadDelay * 2 ** reload.count
+      );
+    });
+    return () => {
+      active = false;
+      if (timer !== void 0) clearTimeout(timer);
+    };
+  }, [key, reload.count]);
   return { data, error, loading };
 }