@chaosity/location-client-react 0.1.19 → 0.3.0

package/README.md

@@ -50,14 +50,17 @@ export default function RootLayout({
 
 ```tsx
 import { useLocationClient } from '@chaosity/location-client-react'
-import { SuggestCommand } from '@chaosity/location-client'
+import {
+  SuggestCommand,
+  type SuggestCommandOutput,
+} from '@chaosity/location-client'
 
 function SearchComponent() {
   const { client, loading, error } = useLocationClient()
 
   const searchPlaces = async (query: string) => {
     if (!client) return
-    const response = await client.send(
+    const response: SuggestCommandOutput = await client.send(
       new SuggestCommand({ QueryText: query, MaxResults: 5 }),
     )
     return response.ResultItems
@@ -87,9 +90,7 @@ function MapComponent() {
   useMapLanguage(mapInstance, language)
 
   useEffect(() => {
-    const map = new maplibregl.Map({
-      /* ... */
-    })
+    const map = new maplibregl.Map({/* ... */})
     map.once('load', () => setMapInstance(map))
     return () => map.remove()
   }, [])
@@ -261,6 +262,7 @@ All AWS Location Service commands are available through the client:
 ```tsx
 import {
   SuggestCommand,
+  type SuggestCommandOutput,
   GeocodeCommand,
   ReverseGeocodeCommand,
   GetPlaceCommand,
@@ -272,7 +274,7 @@ function MyComponent() {
   const { client } = useLocationClient()
 
   const search = async () => {
-    const response = await client!.send(
+    const response: SuggestCommandOutput = await client!.send(
       new SuggestCommand({ QueryText: 'Vancouver', MaxResults: 5 }),
     )
     return response.ResultItems
@@ -293,7 +295,10 @@ DEBUG=location-client-react:* npm run dev
 Full TypeScript support with types from AWS SDK:
 
 ```tsx
-import type { SuggestCommandOutput } from '@aws-sdk/client-geo-places'
+import {
+  SuggestCommand,
+  type SuggestCommandOutput,
+} from '@chaosity/location-client'
 
 const { client } = useLocationClient()
 const response: SuggestCommandOutput = await client!.send(

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { LocationClientProvider, useLocationClient, } from './provider/LocationClientProvider';
-export type { LocationClientProviderProps } from './provider/LocationClientProvider';
+export type { LocationClient, LocationClientProviderProps, SendOptions, } from './provider/LocationClientProvider';
 export { useMapLanguage } from './hooks/useMapLanguage';

package/dist/provider/LocationClientProvider.d.ts

@@ -1,8 +1,34 @@
 import type { ClientConfig } from '@chaosity/location-client';
-import { GeoPlacesClient } from '@chaosity/location-client';
 import type { ReactNode } from 'react';
+/**
+ * Per-request transport options.
+ *
+ * Declared structurally rather than imported so this package builds against the
+ * currently published client; it matches `SendOptions` there exactly.
+ */
+export interface SendOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    retry?: false | {
+        maxAttempts?: number;
+    };
+}
+/**
+ * What the provider hands out.
+ *
+ * An interface rather than `GeoPlacesClient` because the provider wraps the
+ * real client to refresh tokens first, and a class with private fields is not
+ * structurally assignable — which is why this used to be an `Object.create`
+ * prototype hack.
+ */
+export interface LocationClient {
+    readonly config: {
+        serviceId: string;
+    };
+    send<TInput, TOutput>(command: TInput, options?: SendOptions): Promise<TOutput>;
+}
 interface LocationClientContextValue {
-    client: GeoPlacesClient | null;
+    client: LocationClient | null;
     getToken: () => string | undefined;
     loading: boolean;
     error: string | null;
@@ -12,9 +38,7 @@ export interface LocationClientProviderProps {
     getConfig: () => Promise<ClientConfig & {
         expiresAt?: number;
     }>;
-    /** Seconds before expiry to proactively refresh (default: 60) */
-    refreshBuffer?: number;
 }
-export declare function LocationClientProvider({ children, getConfig, refreshBuffer, }: LocationClientProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function LocationClientProvider({ children, getConfig, }: LocationClientProviderProps): import("react").JSX.Element;
 export declare function useLocationClient(): LocationClientContextValue;
 export {};

package/dist/provider/LocationClientProvider.js

@@ -1,106 +1,194 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { GeoPlacesClient } from '@chaosity/location-client';
+import { GeoPlacesClient, TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from '@chaosity/location-client';
 import debug from 'debug';
 import { createContext, useCallback, useContext, useEffect, useRef, useState, } from 'react';
 const log = debug('location-client-react:provider');
 const LocationClientContext = createContext(undefined);
-export function LocationClientProvider({ children, getConfig, refreshBuffer = 60, }) {
+const DEFAULT_LIFETIME_MS = 900000;
+/**
+ * When this token needs replacing.
+ *
+ * The `exp` claim first — it is the only value that cannot disagree with what
+ * the API will accept, and the server-side TokenProvider reads the same one.
+ * `expiresAt` is whatever `getConfig` chose to report, and the final fallback
+ * is a guess used only when the token cannot be parsed at all.
+ */
+function expiryOf(cfg) {
+    return (readTokenExpiry(cfg.token) ??
+        cfg.expiresAt ??
+        Date.now() + DEFAULT_LIFETIME_MS);
+}
+export function LocationClientProvider({ children, getConfig, }) {
     const [client, setClient] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
-    // Refs hold live values without triggering re-renders
     const tokenRef = useRef(undefined);
     const expiresAtRef = useRef(null);
     const getConfigRef = useRef(getConfig);
     const refreshPromiseRef = useRef(null);
-    const ensureValidTokenRef = useRef(async () => { });
-    // Keep getConfig ref current without recreating callbacks
+    const timerRef = useRef(null);
+    const mountedRef = useRef(true);
     useEffect(() => {
         getConfigRef.current = getConfig;
     }, [getConfig]);
-    // Stable token getter — passed into GeoPlacesClient so it always reads the live ref
-    const getToken = useCallback(() => tokenRef.current, []);
-    // Returns true when the token is expired or within the refresh buffer window.
-    // Treats unknown expiry as expired so we always refresh on first use.
     const isTokenExpired = useCallback(() => {
         if (!expiresAtRef.current)
             return true;
-        return Date.now() >= expiresAtRef.current - refreshBuffer * 1000;
-    }, [refreshBuffer]);
-    // Refreshes the token exactly once even when called concurrently.
-    // All concurrent callers await the same in-flight promise — same pattern as
-    // server-side TokenProvider.tokenPromise deduplication.
-    const ensureValidToken = useCallback(async () => {
-        if (!isTokenExpired())
-            return;
-        // Deduplicate: if a refresh is already in flight, wait for it instead of firing another
-        if (refreshPromiseRef.current) {
-            log('Token refresh already in progress, waiting...');
+        return (Date.now() >= expiresAtRef.current - TOKEN_REFRESH_BUFFER_SECONDS * 1000);
+    }, []);
+    /**
+     * Refresh once, however many callers ask at the same moment.
+     *
+     * REJECTS on failure. It used to swallow the error into state and resolve,
+     * so `send` carried on with the token it already had — guaranteeing a 401 on
+     * the very next call and reporting it as an API error rather than a refresh
+     * failure.
+     */
+    const refreshToken = useCallback(async () => {
+        if (refreshPromiseRef.current)
             return refreshPromiseRef.current;
-        }
-        const timeUntilExpiry = expiresAtRef.current
-            ? Math.floor((expiresAtRef.current - Date.now()) / 1000)
-            : 0;
-        log('Token expired or expiring soon (in %ds), refreshing...', timeUntilExpiry);
         refreshPromiseRef.current = (async () => {
             const cfg = await getConfigRef.current();
             tokenRef.current = cfg.token;
-            expiresAtRef.current = cfg.expiresAt ?? Date.now() + 900000;
-            const newExpiry = Math.floor((expiresAtRef.current - Date.now()) / 1000);
-            log('Token refreshed (expires in %ds)', newExpiry);
+            expiresAtRef.current = expiryOf(cfg);
+            log('Token refreshed (expires in %ds)', Math.floor((expiresAtRef.current - Date.now()) / 1000));
+            if (mountedRef.current)
+                setError(null);
         })();
         try {
             await refreshPromiseRef.current;
+            scheduleRefreshRef.current();
         }
         catch (err) {
-            log('Token refresh failed: %s', err instanceof Error ? err.message : 'Unknown error');
-            setError(err instanceof Error ? err.message : 'Failed to refresh token');
+            const message = err instanceof Error ? err.message : 'Failed to refresh token';
+            log('Token refresh failed: %s', message);
+            if (mountedRef.current)
+                setError(message);
+            throw err;
         }
         finally {
             refreshPromiseRef.current = null;
         }
-    }, [isTokenExpired]);
-    // Keep ensureValidToken ref current so the send wrapper always uses the latest version
+    }, []);
+    /**
+     * Refresh AHEAD of expiry, on a timer.
+     *
+     * This is the whole fix for the map path. MapLibre's `transformRequest` is
+     * synchronous by contract, so `getToken` cannot await anything — the token it
+     * reads has to be valid already. Refresh used to happen only inside the `send`
+     * wrapper, which the map never calls: it requests tiles, glyphs and sprites
+     * directly. So after 15 minutes every map request failed, for as long as the
+     * page stayed open, and no amount of panning recovered it.
+     */
+    const scheduleRefresh = useCallback(() => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        if (!expiresAtRef.current)
+            return;
+        const delay = Math.max(0, expiresAtRef.current - TOKEN_REFRESH_BUFFER_SECONDS * 1000 - Date.now());
+        log('Next refresh in %ds', Math.floor(delay / 1000));
+        timerRef.current = setTimeout(() => {
+            // Errors are already surfaced onto state by refreshToken; swallow here so
+            // a failed background refresh cannot become an unhandled rejection.
+            void refreshToken().catch(() => { });
+        }, delay);
+    }, [refreshToken]);
+    // refreshToken and scheduleRefresh reference each other; a ref breaks the cycle
+    // without recreating either callback on every render.
+    const scheduleRefreshRef = useRef(() => { });
+    useEffect(() => {
+        scheduleRefreshRef.current = scheduleRefresh;
+    }, [scheduleRefresh]);
+    /**
+     * Synchronous read for the map path.
+     *
+     * If the token is already stale — a timer that never fired because the tab was
+     * backgrounded and throttled — this kicks off a refresh but cannot wait for it.
+     * The current read still returns the stale value; the point is that the NEXT
+     * one will not.
+     */
+    const getToken = useCallback(() => {
+        // `tokenRef.current` guards the pre-initialisation window: until the first
+        // config load lands there is no expiry to judge, and firing here would race
+        // the initial fetch and request a second token nobody asked for.
+        if (tokenRef.current && isTokenExpired() && !refreshPromiseRef.current) {
+            log('Stale token read — refreshing in the background');
+            void refreshToken().catch(() => { });
+        }
+        return tokenRef.current;
+    }, [isTokenExpired, refreshToken]);
+    const ensureValidToken = useCallback(async () => {
+        if (!isTokenExpired())
+            return;
+        await refreshToken();
+    }, [isTokenExpired, refreshToken]);
+    const ensureValidTokenRef = useRef(ensureValidToken);
     useEffect(() => {
         ensureValidTokenRef.current = ensureValidToken;
     }, [ensureValidToken]);
-    // Initial load — create the client once.
-    // getToken is passed as a callback so the client always reads the live token ref.
-    // ensureValidToken is called before each send so expiring tokens are refreshed
-    // transparently without recreating the client or causing re-renders.
+    /**
+     * A backgrounded tab has its timers throttled, so the scheduled refresh can be
+     * arbitrarily late. Refresh on the way back in, before the user touches the map.
+     */
     useEffect(() => {
+        if (typeof document === 'undefined')
+            return;
+        const onVisible = () => {
+            if (document.visibilityState === 'visible' &&
+                tokenRef.current &&
+                isTokenExpired()) {
+                log('Tab visible again with a stale token — refreshing');
+                void refreshToken().catch(() => { });
+            }
+        };
+        document.addEventListener('visibilitychange', onVisible);
+        return () => document.removeEventListener('visibilitychange', onVisible);
+    }, [isTokenExpired, refreshToken]);
+    useEffect(() => {
+        mountedRef.current = true;
         log('Initializing LocationClientProvider');
         getConfigRef
             .current()
             .then((cfg) => {
+            if (!mountedRef.current)
+                return;
             tokenRef.current = cfg.token;
-            expiresAtRef.current = cfg.expiresAt ?? Date.now() + 900000;
-            // GeoPlacesClient.send() calls getToken() synchronously for the token value,
-            // but token refresh is async. We create a thin send wrapper that:
-            // 1. awaits ensureValidToken (via ref — always latest, race-safe)
-            // 2. delegates to baseClient which reads the now-fresh token from getToken()
-            // The client instance is created once and never recreated on token refresh.
+            expiresAtRef.current = expiryOf(cfg);
             const baseClient = new GeoPlacesClient({
                 apiUrl: cfg.apiUrl,
                 token: cfg.token,
                 getToken,
             });
-            const wrappingClient = Object.create(baseClient);
-            wrappingClient.send = (async (command) => {
-                await ensureValidTokenRef.current();
-                return baseClient.send(command);
-            });
-            setClient(wrappingClient);
-            const expiry = Math.floor((expiresAtRef.current - Date.now()) / 1000);
-            log('Client initialized (token expires in %ds)', expiry);
+            // A plain object, not Object.create(baseClient): the prototype hack was
+            // opaque, and its `send` dropped the second argument entirely — so once
+            // the client gained `signal`/`timeoutMs`, every option passed through
+            // this provider would have been silently discarded.
+            const refreshing = {
+                config: baseClient.config,
+                async send(command, options) {
+                    await ensureValidTokenRef.current();
+                    return baseClient.send(command, options);
+                },
+            };
+            setClient(refreshing);
+            scheduleRefreshRef.current();
+            log('Client initialized (token expires in %ds)', Math.floor((expiresAtRef.current - Date.now()) / 1000));
             setLoading(false);
         })
             .catch((err) => {
-            log('Initialization failed: %s', err instanceof Error ? err.message : 'Unknown error');
-            setError(err instanceof Error ? err.message : 'Failed to initialize client');
+            if (!mountedRef.current)
+                return;
+            const message = err instanceof Error ? err.message : 'Failed to initialize client';
+            log('Initialization failed: %s', message);
+            setError(message);
             setLoading(false);
         });
+        return () => {
+            mountedRef.current = false;
+            if (timerRef.current)
+                clearTimeout(timerRef.current);
+        };
     }, [getToken]);
     return (_jsx(LocationClientContext.Provider, { value: { client, getToken, loading, error }, children: children }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client-react",
-  "version": "0.1.19",
+  "version": "0.3.0",
   "description": "React bindings for Chaosity Location Service client",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,7 @@
     "lint": "eslint . && prettier --check .",
     "lint:fix": "eslint --fix . && prettier --write .",
     "format": "prettier --write .",
-    "test": "vitest run --passWithNoTests",
+    "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build",
     "prepare": "husky"
@@ -34,7 +34,7 @@
     "url": "https://github.com/chaosity-io/location-service-client-react/issues"
   },
   "dependencies": {
-    "@chaosity/location-client": "^0.1.14",
+    "@chaosity/location-client": "^0.2.1",
     "debug": "^4.4.3"
   },
   "peerDependencies": {
@@ -54,7 +54,7 @@
     "@types/react": "^19.0.0",
     "@vitest/coverage-v8": "^3.0.0",
     "eslint": "^10.1.0",
-    "happy-dom": "^17.0.0",
+    "happy-dom": "^20.11.6",
     "husky": "^9.0.0",
     "maplibre-gl": "^5.0.0",
     "prettier": "^3.8.1",