Add new buffered methods, improve types

[silesky]

This PR:

• Adds 'screen', 'register', 'deregister', 'user' method and 'VERSION' property on AnalyticsBrowser. 🎸
• Allows buffering of 'screen', 'register', 'deregister' methods for snippet users. 🎹
• Improves typing -- e.g better names, add overloads 🎷

Outstanding todo: update the actual UI snippet (the one that shows up on app.segment.com?) so that the copypasta from includes 'screen', 'register', and 'deregister' ⛑️

😢 Because of some differences in return types between AnalyticsBrowser and Analytics (AnalyticsBrowser always being async, while Analytics is inconsistent in that regard) the dream of a unified AnalyticsCore interface between Analytics and AnalyticsBrowser is on hold.

It’s IMO advisable to not try to obsess over strict sharing of a public interfaces, as that common abstraction does not seem possible, and it can in addition become hard to maintain either for the legacy behavior of one system or due to subtle differences between platforms. Ultimately, our API is just a bags of methods and we want to evolve and be nimble, and not hamstring ourselves.

We can continue to share models and types where appropriate.

[changeset-bot]

🦋 Changeset detected

Latest commit: 822b057

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@segment/analytics-next	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chrisradek]

Love seeing the addition of more methods on the buffered Analytics class! Had some pretty minor comments.

[chrisradek]

This might be too strict - we have some users passing in an instance of a class as event properties and TypeScript will complain that the class doesn't have the index signature.

[silesky]

I don’t think the official typescript interface should support people passing “any class”, since it’s AFAIK not possible in TS to distinguish between an intentionally passed class instance and an accidentally-passed function or array — the problem with the “object” type is that so much in JS is an object.

I think we should write the typescript API to encourage people to do things idiomatically, i.e create a toJSON() on their class or construct an object literal using class properties via {…new MyClass()} — but accepting any class seems like smell to me — and, as a consumer, the looseness of object would be a source of confusion (and uncaught typescript bugs).

Since this isn’t a runtime change, and is a non breaking change (in the Typescript “correctness” sense) that affects a super minority of npm typescript users, I feel good about this. They are always free to keep using vanilla JS and ignore or unsafely cast in their own calling code, but I want us to lead them into the light — and also do a better job of using Typescript to clarify and document the API (e.g using overloads).

/my two cents