analytics-next
analytics-next copied to clipboard
[feature] Updates AnalyticsNode API
This change is part of the effort to improve using analytics in node.js. The goal is that this library should be able to replace the analytics-node library.
This PR focuses on 2 aspects:
- Defines a node.js-specific analytics interface that represents the APIs available in node.js
- Updates the
Analyticsclass so that it can function without maintaining user/group state.
Node.js interface
The AnalyticsNodeJs interface exposes the analytics API that works in node.js. If we continued exporting Analytics from AnalyticsNode.load() directly then we'd have 2 issues:
- Many APIs are either only supported in the browser (e.g.
trackLink) or were included for backwards compatibility with analytics.js classic and have been deprecated (e.g.use). - Analytics assumes that 1 user/group is being used at a time.
This change addresses both these points by only exposing the APIs that work in node.js and enforcing that either a userId or anonymousId is provided in each operation that generates an event.
Analytics sans users
The Analytics class assumed that there would always be a single user (anonymous and/or known) at a time and would automatically keep track of the user details so our customers wouldn't have to. This causes an issue when using Analytics to a server environment because it's common to be handling multiple users concurrently.
The simplest way I found to handle this was to support disabling the User and Group objects so that they didn't store any state. This didn't require changing any method signatures. I thought of some alternatives such as:
- creating a
UserLike/GroupLikeinterface to pass to Analytics instead of classes so we can pass in a no-op implementation in node.js - Subclassing
User/GroupwithNullUserandNullGroupThe 1st ended up leading to broader API changes that would leak into the browser usage unless we did our own type casting. The 2nd option is safe but caused some extra work to be done in the constructor.
Notes
I've set this PR to target the feature-node-uplift branch. Since we are changing the API for the node.js Analytics, this is technically a breaking change and we should do a major version bump when we decide to ship this. I don't want to block releasing from the main branch while this work is ongoing.
Note: I believe some tests are sometimes timing out because validation errors are getting retried. I believe validation errors should fail without retries since the data being validated doesn't change between attempts. I'll update this PR with those changes.