From 1c26a4003d72eedd50b60244f46ce93410e4d8a6 Mon Sep 17 00:00:00 2001 From: Dobes Vandermeer Date: Fri, 7 Oct 2022 15:34:39 -0700 Subject: [PATCH] Refine JSDoc / TypeScript types for plugins --- packages/analytics-core/src/index.js | 20 +++--- packages/analytics-core/src/modules/page.js | 2 +- packages/analytics-core/src/modules/track.js | 1 + packages/analytics-core/src/pluginTypeDef.js | 68 ++++++++++++++++++-- 4 files changed, 75 insertions(+), 16 deletions(-) diff --git a/packages/analytics-core/src/index.js b/packages/analytics-core/src/index.js index c1683393..0b71d34f 100644 --- 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 = { @@ -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 index 97b293d5..154ba27e 100644 --- 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 index d14641f5..1d76c16d 100644 --- a/packages/analytics-core/src/modules/track.js +++ b/packages/analytics-core/src/modules/track.js @@ -2,6 +2,7 @@ import EVENTS from '../events' import serialize from '../utils/serialize' + // Track State const initialState = { last: {}, diff --git a/packages/analytics-core/src/pluginTypeDef.js b/packages/analytics-core/src/pluginTypeDef.js index bf660429..73808436 100644 --- a/packages/analytics-core/src/pluginTypeDef.js +++ b/packages/analytics-core/src/pluginTypeDef.js @@ -1,12 +1,70 @@ +/** + * @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 {Object.} 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.userId + * @param {Object.} arg.payload.traits + * @return {void} + */ + +/** + * @callback PluginInitializeFunction + * @param {Object} arg + * @param {Object} arg.config config from the plugin spec + * @param {AnalyticsInstance} arg.instance analytics instance + * @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 */