Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refine JSDoc / TypeScript types for plugins #324

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

dobesv
Copy link
Contributor

@dobesv dobesv commented Oct 7, 2022

Starting working on improving the JSDoc / TypeScript a bit so that I could better understand the types here.

I'm not totally sure these are quite correct.

Also - can plugins define all the events defined in events.js ? It seems like the JSDoc currently only lists a few events.

@@ -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
Copy link
Contributor Author

@dobesv dobesv Oct 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This conflicted with the built-in type Storage used for localStorage & sessionStorage so I took the liberty of renaming it while I was in here to fix the TypeScript error I got. Hopefully that's OK.

@dobesv dobesv force-pushed the plugin-types-refinements branch 2 times, most recently from eea7d2f to 6b023a9 Compare October 7, 2022 22:45
* @param {AnalyticsInstance} arg.instance analytics instance
* @param {Object} arg.payload event data
* @param {string} arg.payload.event event name passed to track
* @param {TrackEventProperties} [arg.payload.properties] event properties passed to track
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if this is actually optional. Will the library always supply an object here?


/**
* Track data for overrides
* @typedef {Object.<string>} TrackEventProperties
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a generic map here since there's no predefined fields for this

@dobesv dobesv force-pushed the plugin-types-refinements branch from 6b023a9 to 95a7fa5 Compare October 7, 2022 22:50
@dobesv dobesv force-pushed the plugin-types-refinements branch from 95a7fa5 to 1c26a40 Compare October 7, 2022 22:51
Comment on lines +65 to +69
* @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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should there be one of these for every event named in events.js ?

@dobesv
Copy link
Contributor Author

dobesv commented Oct 7, 2022

Working on this it does feel like maintaining separate .d.ts files would actually be easier than trying to figure out JSDoc magic I need to do in order to produce good TypeScript definitions.

@rene-airtame
Copy link

This would be a very welcome addition as all the plugin methods are typed simply (...params: any[]) => any now.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to add meta, anonymousId and userId as well? I haven't entirely figured which are present in what methods always.

https://getanalytics.io/resources/faq/#do-i-need-to-use-a-plugin

Copy link
Contributor Author

@dobesv dobesv Nov 9, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, maybe? Doesn't seem like this PR is getting any attention from the library maintainer so I'm not sure making any changes to it makes practical sense.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, it seems like issues and PRs are increasing. I'm sure @DavidWells is just busy at the moment. Maybe it's time for a call for maintainers? 🤔

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants