feat: useMapsLibrary returns API object instead of boolean

BREAKING CHANGE: loading multiple libraries at once is no longer supported, changed the return type of useMapsLibrary.

src/components/__tests__/api-provider.test.tsx

@@ -3,14 +3,17 @@ import {act, render, screen} from '@testing-library/react';
 import {initialize} from '@googlemaps/jest-mocks';
 import '@testing-library/jest-dom';
 
+// FIXME: this should no longer be needed with the next version of @googlemaps/jest-mocks
+import {importLibraryMock} from '../../libraries/__mocks__/lib/import-library-mock';
+
 import {
   APILoadingStatus,
   APIProvider,
   APIProviderContext,
   APIProviderContextValue
 } from '../api-provider';
 import {ApiParams} from '../../libraries/google-maps-api-loader';
-import {useApiIsLoaded} from '../../hooks/api-loading-status';
+import {useApiIsLoaded} from '../../hooks/use-api-is-loaded';
 
 const apiLoadSpy = jest.fn();
 const apiUnloadSpy = jest.fn();
@@ -29,6 +32,7 @@ jest.mock('../../libraries/google-maps-api-loader', () => {
   class GoogleMapsApiLoader {
     static async load(params: ApiParams): Promise<void> {
       apiLoadSpy(params);
+      google.maps.importLibrary = importLibraryMock;
       return new Promise(resolve => (triggerMapsApiLoaded = resolve));
     }
     static unload() {

src/components/__tests__/map.test.tsx

@@ -24,7 +24,7 @@ beforeEach(() => {
 
   mockContextValue = {
     importLibrary: jest.fn(),
-    loadedLibraries: new Set(),
+    loadedLibraries: {},
     status: APILoadingStatus.LOADED,
     mapInstances: {},
     addMapInstance: jest.fn(),

src/components/advanced-marker.tsx

@@ -13,7 +13,7 @@ import {createPortal} from 'react-dom';
 import {GoogleMapsContext} from './map';
 
 import type {Ref, PropsWithChildren} from 'react';
-import {useMapsLibrary} from '../hooks/api-loading-status';
+import {useMapsLibrary} from '../hooks/use-maps-library';
 
 export interface AdvancedMarkerContextValue {
   marker: google.maps.marker.AdvancedMarkerElement;

src/components/api-provider.tsx

@@ -4,6 +4,7 @@ import React, {
   useCallback,
   useEffect,
   useMemo,
+  useReducer,
   useState
 } from 'react';
 
@@ -18,12 +19,13 @@ export enum APILoadingStatus {
 
 const {NOT_LOADED, LOADING, LOADED, FAILED} = APILoadingStatus;
 
-/**
- * API Provider context
- */
+type ImportLibraryFunction = typeof google.maps.importLibrary;
+type GoogleMapsLibrary = Awaited<ReturnType<ImportLibraryFunction>>;
+type LoadedLibraries = {[name: string]: GoogleMapsLibrary};
+
 export interface APIProviderContextValue {
   status: APILoadingStatus;
-  loadedLibraries: Set<string>;
+  loadedLibraries: LoadedLibraries;
   importLibrary: typeof google.maps.importLibrary;
   mapInstances: Record<string, google.maps.Map>;
   addMapInstance: (map: google.maps.Map, id?: string) => void;
@@ -106,8 +108,14 @@ function useGoogleMapsApiLoader(props: APIProviderProps) {
   const {onLoad, apiKey, libraries = [], ...otherApiParams} = props;
 
   const [status, setStatus] = useState<APILoadingStatus>(NOT_LOADED);
-  const [loadedLibraries, setLoadedLibraries] = useState<Set<string>>(
-    new Set()
+  const [loadedLibraries, addLoadedLibrary] = useReducer(
+    (
+      loadedLibraries: LoadedLibraries,
+      action: {name: keyof LoadedLibraries; value: LoadedLibraries[string]}
+    ) => {
+      return {...loadedLibraries, [action.name]: action.value};
+    },
+    {}
   );
 
   const librariesString = useMemo(() => libraries?.join(','), [libraries]);
@@ -116,6 +124,27 @@ function useGoogleMapsApiLoader(props: APIProviderProps) {
     [otherApiParams]
   );
 
+  const importLibrary: typeof google.maps.importLibrary = useCallback(
+    async (name: string) => {
+      if (loadedLibraries[name]) {
+        return loadedLibraries[name];
+      }
+
+      if (!google?.maps?.importLibrary) {
+        throw new Error(
+          '[api-provider-internal] importLibrary was called before ' +
+            'google.maps.importLibrary was defined.'
+        );
+      }
+
+      const res = await window.google.maps.importLibrary(name);
+      addLoadedLibrary({name, value: res});
+
+      return res;
+    },
+    []
+  );
+
   useEffect(
     () => {
       setStatus(LOADING);
@@ -129,7 +158,10 @@ function useGoogleMapsApiLoader(props: APIProviderProps) {
           });
 
           setStatus(LOADED);
-          setLoadedLibraries(new Set(['maps', ...libraries]));
+
+          for (const name of ['core', 'maps', ...libraries]) {
+            await importLibrary(name);
+          }
 
           if (onLoad) {
             onLoad();
@@ -144,22 +176,6 @@ function useGoogleMapsApiLoader(props: APIProviderProps) {
     [apiKey, librariesString, serializedParams]
   );
 
-  const importLibrary: typeof google.maps.importLibrary = useCallback(
-    async (name: string) => {
-      if (!google?.maps?.importLibrary) {
-        throw new Error(
-          'importLibrary was called before google.maps.importLibrary was defined'
-        );
-      }
-
-      const res = await window.google.maps.importLibrary(name);
-      setLoadedLibraries(new Set([...loadedLibraries, name]));
-
-      return res;
-    },
-    []
-  );
-
   return {
     status,
     loadedLibraries,

src/components/map.tsx

@@ -12,7 +12,7 @@ import React, {
 
 import {APIProviderContext, APIProviderContextValue} from './api-provider';
 
-import {useApiIsLoaded} from '../hooks/api-loading-status';
+import {useApiIsLoaded} from '../hooks/use-api-is-loaded';
 import {logErrorOnce} from '../libraries/errors';
 
 // Google Maps context

src/hooks/__tests__/api-loading-status.test.tsx → src/hooks/__tests__/api-loading.test.tsx

@@ -7,7 +7,9 @@ import {
   APIProviderContext,
   APIProviderContextValue
 } from '../../components/api-provider';
-import {useApiIsLoaded, useApiLoadingStatus} from '../api-loading-status';
+
+import {useApiLoadingStatus} from '../use-api-loading-status';
+import {useApiIsLoaded} from '../use-api-is-loaded';
 
 let wrapper: ({children}: {children: React.ReactNode}) => JSX.Element | null;
 let mockContextValue: jest.MockedObject<APIProviderContextValue>;
@@ -16,7 +18,7 @@ beforeEach(() => {
 
   mockContextValue = {
     importLibrary: jest.fn(),
-    loadedLibraries: new Set(),
+    loadedLibraries: {},
     status: APILoadingStatus.LOADED,
     mapInstances: {},
     addMapInstance: jest.fn(),

src/hooks/__tests__/map-instance.test.tsx → src/hooks/__tests__/use-map.test.tsx

@@ -3,7 +3,7 @@ import '@testing-library/jest-dom';
 import {renderHook} from '@testing-library/react';
 import {initialize, mockInstances} from '@googlemaps/jest-mocks';
 
-import {useMap} from '../map-instance';
+import {useMap} from '../use-map';
 import {
   APILoadingStatus,
   APIProviderContext,
@@ -28,7 +28,7 @@ beforeEach(() => {
 
   mockContextValue = {
     importLibrary: jest.fn(),
-    loadedLibraries: new Set(),
+    loadedLibraries: {},
     status: APILoadingStatus.LOADED,
     mapInstances: {},
     addMapInstance: jest.fn(),

src/hooks/autocomplete.ts

@@ -1,6 +1,6 @@
 import {useState, useRef, useEffect} from 'react';
 
-import {useApiIsLoaded} from './api-loading-status';
+import {useApiIsLoaded} from './use-api-is-loaded';
 
 export interface AutocompleteProps {
   inputField: HTMLInputElement | null;

src/hooks/directions-service.ts

@@ -1,7 +1,7 @@
 import {useMemo, useEffect, useCallback} from 'react';
 
-import {useApiIsLoaded} from './api-loading-status';
-import {useMap} from './map-instance';
+import {useApiIsLoaded} from './use-api-is-loaded';
+import {useMap} from './use-map';
 import {assertNotNull} from '../libraries/assert-not-null';
 
 export interface DirectionsServiceHookOptions {

src/hooks/street-view-panorama.ts

@@ -1,7 +1,7 @@
 /* eslint-disable complexity */
 import {useEffect, useState} from 'react';
-import {useApiIsLoaded} from './api-loading-status';
-import {useMap} from './map-instance';
+import {useApiIsLoaded} from './use-api-is-loaded';
+import {useMap} from './use-map';
 
 export interface StreetViewPanoramaProps {
   mapId?: string;

src/hooks/use-api-is-loaded.ts

@@ -0,0 +1,10 @@
+import {APILoadingStatus} from '../components/api-provider';
+import {useApiLoadingStatus} from './use-api-loading-status';
+/**
+ * Hook to check if the Google Maps API is loaded
+ */
+export function useApiIsLoaded(): boolean {
+  const status = useApiLoadingStatus();
+
+  return status === APILoadingStatus.LOADED;
+}

src/hooks/use-api-loading-status.ts

@@ -0,0 +1,6 @@
+import {useContext} from 'react';
+import {APILoadingStatus, APIProviderContext} from '../components/api-provider';
+
+export function useApiLoadingStatus(): APILoadingStatus {
+  return useContext(APIProviderContext)?.status || APILoadingStatus.NOT_LOADED;
+}

src/hooks/use-maps-library.ts

@@ -0,0 +1,40 @@
+import {useContext, useEffect} from 'react';
+
+import {APIProviderContext} from '../components/api-provider';
+import {useApiIsLoaded} from './use-api-is-loaded';
+
+interface ApiLibraries {
+  core: google.maps.CoreLibrary;
+  maps: google.maps.MapsLibrary;
+  places: google.maps.PlacesLibrary;
+  geocoding: google.maps.GeocodingLibrary;
+  routes: google.maps.RoutesLibrary;
+  marker: google.maps.MarkerLibrary;
+  geometry: google.maps.GeometryLibrary;
+  elevation: google.maps.ElevationLibrary;
+  streetView: google.maps.StreetViewLibrary;
+  journeySharing: google.maps.JourneySharingLibrary;
+  drawing: google.maps.DrawingLibrary;
+  visualization: google.maps.VisualizationLibrary;
+}
+
+export function useMapsLibrary<
+  K extends keyof ApiLibraries,
+  V extends ApiLibraries[K]
+>(name: K): V | null;
+
+export function useMapsLibrary(name: string) {
+  const apiIsLoaded = useApiIsLoaded();
+  const ctx = useContext(APIProviderContext);
+
+  useEffect(() => {
+    if (!apiIsLoaded || !ctx) return;
+
+    // Trigger loading the libraries via our proxy-method.
+    // The returned promise is ignored, since importLibrary will update loadedLibraries
+    // list in the context, triggering a re-render.
+    void ctx.importLibrary(name);
+  }, [apiIsLoaded, ctx?.importLibrary]);
+
+  return ctx?.loadedLibraries[name] || null;
+}

src/index.ts

@@ -4,9 +4,12 @@ export * from './components/info-window';
 export * from './components/map';
 export * from './components/marker';
 export * from './components/pin';
-export * from './hooks/api-loading-status';
+export * from './hooks/use-api-loading-status';
+export * from './hooks/use-api-is-loaded';
+export * from './hooks/use-maps-library';
+export * from './hooks/use-map';
 export * from './hooks/autocomplete';
 export * from './hooks/directions-service';
-export * from './hooks/map-instance';
 export * from './hooks/street-view-panorama';
+
 export {limitTiltRange} from './libraries/limit-tilt-range';

src/libraries/__mocks__/google-maps-api-loader.ts

@@ -1,5 +1,11 @@
 import type {GoogleMapsApiLoader as ActualLoader} from '../google-maps-api-loader';
 
+// FIXME: this should no longer be needed with the next version of @googlemaps/jest-mocks
+import {importLibraryMock} from './lib/import-library-mock';
+
 export class GoogleMapsApiLoader {
-  static load: typeof ActualLoader.load = jest.fn(() => Promise.resolve());
+  static load: typeof ActualLoader.load = jest.fn(() => {
+    google.maps.importLibrary = importLibraryMock;
+    return Promise.resolve();
+  });
 }