Add new buffered methods, improve types

.changeset/grumpy-oranges-stare.md

@@ -0,0 +1,5 @@
+---
+'@segment/analytics-next': minor
+---
+
+Add 'screen', 'register', 'deregister', 'user' method and 'VERSION' property on AnalyticsBrowser. Allow buffering of 'screen', 'register', 'deregister' methods for snippet users.

examples/standalone-playground/pages/index-local-batched.html

@@ -36,6 +36,9 @@
           else {
             analytics.invoked = !0
             analytics.methods = [
+              'screen',
+              'register',
+              'deregister',
               'trackSubmit',
               'trackClick',
               'trackLink',

examples/standalone-playground/pages/index-local-csp.html

@@ -37,6 +37,9 @@
           else {
             analytics.invoked = !0
             analytics.methods = [
+              'screen',
+              'register',
+              'deregister',
               'trackSubmit',
               'trackClick',
               'trackLink',

examples/standalone-playground/pages/index-local-errors.html

@@ -36,6 +36,9 @@
           else {
             analytics.invoked = !0
             analytics.methods = [
+              'screen',
+              'register',
+              'deregister',
               'trackSubmit',
               'trackClick',
               'trackLink',

examples/standalone-playground/pages/index-local-track-link.html

@@ -36,6 +36,9 @@
           else {
             analytics.invoked = !0
             analytics.methods = [
+              'screen',
+              'register',
+              'deregister',
               'trackSubmit',
               'trackClick',
               'trackLink',

examples/standalone-playground/pages/index-local.html

@@ -36,6 +36,9 @@
           else {
             analytics.invoked = !0
             analytics.methods = [
+              'screen',
+              'register',
+              'deregister',
               'trackSubmit',
               'trackClick',
               'trackLink',

examples/standalone-playground/pages/index-remote.html

@@ -33,6 +33,9 @@
           else {
             analytics.invoked = !0
             analytics.methods = [
+              'screen',
+              'register',
+              'deregister',
               'trackSubmit',
               'trackClick',
               'trackLink',

packages/browser/package.json

@@ -43,7 +43,7 @@
   "size-limit": [
     {
       "path": "dist/umd/index.js",
-      "limit": "25.85 KB"
+      "limit": "25.9 KB"
     }
   ],
   "dependencies": {

packages/browser/qa/__fixtures__/snippets.ts

@@ -13,6 +13,9 @@ export function next(writekey: string, obfuscate: boolean) {
           else {
             analytics.invoked = !0
             analytics.methods = [
+              'screen',
+              'register',
+              'deregister',
               'trackSubmit',
               'trackClick',
               'trackLink',
@@ -84,6 +87,9 @@ export function classic(writekey: string) {
       else {
         analytics.invoked = !0
         analytics.methods = [
+          'screen',
+          'register',
+          'deregister',
           'trackSubmit',
           'trackClick',
           'trackLink',

packages/browser/src/browser/__tests__/integration.test.ts

@@ -3,7 +3,6 @@ import { Context } from '@/core/context'
 import { Plugin } from '@/core/plugin'
 import { JSDOM } from 'jsdom'
 import { Analytics } from '../../core/analytics'
-import { Group } from '../../core/user'
 import { LegacyDestination } from '../../plugins/ajs-destination'
 import { PersistedPriorityQueue } from '../../lib/priority-queue/persisted'
 // @ts-ignore loadLegacySettings mocked dependency is accused as unused
@@ -258,7 +257,7 @@ describe('Initialization', () => {
     )
 
     expect(ajs.user().options.persist).toBe(false)
-    expect((ajs.group() as Group).options.persist).toBe(false)
+    expect(ajs.group().options.persist).toBe(false)
   })
 
   it('fetch remote source settings by default', async () => {
@@ -536,11 +535,11 @@ describe('Group', () => {
       writeKey,
     })
 
-    const group = analytics.group() as Group
+    const group = analytics.group()
 
-    const ctx = (await analytics.group('coolKids', {
+    const ctx = await analytics.group('coolKids', {
       coolKids: true,
-    })) as Context
+    })
 
     expect(ctx.event.groupId).toEqual('coolKids')
     expect(ctx.event.traits).toEqual({ coolKids: true })

packages/browser/src/browser/__tests__/typedef-tests/analytics-browser.ts

@@ -2,6 +2,7 @@ import { Analytics } from '@/core/analytics'
 import { Context } from '@/core/context'
 import { AnalyticsBrowser } from '@/browser'
 import { assertNotAny, assertIs } from '@/test-helpers/type-assertions'
+import { Group } from '../../../core/user'
 
 /**
  * These are general typescript definition tests;
@@ -54,4 +55,16 @@ export default {
           assertIs<number | [Analytics, Context]>(response)
         })
     },
+
+  'Group should have the correct type': () => {
+    const ajs = AnalyticsBrowser.load({ writeKey: 'foo' })
+    {
+      const grpResult = ajs.group()
+      assertIs<Promise<Group>>(grpResult)
+    }
+    {
+      const grpResult = ajs.group('foo')
+      assertIs<Promise<Context>>(grpResult)
+    }
+  },
 }

packages/browser/src/core/analytics/index.ts

@@ -10,11 +10,18 @@ import {
   UserParams,
 } from '../arguments-resolver'
 import type { FormArgs, LinkArgs } from '../auto-track'
-import { Callback, invokeCallback } from '../callback'
+import { invokeCallback } from '../callback'
 import { isOffline } from '../connection'
 import { Context } from '../context'
 import { Emitter } from '@segment/analytics-core'
-import { EventFactory, Integrations, Plan, SegmentEvent } from '../events'
+import {
+  Callback,
+  EventFactory,
+  Integrations,
+  Plan,
+  EventProperties,
+  SegmentEvent,
+} from '../events'
 import { Plugin } from '../plugin'
 import { EventQueue } from '../queue/event-queue'
 import { CookieOptions, Group, ID, User, UserOptions } from '../user'
@@ -30,6 +37,7 @@ import { version } from '../../generated/version'
 import { PriorityQueue } from '../../lib/priority-queue'
 import { getGlobal } from '../../lib/get-global'
 import { inspectorHost } from '../inspector'
+import { AnalyticsClassic, AnalyticsSnippetCore } from './interfaces'
 
 const deprecationWarning =
   'This is being deprecated and will be not be available in future releases of Analytics JS'
@@ -69,7 +77,15 @@ export interface InitOptions {
   obfuscate?: boolean
 }
 
-export class Analytics extends Emitter {
+/* analytics-classic stubs */
+function _stub(this: never) {
+  console.warn(deprecationWarning)
+}
+
+export class Analytics
+  extends Emitter
+  implements AnalyticsSnippetCore, AnalyticsClassic
+{
   protected settings: AnalyticsSettings
   private _user: User
   private _group: Group
@@ -127,7 +143,7 @@ export class Analytics extends Emitter {
 
     const segmentEvent = this.eventFactory.track(
       name,
-      data as SegmentEvent['properties'],
+      data as EventProperties,
       opts,
       this.integrations
     )
@@ -180,6 +196,8 @@ export class Analytics extends Emitter {
     })
   }
 
+  group(): Group
+  group(...args: UserParams): Promise<DispatchedEvent>
   group(...args: UserParams): Promise<DispatchedEvent> | Group {
     if (args.length === 0) {
       return this._group
@@ -503,58 +521,16 @@ export class Analytics extends Emitter {
     return integrations
   }
 
-  // analytics-classic stubs
-
-  log() {
-    console.warn(deprecationWarning)
-    return
-  }
-
-  addIntegrationMiddleware() {
-    console.warn(deprecationWarning)
-    return
-  }
-
-  listeners() {
-    console.warn(deprecationWarning)
-    return
-  }
-
-  addEventListener() {
-    console.warn(deprecationWarning)
-    return
-  }
-
-  removeAllListeners() {
-    console.warn(deprecationWarning)
-    return
-  }
-
-  removeListener() {
-    console.warn(deprecationWarning)
-    return
-  }
-
-  removeEventListener() {
-    console.warn(deprecationWarning)
-    return
-  }
-
-  hasListeners() {
-    console.warn(deprecationWarning)
-    return
-  }
-
-  // This function is only used to add GA and Appcue, but these are already being added to Integrations by AJSN
-  addIntegration() {
-    console.warn(deprecationWarning)
-    return
-  }
-
-  add() {
-    console.warn(deprecationWarning)
-    return
-  }
+  log = _stub
+  addIntegrationMiddleware = _stub
+  listeners = _stub
+  addEventListener = _stub
+  removeAllListeners = _stub
+  removeListener = _stub
+  removeEventListener = _stub
+  hasListeners = _stub
+  add = _stub
+  addIntegration = _stub
 
   // snippet function
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

packages/browser/src/core/analytics/interfaces.ts

@@ -0,0 +1,106 @@
+import type { Analytics, AnalyticsSettings, InitOptions } from '.'
+import type { Plugin } from '../plugin'
+import type {
+  EventParams,
+  DispatchedEvent,
+  PageParams,
+  UserParams,
+  AliasParams,
+} from '../arguments-resolver'
+import type { Context } from '../context'
+import type { SegmentEvent } from '../events'
+import type { Group, User } from '../user'
+import type { LegacyIntegration } from '../../plugins/ajs-destination/types'
+
+// we can define a contract because:
+// - it gives us a neat place to put all our typedocs (they end up being inherited by the class that implements them).
+// - it makes it easy to reason about what's being shared between browser and node
+
+/**
+ * All of these methods are a no-op.
+ */
+/** @deprecated */
+interface AnalyticsClassicStubs {
+  /** @deprecated */
+  log(this: never): void
+  /** @deprecated */
+  addIntegrationMiddleware(this: never): void
+  /** @deprecated */
+  listeners(this: never): void
+  /** @deprecated */
+  addEventListener(this: never): void
+  /** @deprecated */
+  removeAllListeners(this: never): void
+  /** @deprecated */
+  removeListener(this: never): void
+  /** @deprecated */
+  removeEventListener(this: never): void
+  /** @deprecated */
+  hasListeners(this: never): void
+  /** @deprecated */
+  // This function is only used to add GA and Appcue, but these are already being added to Integrations by AJSN
+  addIntegration(this: never): void
+  /** @deprecated */
+  add(this: never): void
+}
+
+/** @deprecated */
+export interface AnalyticsClassic extends AnalyticsClassicStubs {
+  /** @deprecated */
+  initialize(
+    settings?: AnalyticsSettings,
+    options?: InitOptions
+  ): Promise<Analytics>
+
+  /** @deprecated */
+  noConflict(): Analytics
+
+  /** @deprecated */
+  normalize(msg: SegmentEvent): SegmentEvent
+
+  /** @deprecated */
+  readonly failedInitializations: string[]
+
+  /** @deprecated */
+  pageview(url: string): Promise<Analytics>
+
+  /**  @deprecated*/
+  readonly plugins: any
+
+  /** @deprecated */
+  readonly Integrations: Record<string, LegacyIntegration>
+}
+
+/**
+ * Interface implemented by the snippet ('Analytics')
+ */
+export interface AnalyticsSnippetCore {
+  track(...args: EventParams): Promise<DispatchedEvent>
+  page(...args: PageParams): Promise<DispatchedEvent>
+  identify(...args: UserParams): Promise<DispatchedEvent>
+  group(): Group
+  group(...args: UserParams): Promise<DispatchedEvent>
+  alias(...args: AliasParams): Promise<DispatchedEvent>
+  screen(...args: PageParams): Promise<DispatchedEvent>
+  register(...plugins: Plugin[]): Promise<Context>
+  deregister(...plugins: string[]): Promise<Context>
+  user(): User
+  readonly VERSION: string
+}
+
+/**
+ * Interface implemented by AnalyticsBrowser
+ */
+export interface AnalyticsBrowserCore {
+  track: AnalyticsSnippetCore['track']
+  page: AnalyticsSnippetCore['page']
+  identify: AnalyticsSnippetCore['identify']
+  group(): Promise<Group> // Different than AnalyticsSnippetCore ^
+  group(...args: UserParams): Promise<DispatchedEvent>
+  alias: AnalyticsSnippetCore['alias']
+  screen: AnalyticsSnippetCore['screen']
+  register: AnalyticsSnippetCore['register']
+  deregister: AnalyticsSnippetCore['deregister']
+  user(): Promise<User> // Different than AnalyticsSnippetCore ^
+  readonly VERSION: AnalyticsSnippetCore['VERSION']
+}