Refine JSDoc / TypeScript types for plugins

DavidWells · Oct 7, 2022 · eea7d2f · eea7d2f
1 parent 6dad612
commit eea7d2f
Show file tree

Hide file tree

Showing 4 changed files with 87 additions and 17 deletions.
diff --git a/packages/analytics-core/src/index.js b/packages/analytics-core/src/index.js
@@ -62,7 +62,7 @@ function analytics(config = {}) {
   // if (SERVER) {
   //   console.log('INIT SERVER')
   // }
-  
+
   /* Parse plugins array */
   const parsedOptions = (config.plugins || []).reduce((acc, plugin) => {
     if (isFunction(plugin)) {
@@ -125,7 +125,7 @@ function analytics(config = {}) {
     middlewares: [],
     events: []
   })
-  
+
   /* Storage by default is set to global & is not persisted */
   const storage = (config.storage) ? config.storage : {
     getItem: get,
@@ -160,7 +160,7 @@ function analytics(config = {}) {
     // throw new Error(`${ERROR_URL}3`)
     throw new Error('Abort disabled inListener')
   }
-  
+
   // Parse URL parameters
   const params = paramsParse()
   // Initialize visitor information
@@ -177,8 +177,8 @@ function analytics(config = {}) {
   }
 
   /**
-   * Async Management methods for plugins. 
-   * 
+   * Async Management methods for plugins.
+   *
    * This is also where [custom methods](https://bit.ly/329vFXy) are loaded into the instance.
    * @typedef {Object} Plugins
    * @property {EnablePlugin} enable - Set storage value
@@ -275,7 +275,7 @@ function analytics(config = {}) {
     // Merge in custom plugin methods
     ...parsedOptions.methods
   }
-  
+
   let readyCalled = false
   /**
    * Analytic instance returned from initialization
@@ -289,7 +289,7 @@ function analytics(config = {}) {
    * @property {On} on - Fire callback on analytics lifecycle events.
    * @property {Once} once - Fire callback on analytics lifecycle events once.
    * @property {GetState} getState - Get data about user, activity, or context.
-   * @property {Storage} storage - storage methods
+   * @property {AnalyticsStorage} storage - storage methods
    * @property {Plugins} plugins - plugin methods
    */
   const instance = {
@@ -363,7 +363,7 @@ function analytics(config = {}) {
      * Track an analytics event. This will trigger `track` calls in any installed plugins
      * @typedef {Function} Track
      * @param  {String}   eventName - Event name
-     * @param  {Object}   [payload]   - Event payload
+     * @param  {TrackData}   [payload]   - Event payload
      * @param  {Object}   [options]   - Event options
      * @param  {Function} [callback]  - Callback to fire after tracking completes
      * @returns {Promise}
@@ -733,7 +733,7 @@ function analytics(config = {}) {
     /**
      * Storage utilities for persisting data.
      * These methods will allow you to save data in localStorage, cookies, or to the window.
-     * @typedef {Object} Storage
+     * @typedef {Object} AnalyticsStorage
      * @property {GetItem} getItem - Get value from storage
      * @property {SetItem} setItem - Set storage value
      * @property {RemoveItem} removeItem - Remove storage value
@@ -887,7 +887,7 @@ function analytics(config = {}) {
     }
     return acc
   }, {})
-  
+
   const initialState = {
     context: initialConfig,
     user: visitorInfo,
@@ -941,7 +941,7 @@ function analytics(config = {}) {
 
   const enabledPlugins = pluginKeys.filter((name) => parsedOptions.pluginEnabled[name])
   const disabledPlugins = pluginKeys.filter((name) => !parsedOptions.pluginEnabled[name])
- 
+
   /* Register analytic plugins */
   store.dispatch({
     type: EVENTS.registerPlugins,

diff --git a/packages/analytics-core/src/modules/page.js b/packages/analytics-core/src/modules/page.js
@@ -35,7 +35,7 @@ function currentUrl(search) {
 }
 
 /**
- * Page data for overides
+ * Page data for overrides
  * @typedef {object} PageData
  * @property {string} [title] - Page title
  * @property {string} [url] - Page url

diff --git a/packages/analytics-core/src/modules/track.js b/packages/analytics-core/src/modules/track.js
@@ -2,6 +2,17 @@
 import EVENTS from '../events'
 import serialize from '../utils/serialize'
 
+
+/**
+ * Track data for overrides
+ * @typedef {Object} TrackData
+ * @property {string} [hitType] (Google Analytics) https://bit.ly/2Jab9L1 one of 'pageview', 'screenview', 'event', 'transaction', 'item', 'social', 'exception', 'timing'
+ * @property {string} [label] (Google Analytics) event Label http://bit.ly/2oo8eb3
+ * @property {number} [value] (Google Analytics) event value
+ * @property {string} [category] (Google Analytics) event Category http://bit.ly/2EAy9UP
+ * @property {boolean} [nonInteraction] (Google Analytics) https://bit.ly/2CUzeoz
+ */
+
 // Track State
 const initialState = {
   last: {},

diff --git a/packages/analytics-core/src/pluginTypeDef.js b/packages/analytics-core/src/pluginTypeDef.js
@@ -1,12 +1,71 @@
+/**
+ * @callback PluginTrackFunction
+ * @param {Object} arg
+ * @param {Object} arg.config config from the plugin spec
+ * @param {AnalyticsInstance} arg.instance analytics instance
+ * @param {Object} arg.payload event data
+ * @param {string} arg.payload.event event name passed to track
+ * @param {TrackData} arg.payload.properties event properties passed to track
+ * @return {void}
+ */
+
+/**
+ * @callback PluginPageFunction
+ * @param {Object} arg
+ * @param {Object} arg.config config from the plugin spec
+ * @param {AnalyticsInstance} arg.instance analytics instance
+ * @param {Object} arg.payload
+ * @param {string} arg.payload.event
+ * @param {PageData} arg.payload.properties
+ * @return {void}
+ */
+
+/**
+ * @callback PluginIdentifyFunction
+ * @param {Object} arg
+ * @param {Object} arg.config config from the plugin spec
+ * @param {AnalyticsInstance} arg.instance analytics instance
+ * @param {Object} arg.payload
+ * @param {string} arg.payload.event
+ * @param {PageData} arg.payload.properties
+ * @return {void}
+ */
+
+/**
+ * @callback PluginInitializeFunction
+ * @param {Object} arg
+ * @param {Object} arg.config config from the plugin spec
+ * @param {AnalyticsInstance} arg.instance analytics instance
+ * @param {Object} arg.payload
+ * @return boolean
+ */
+
+/**
+ * @callback PluginLoadedFunction
+ * @param {Object} arg
+ * @param {Object} arg.config config from the plugin spec
+ * @param {AnalyticsInstance} arg.instance analytics instance
+ * @param {Object} arg.payload
+ * @return boolean
+ */
+
+/**
+ * @callback PluginReadyFunction
+ * @param {Object} arg
+ * @param {Object} arg.config config from the plugin spec
+ * @param {AnalyticsInstance} arg.instance analytics instance
+ * @return void
+ */
+
 /**
   * @typedef {Object} AnalyticsPlugin
   * @property {string} name - Name of plugin
   * @property {Object} [EVENTS] - exposed events of plugin
   * @property {Object} [config] - Configuration of plugin
   * @property {function} [initialize] - Load analytics scripts method
-  * @property {function} [page] - Page visit tracking method
-  * @property {function} [track] - Custom event tracking method
-  * @property {function} [identify] - User identify method
-  * @property {function} [loaded] - Function to determine if analytics script loaded
-  * @property {function} [ready] - Fire function when plugin ready
+  * @property {PluginPageFunction} [page] - Page visit tracking method
+  * @property {PluginTrackFunction} [track] - Custom event tracking method
+  * @property {PluginIdentifyFunction} [identify] - User identify method
+  * @property {PluginLoadedFunction} [loaded] - Function to determine if analytics script loaded
+  * @property {PluginReadyFunction} [ready] - Fire function when plugin ready
   */