fix(v3): improve types, interfaces and composables

We also improve some function descriptions and we update all dependencies to its latest versions

packages/v3/package.json

@@ -4,7 +4,7 @@
   "description": "This is a google map component for Vue.js, updated for Vue 2 compatibility",
   "main": "dist/main.umd.js",
   "module": "dist/main.es.js",
-  "typings": "dist/types/src/main.d.ts",
+  "typings": "dist/types",
   "unpkg": "dist/main.umd.js",
   "jsdelivr": "dist/main.umd.js",
   "browser": {
@@ -14,6 +14,25 @@
     "node": ">=12",
     "npm": ">6"
   },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/src/main.d.ts",
+        "default": "./dist/main.es.js"
+      },
+      "require": {
+        "types": "./dist/types/src/main.d.ts",
+        "default": "./dist/main.umd.js"
+      },
+      "default": {
+        "types": "./dist/types/src/main.d.ts",
+        "default": "./dist/main.es.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -40,16 +59,6 @@
     "copy:components": "cpx \"./src/components/*.vue\" \"./dist/components\" --verbose",
     "release": "semantic-release"
   },
-  "exports": {
-    ".": {
-      "import": "./dist/main.es.js",
-      "require": "./dist/main.umd.js",
-      "default": "./dist/main.es.js"
-    }
-  },
-  "files": [
-    "dist"
-  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/diegoazh/gmap-vue.git"
@@ -59,10 +68,10 @@
   },
   "homepage": "https://github.com/diegoazh/gmap-vue#readme",
   "dependencies": {
-    "@googlemaps/markerclusterer": "^2.1.4",
+    "@googlemaps/markerclusterer": "^2.5.3",
     "lodash.isequal": "^4.5.0",
-    "mitt": "^3.0.0",
-    "vue": "^3.3.4"
+    "mitt": "^3.0.1",
+    "vue": "^3.4.21"
   },
   "devDependencies": {
     "@rushstack/eslint-patch": "^1.3.0",

packages/v3/src/composables/helpers.ts

@@ -1,4 +1,4 @@
-import type { IPluginOptions, IVueProp } from '@/interfaces';
+import type { IGmapVuePluginOptions, IVueProp } from '@/interfaces';
 import type {
   GmapVuePluginProps,
   LazyValueGetterFn,
@@ -63,11 +63,13 @@ export function getPropsValuesWithoutOptionsProp(
  *
  * @internal
  */
-export function getLazyValue(fn: () => Promise<any>): LazyValueGetterFn {
+export function getLazyValue<T>(
+  fn: LazyValueGetterFn<T>
+): LazyValueGetterFn<T> {
   let called = false;
-  let ret: Promise<any>;
+  let ret: Promise<T>;
 
-  return (): Promise<any> => {
+  return (): Promise<T> => {
     if (!called) {
       called = true;
       ret = fn();
@@ -351,7 +353,7 @@ export function watchPrimitivePropertiesOnSetup(
 export function bindEvents(
   eventsConfig: string[],
   googleMapsInst: Record<string, any>,
-  vueInst: ComponentPublicInstance & { $gmapOptions: IPluginOptions },
+  vueInst: ComponentPublicInstance & { $gmapOptions: IGmapVuePluginOptions },
   excludedEvents: string[] = []
 ): void {
   eventsConfig.forEach((eventName) => {
@@ -382,7 +384,7 @@ export function bindEvents(
 export function bindProps(
   propsComponentConfig: Omit<SinglePluginComponentConfig, 'events'>,
   AnyGoogleMapsClassInstance: Record<string, any>,
-  vueInst: ComponentPublicInstance & { $gmapOptions: IPluginOptions }
+  vueInst: ComponentPublicInstance & { $gmapOptions: IGmapVuePluginOptions }
 ): void {
   Object.entries(vueInst.$props).forEach(([propKey, propValue]) => {
     if (!propsComponentConfig.noBind.includes(propKey)) {

packages/v3/src/composables/index.ts

@@ -1,6 +1,9 @@
 import type { GmvSharedComposables } from '../types';
 import { useMapPromise } from './map-promise';
-import { useGoogleMapsApiPromiseLazy } from './promise-lazy-builder';
+import {
+  useGoogleMapsApiPromiseLazy,
+  usePluginOptions,
+} from './promise-lazy-builder';
 import { useResizeBus } from './resize-bus';
 import { useStreetViewPanoramaPromise } from './street-view-panorama-promise';
 
@@ -28,4 +31,5 @@ export const sharedComposables: GmvSharedComposables = {
   useResizeBus,
   useGoogleMapsApiPromiseLazy,
   useStreetViewPanoramaPromise,
+  usePluginOptions,
 };

packages/v3/src/composables/promise-lazy-builder.ts

@@ -1,4 +1,4 @@
-import type { IGoogleMapsApiObject, IPluginOptions } from '@/interfaces';
+import type { IGoogleMapsApiObject, IGmapVuePluginOptions } from '@/interfaces';
 import type {
   GlobalGoogleObject,
   GoogleMapsAPIInitializerFn,
@@ -7,8 +7,8 @@ import type {
 } from '@/types';
 import { getLazyValue } from './helpers';
 
-let $finalOptions: IPluginOptions;
-let $googleMapsApiPromiseLazy: LazyValueGetterFn;
+let $finalOptions: IGmapVuePluginOptions;
+let $googleMapsApiPromiseLazy: LazyValueGetterFn<GlobalGoogleObject>;
 
 /**
  * This function is a factory of the promise lazy creator
@@ -17,15 +17,17 @@ let $googleMapsApiPromiseLazy: LazyValueGetterFn;
  *
  * @param  {Function} googleMapsApiInitializer function that initialize the Google Maps API
  * @param  {Object} GoogleMapsApi Vue app instance that will help to know if the Google API object is ready
- * @returns {(options: IPluginOptions) => LazyValueGetterFn}
+ * @returns {(options: IGmapVuePluginOptions) => LazyValueGetterFn}
  *
  * @internal
  */
 export function usePromiseLazyBuilderFn(
   googleMapsApiInitializer: GoogleMapsAPIInitializerFn,
   GoogleMapsApi: IGoogleMapsApiObject
 ): PromiseLazyCreatorFn {
-  return (options: IPluginOptions): LazyValueGetterFn => {
+  return (
+    options: IGmapVuePluginOptions
+  ): LazyValueGetterFn<GlobalGoogleObject> => {
     /**
      * Things to do once the API is loaded
      *
@@ -71,7 +73,7 @@ function createCallbackAndChecksIfMapIsLoaded(resolveFn: Function): void {
 
       if (window?.google?.maps != null && !callbackExecuted) {
         globalThis.GoogleMapsCallback();
-        callbackExecuted = true;
+        callbackExecuted = true; // TODO: check this, is possible it can be removed. Assigned in the callback function.
       }
 
       if (callbackExecuted) {
@@ -87,14 +89,14 @@ function createCallbackAndChecksIfMapIsLoaded(resolveFn: Function): void {
  * and helps to define if the plugin should load
  * the Google Maps API or not
  *
- * @param  {IPluginOptions} options
+ * @param  {IGmapVuePluginOptions} options
  * @param  {GoogleMapsAPIInitializerFn} googleMapsApiInitializer
  * @param  {()=>GlobalGoogleObject} onMapsReady
  *
  * @internal
  */
 function createFinalPromise(
-  options: IPluginOptions,
+  options: IGmapVuePluginOptions,
   googleMapsApiInitializer: GoogleMapsAPIInitializerFn,
   onMapsReady: () => GlobalGoogleObject
 ): Promise<GlobalGoogleObject> {
@@ -121,15 +123,15 @@ function createFinalPromise(
  * the function to get the promise useful to wait until the Google Maps API
  * is loaded and ready to use it
  *
- * @param  {IPluginOptions} finalOptions
+ * @param  {IGmapVuePluginOptions} finalOptions
  * @param  {LazyValueGetterFn} googleMapsApiPromiseLazy
  * @returns void
  *
  * @internal
  */
 export function saveLazyPromiseAndFinalOptions(
-  finalOptions: IPluginOptions,
-  googleMapsApiPromiseLazy: LazyValueGetterFn
+  finalOptions: IGmapVuePluginOptions,
+  googleMapsApiPromiseLazy: LazyValueGetterFn<GlobalGoogleObject>
 ): void {
   if (!$finalOptions) {
     $finalOptions = finalOptions;
@@ -148,7 +150,9 @@ export function saveLazyPromiseAndFinalOptions(
  * @public
  * @returns {Promise<any>}
  */
-export function useGoogleMapsApiPromiseLazy(): Promise<any> {
+export function useGoogleMapsApiPromiseLazy(): Promise<
+  GlobalGoogleObject | undefined
+> {
   if (!$googleMapsApiPromiseLazy) {
     globalThis.console.warn('$googleMapsApiPromiseLazy was not created yet...');
   }
@@ -161,7 +165,7 @@ export function useGoogleMapsApiPromiseLazy(): Promise<any> {
  *
  * @returns IPluginOptions
  */
-export function usePluginOptions(): IPluginOptions {
+export function usePluginOptions(): IGmapVuePluginOptions {
   if (!$finalOptions) {
     globalThis.console.warn('$finalOptions was not defined yet...');
   }

packages/v3/src/interfaces/gmap-vue.interface.ts

@@ -19,12 +19,12 @@ export interface IGoogleMapsApiObject {
  * @property {string} key - The Google Maps key
  * @property {string} libraries - The Google Maps libraries that should be loaded
  * @property {string?} v - The Google Maps version that should be loaded
- * @property {string?} callback - The callback name that should be called when Google Maps is ready
- * @property {string?} customCallback - The custom callback name that should be called when Google Maps is ready this overrides the callback property
+ * @property {string?} callback - The callback name that should be called when Google Maps is ready, if you set this do not forget to call `globalThis.GoogleMapsCallback` function in your callback
+ * @property {string?} customCallback - The custom callback name that should be called when Google Maps is ready this overrides the callback property [DEPRECATED]
  */
 export interface ILoadPluginOptions {
-  key: string;
-  libraries: string;
+  key?: string;
+  libraries?: string;
   v?: string;
   callback?: string;
   customCallback?: string;
@@ -37,13 +37,13 @@ export interface ILoadPluginOptions {
  * The object which contain all event names to and params that should be used to add listener to the Google Maps instance
  * @public
  * @typedef {object} PluginOptions - The options required to configure the plugin
- * @property {boolean} [dynamicLoad=false] - The plugin should be loaded dynamically
+ * @property {boolean} [dynamicLoad=false] - The plugin should be loaded dynamically, if you set this to `true` the plugin doesn't load the Google Maps API
  * @property {boolean} [installComponents=true] - The plugin should install all components
  * @property {LoadPluginOptions} [load] - All load plugin options
  * @property {boolean} [loadCn=false] - The plugin should be loaded using the cn url
  * @property {ExcludeEvents} [excludeEventsOnAllComponents] - A function that should return an array of events that should not be fired
  */
-export interface IPluginOptions {
+export interface IGmapVuePluginOptions {
   dynamicLoad?: boolean;
   installComponents?: boolean;
   load?: ILoadPluginOptions;

packages/v3/src/main.ts

@@ -18,13 +18,12 @@ import {
   pluginComponentBuilder,
   saveLazyPromiseAndFinalOptions,
   sharedComposables,
-  useDefaultResizeBus,
   usePromiseLazyBuilderFn,
 } from '@/composables';
-import type { IGoogleMapsApiObject, IPluginOptions } from '@/interfaces';
+import type { IGmapVuePluginOptions, IGoogleMapsApiObject } from '@/interfaces';
 import type { GlobalGoogleObject, GmvComponents, GmvUtilities } from '@/types';
 import type { Emitter, EventType } from 'mitt';
-import type { App, Plugin } from 'vue';
+import type { App, FunctionPlugin, Plugin } from 'vue';
 
 /**
  * Vue augmentations
@@ -33,7 +32,7 @@ declare module 'vue' {
   interface ComponentCustomProperties {
     $gmapDefaultResizeBus: Emitter<Record<EventType, unknown>>;
     $gmapApiPromiseLazy: () => Promise<any>;
-    $gmapOptions: IPluginOptions;
+    $gmapOptions: IGmapVuePluginOptions;
   }
 }
 
@@ -78,7 +77,7 @@ globalThis.GoogleMapsApi = { isReady: false };
  * when its ready on the window object
  * @function
  */
-function getGoogleMapsAPI(): false | typeof google {
+function getGoogleMapsAPI(): false | GlobalGoogleObject {
   return globalThis.GoogleMapsApi.isReady && globalThis.google;
 }
 
@@ -136,11 +135,14 @@ const utilities: GmvUtilities = {
  * GmapVue install function
  *
  * @param  {Object} app the vue app instance
- * @param  {PluginOptions} [options] configuration object to initialize the GmapVue plugin
+ * @param  {IGmapVuePluginOptions} [options] configuration object to initialize the GmapVue plugin
  */
-function pluginInstallFn(app: App, options?: IPluginOptions): void {
+const pluginInstallFn: FunctionPlugin<IGmapVuePluginOptions> = (
+  app: App,
+  options?: IGmapVuePluginOptions
+): void => {
   // see defaults
-  const finalOptions: IPluginOptions = {
+  const finalOptions: IGmapVuePluginOptions = {
     dynamicLoad: false,
     installComponents: true,
     ...options,
@@ -175,11 +177,9 @@ function pluginInstallFn(app: App, options?: IPluginOptions): void {
    *
    * These properties are the same references that you can find in the instance,
    * but they are static because they are attached to the main Vue object.
-   * app.config.globalProperties.$gmapDefaultResizeBus - function to use the default resize bus
    * app.config.globalProperties.$googleMapsApiPromiseLazy - function that you can use to wait until Google Maps API is ready
    * app.config.globalProperties.$gmapOptions - object with the final options passed to Google Maps API to configure it
    */
-  app.config.globalProperties.$gmapDefaultResizeBus = useDefaultResizeBus();
   app.config.globalProperties.$gmapApiPromiseLazy = googleMapsApiPromiseLazy;
   app.config.globalProperties.$gmapOptions = finalOptions;
 
@@ -198,17 +198,19 @@ function pluginInstallFn(app: App, options?: IPluginOptions): void {
       .component('GmvRectangle', Rectangle)
       .component('GmvDrawingManager', DrawingManager);
   }
-}
+};
 
 /**
  * Export the default Vue object for plugins
  * Export for ESM modules
  *
  * @see pluginInstallFn
  * @type GmapVue
- * @property {Function} install function to install the plugin
+ * @property {FunctionPlugin} install function to install the plugin
  */
-const GmapVuePlugin: Plugin = { install: pluginInstallFn };
+const GmapVuePlugin: Plugin<IGmapVuePluginOptions> = {
+  install: pluginInstallFn,
+};
 
 export {
   GmapVuePlugin,

packages/v3/src/types/gmap-vue.type.ts

@@ -17,7 +17,7 @@ import type {
   IGmapVueElementOptions,
   IGoogleMapProp,
   ILoadPluginOptions,
-  IPluginOptions,
+  IGmapVuePluginOptions,
   IVueProp,
 } from '@/interfaces';
 import type { Emitter, EventType } from 'mitt';
@@ -75,20 +75,20 @@ export type PluginComponentConfig = {
 };
 
 /** @internal */
-export type GlobalGoogleObject = { [key: string]: any };
+export type GlobalGoogleObject = typeof google;
 
 export type GoogleMapsAPIInitializerFn = (
   options: ILoadPluginOptions,
   loadCn?: boolean
 ) => void;
 
 /** @internal */
-export type LazyValueGetterFn = () => Promise<any>;
+export type LazyValueGetterFn<T> = () => Promise<T>;
 
 /** @internal */
 export type PromiseLazyCreatorFn = (
-  options: IPluginOptions
-) => LazyValueGetterFn;
+  options: IGmapVuePluginOptions
+) => LazyValueGetterFn<GlobalGoogleObject>;
 
 /** @internal */
 export type OldHtmlInputElement = HTMLInputElement & {
@@ -125,12 +125,13 @@ export type GmvSharedComposables = {
   useStreetViewPanoramaPromise: () => Promise<
     google.maps.StreetViewPanorama | undefined
   >;
+  usePluginOptions: () => IGmapVuePluginOptions;
 };
 
 export type GmvUtilities = {
   googleMapsApiInitializer: GoogleMapsAPIInitializerFn;
   pluginComponentBuilder: (
     providedOptions: IGmapVueElementOptions
   ) => ComponentOptions;
-  getGoogleMapsAPI: () => false | typeof google;
+  getGoogleMapsAPI: () => false | GlobalGoogleObject;
 };